🇰🇷 한국어 버전

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