🇰🇷 한국어 버전

vibe-ready

A CLI tool that analyzes how ready a repository is for vibe coding (AI agent-based development).

Using Claude Agent SDK or Codex CLI, an LLM directly explores the repository, scores it across 7 categories, and provides an overall grade along with specific improvement recommendations. Commit-log stats (issue reference rate, PR workflow patterns) are pre-extracted and injected into the analysis prompt before the LLM call.

Installation & Usage

Development-process diagnosis

--diagnose adds evidence-based process diagnosis with up to three actionable improvements, source/PR/CI references, team questions, and follow-up comparison. It supports service, library, CLI, data, and general repositories. The existing scoring command remains unchanged.

vibe-ready . --diagnose --goal "Shorten feedback cycles" --save-diagnosis ../diagnosis.json
vibe-ready . --diagnose --provider none --profile cli --interview
vibe-ready . --diagnose --goal "Shorten feedback cycles" --baseline ../diagnosis.json --output ../follow-up.md
vibe-ready . --diagnosis-file ../diagnosis.json --json

The default window is 30 days with at most 30 PR/MRs and 30 CI runs. Remote reads use GH_TOKEN/GITHUB_TOKEN or GITLAB_TOKEN; missing access appears as a collection gap. --provider none disables remote API collection but still calls the selected analysis engine. Snapshot replay (--diagnosis-file) needs no model or network access. Target repositories are read-only: output files must be outside the target, use new filenames, and have an existing parent directory. Nothing is saved implicitly.

To answer saved questions, use --diagnosis-file ../diagnosis.json --answers ../answers.json (calls the model and requires the original repository/commit). See diagnosis options, interview format, and metric limitations.

Quick Start (via npm)

# Run directly without installation
npx vibe-ready .

# Or install globally
npm install -g vibe-ready

# Then use anywhere
vibe-ready /path/to/repo
vibe-ready . --verbose
vibe-ready . --markdown
vibe-ready . --pdf report.pdf
vibe-ready . --category "하네스 엔지니어링"

Prerequisite: The default Claude engine requires authenticated Claude Code. For Codex, install the latest CLI and sign in with ChatGPT; existing Codex authentication is reused (official authentication guide). No extra npm dependency or separate API key is required by this integration.

Select an analysis engine

npm install -g @openai/codex@latest
codex login
vibe-ready . --engine codex
vibe-ready . --diagnose --engine codex --provider none --timeout 180

--engine claude|codex selects who performs the analysis. --agent still selects the coding-agent harness being evaluated; --provider still selects GitHub/GitLab evidence. Selection order is CLI → config engine → claude. For a persistent default, .vibeready.json may contain only {"engine":"codex"}; default scoring categories are inherited.

Codex CLI 0.155.1 is the tested integration version. It runs codex exec with a read-only sandbox and isolated configuration. Explicit --max-budget and --max-turns are Claude-only and rejected for Codex; their displayed Claude defaults are not Codex limits. --timeout works with both engines. Scoring caches are separated by engine. Diagnosis snapshots preserve the engine, resume with that engine, and reject cross-engine baselines. Older snapshots without an engine mean Claude. Plain snapshot replay needs neither CLI installed.

For Developers (from source)

git clone https://github.com/roboco-io/vibe-ready-cli.git
cd vibe-ready-cli
npm install
npm run build

# Run from source
node dist/index.js /path/to/repo
node dist/index.js . --verbose --markdown
node dist/index.js . --pdf report.pdf --verbose

# Run tests
npm test

CLI Options

Option	Default	Description
[path]	.	Path to the repository to analyze
--engine <engine>	claude	Analysis engine (claude or codex); overrides config
-v, --verbose	-	Show detailed analysis findings
-m, --markdown	-	Output in Markdown format
-c, --category <names>	all	Analyze specific categories only (comma-separated)
--agent <tool>	auto-detect	Limit Harness Engineering scoring to one coding agent: claude, codex, cursor, or copilot. When set, other agents' files (AGENTS.md, .cursorrules, etc.) are ignored — never penalized
-b, --branch <branches>	current	Analyze specific branches (comma-separated, with comparison report)
-o, --output <file>	-	Save report to file (.md extension auto-detected)
--pdf <file>	-	Export report as PDF (requires pandoc + xelatex)
--no-cache	-	Skip cache and force fresh analysis
--max-turns <n>	200	Claude-only agent turn limit
--max-budget <n>	2.00	Claude-only budget in USD
--no-max-budget	-	Run Claude without a budget cap
--timeout <n>	120	Timeout in seconds

Architecture

Analysis Categories

Must-Have — Verification First

Category	Weight	What's Analyzed
Test Coverage	20%	Test configuration, test files, coverage setup, test scripts
CI/CD	20%	GitHub Actions, GitLab CI, and other pipeline configurations and contents
Hook-based Validation	20%	husky, lint-staged, pre-commit, commitlint, etc.

Nice-to-Have

Category	Weight	What's Analyzed
Repository Structure	10%	Directory organization, dependency management, configuration separation
Documentation Level	10%	README, CONTRIBUTING, API docs, architecture docs
Harness Engineering	10%	Single-agent harness completeness — context + safety + extensions for one agent (e.g. Claude Code: CLAUDE.md + .claude/settings.json + skills/commands; or Codex: AGENTS.md). Supporting one agent fully = full marks; multi-agent support is a tiebreaker bonus only
Issue Tracking Integration	10%	Issue reference rate in commits (GitHub #N / Jira ABC-123), PR workflow patterns

Configuration

Create a .vibeready.json in your repo root to customize evaluation:

{
  "categories": [
    { "name": "Test Coverage", "tier": "must", "weight": 0.25 },
    { "name": "CI/CD", "tier": "must", "weight": 0.25 },
    { "name": "Security", "tier": "must", "weight": 0.20,
      "description": "Evaluate repository security settings",
      "checkpoints": [
        ".env is in .gitignore",
        "No hardcoded secrets in source code",
        "Dependency vulnerability scanning configured"
      ]
    },
    { "name": "Documentation", "tier": "nice", "weight": 0.15 },
    { "name": "Harness Engineering", "tier": "nice", "weight": 0.15 },
    { "name": "Security", "tier": "optional", "bonusCap": 5,
      "description": "Optional item: never lowers the grade; adds up to 5 bonus points if present",
      "checkpoints": [".env is in .gitignore", "Dependency vulnerability scanning configured"]
    }
  ],
  "penaltyRule": {
    "enabled": true,
    "maxGrade": "C",
    "condition": "any must-have category F"
  },
  "agent": "claude"
}

• Override default category weights and tiers
• Add custom categories with description and checkpoints
• Tiers: must (F caps the overall grade at C), nice (counts toward the weighted average), optional (never lowers the grade — adds bonus points proportional to its score, up to bonusCap, which can raise the total)
• Adopt / skip / optional: include a category to adopt it; remove it from categories to skip it (excluded from analysis); set tier: "optional" with a bonusCap to make it a bonus-only item
• Weights are auto-normalized if they don't sum to 1.0 (optional categories are excluded from normalization and use bonusCap instead of weight)
• "agent" pins Harness Engineering to one coding agent (claude / codex / cursor / copilot). Omit it for auto-detection. The --agent CLI flag overrides this field.
• Supported filenames: .vibeready.json, .vibeready.config.json, vibeready.config.json
• See .vibeready.example.json for a full example

Output Example

═══════════════════════════════════════════════════
  🎵 Vibe Ready Score
═══════════════════════════════════════════════════

  Overall Score: 72 / 100  Grade: C

  Results by Category
  ─────────────────────────────────────────────────
  Category               Type      Score    Grade
  ─────────────────────────────────────────────────
  Test Coverage          Must      85       B
  CI/CD                  Must      90       A
  Hook-based Validation  Must      45       F
  Repository Structure   Nice      80       B
  Documentation Level    Nice      70       C
  Harness Engineering     Nice      60       D
  Issue Tracking Integration Nice   75       C
  ─────────────────────────────────────────────────

  ⚠ Must-Have category F grade: Hook-based Validation → Overall grade capped at C

  Recommendations
  ✖ [Hook-based Validation] pre-commit hook is not configured
    → Install husky and configure lint-staged

Scoring Model

• Each category: 0–100 points
• Overall score: weighted average (Must-Have 60%, Nice-to-Have 40%)
• Grades: A(90+), B(80+), C(70+), D(50+), F(<50)
• Penalty: If any Must-Have category receives an F, the overall grade is capped at C

CLI Options

Option	Default	Description
[path]	.	Path to the repository to analyze
-v, --verbose	-	Show detailed analysis results (rawFindings)
--max-turns <n>	200	Claude-only maximum agent turns
--max-budget <n>	2.00	Claude-only maximum cost (USD)
--no-max-budget	-	Run Claude without a budget cap
--timeout <n>	120	Timeout (seconds)

Known Limitations

• LLM non-determinism: Repeated analysis of the same repo may vary by ±5–10 points
• Estimated cost: Varies with repo size; large repositories can exceed $0.50 per run. When the budget is exceeded, the error shows the spent cost and a suggested --max-budget value. With Claude Code subscription auth, this is an estimated API-price cost, not a separate charge
• Read-Only analysis: The target repository is never modified
• MVP limitations: Currently supports single repo + terminal output only. JSON/HTML output and batch analysis are planned for future versions

Development

npm install
npm run build
npm test

Tutorial

The entire process of building this project has been documented as a vibe coding tutorial:

Vibe Coding Tutorial — 5 chapters, from idea → deep interview → implementation → harness engineering → contribution framework

Chapter	Duration	Key Content
01. Idea & Initialization	~10 min	Ideation doc, /init
02. Deep Interview	~25 min	10-round Q&A, ambiguity 100%→19%
03. MVP Implementation	~40 min	5 modules based on Claude Agent SDK
04. Harness Engineering	~15 min	CLAUDE.md, AGENTS.md, settings.json
05. Contribution Guide + Skills	~10 min	CONTRIBUTING.md, contribution-guard skill

Harness Engineering

This project applies harness engineering so that AI agents (such as Claude Code) can effectively understand and work with the codebase.

Components

File	Role
AGENTS.md	Single source of agent instructions — tech stack, build commands, architecture, data flow, scoring rules, coding/test/commit conventions, extension points, prohibited actions
CLAUDE.md	Imports AGENTS.md (@AGENTS.md) so Claude Code loads the same instructions
.claude/settings.json	Agent permissions and hook configuration — allowed tools, PreCommit auto-validation (build+test)

Design Principles

• Immediately graspable context: AGENTS.md is written so agents can understand the project structure, build process, and architecture on their first turn; keeping one file avoids drift between Claude Code and Codex instructions
• Safe autonomous operation: .claude/settings.json auto-allows only read tools and build/test commands, enabling agents to explore and verify autonomously without destructive behavior
• Pre-commit auto-validation: A PreCommit hook enforces npm run build && npm test, preventing agents from committing broken code
• Built-in extension guide: AGENTS.md specifies how to add new check modules, output formats, CI gate modes, and more, so agents can add features following consistent patterns

Deep Interview-based Context Collection

To reduce requirement ambiguity in the early stages of the project, a deep interview was conducted. Through 10 rounds of structured Q&A, goals, constraints, and acceptance criteria were clarified. The results are preserved in .omc/specs/deep-interview-*.md and used as context for subsequent work.

License

MIT