codebase-readiness

コードベースの対応状況評価

エージェント対応コードベース評価を実施します。コードベースが自律型AIエージェントによる作業をどの程度支援できるかを採点し、週に1,000件以上のAI生成プルリクエストを達成しているStripeをベンチマークとして評価します。

以下のフェーズを順番に進めます。

---

フェーズ 1：コードベースの事前調査

評価パスを開始する前に、事前調査スクリプトを実行してプロジェクトのメタデータを収集します。現在のエージェント内で直接実行してください。

bash scripts/recon.sh

スクリプトは、このスキルのディレクトリを基準にした scripts/recon.sh にあります。

出力を確認した後、コードベースのスナップショットを作成します。

## Codebase Snapshot: [Project Name]

- **Primary language/framework**: [detected]
- **Language tier**: [statically-typed | dynamically-typed | gradually-typed]
  - Statically-typed: TypeScript, Go, Java, Scala, Rust, C#, Kotlin
  - Dynamically-typed: Ruby, Python (unannotated), JavaScript/Node.js, PHP
  - Gradually-typed: Python with mypy/Pydantic, TypeScript with strict:false
- **Commit count**: [X]
- **Contributors**: [X]
- **Source files**: [X]
- **Test files**: [X] (ratio: X%)
- **CI/CD**: [platform(s) found or none]
- **Agent instructions**: [AGENTS.md / CLAUDE.md / both, with canonical path and symlink status / absent]
- **Domain context**: [CONTEXT.md / CONTEXT-MAP.md / docs/DOMAIN.md / absent; ADR location and count]
- **Linting config**: [tools found or none]
- **Quality gates**: [copy the `Suggested Gate Maturity Level: Lx -- ...` line from recon output, e.g. "L0 -- no complexity, duplication, or dead-code tooling detected"]
- **README**: [present, X lines / absent]

Quality gates の行は必須です。 recon.sh は === QUALITY GATES === セクションの末尾に Suggested Gate Maturity Level: Lx -- <reason> を出力します。そのレベルと理由をスナップショットの Quality gates 行に記載します。次に references/quality-gates.md を読み、上記の詳細な根拠（L0 なし、L1 レポートのみ、L2 しきい値、L3 回帰を考慮したブロック、L4 ガバナンスあり）と照らし合わせて提案を確認します。ヒューリスティックと根拠が矛盾する場合に限り、行を変更し、その理由を説明してください。この行がない状態で評価パスを開始してはいけません。各パスはゲートの根拠のうち自身に割り当てられた部分のみを採点し、レベルはスナップショットから読み取ります。行がないと、各パスが独自にレベルを再判定するため、4つの評価軸で判定が食い違います。

スナップショットから PRIMARY_LANGUAGE と LANGUAGE_TIER を特定します。これらの値を使って読み込む言語リファレンスファイルを決定します。

対応言語： ruby、python、php、typescript、javascript、go、java、scala、rust。

主言語が対応リストにない場合は、対応言語をユーザーに伝えます。ユーザーの同意を得て最も近い対応言語のファイルを使って進めるか、言語固有の基準を使わずに各評価軸を評価するかを提案してください。

---

フェーズ 2：4つの評価パスを実行

プロンプトの構成

各パスには、リファレンスファイルを組み合わせて作成したプロンプトを渡します。

1. 言語ファイルを読む — references/languages/{PRIMARY_LANGUAGE}.md
2. 評価軸ファイルを読む — 各パスには、references/dimensions/ の関連する評価軸ファイルを渡します
3. 共通のゲートリファレンスを読む — references/quality-gates.md は、テストとCI、コード品質、アーキテクチャの各パスに渡します（各パスは異なる部分を採点し、クレジットの帰属表によって二重計上を防ぎます）
4. プロンプトを構成する — 役割の前置き＋コードベースのスナップショット＋評価軸の内容＋quality-gates の内容＋言語固有の内容＋出力指示

各リファレンスファイルを読み込んだ後、その内容を各パスのプロンプトにインラインで含めます。言語ファイルを含める際は、各パスに対し、割り当てられた評価軸に関連するセクションのみを参照するよう指示してください。

パスの実行方法

以下の4つのパスをすべて実行してください。ランタイムが対応している場合は、同時実行を優先してください。対応していない場合は、現在のエージェント内で1つずつ実行してください。並列実行ができないことを理由にパスを省略したり、特定ベンダー専用のツールを必須にしたりしないでください。

• 対応している場合は並列実行。 フェーズ3に進む前に、4つのパスをすべて同時に開始し、すべての結果が返るまで待ちます。Claude Codeでは、4つのAgentツール呼び出し（subagent_type: general-purpose）を1つのメッセージで送信します。Cursor、Codex、その他のエージェントでは、そのランタイムのサブエージェントまたは並列タスクの仕組みを使います。
• 逐次実行へのフォールバック。 ランタイムがサブエージェントや並列タスクに対応していない場合は、現在のエージェント内で4つのパスを順番に実行します。1つのパスを完了して採点結果を保持してから、次のパスを開始します。

どちらの場合も、各パスには同じ構成のプロンプトを渡します。

パスのプロンプト

---

パス 1：テストと CI

読み込んで含めるディメンションファイル：

• references/dimensions/test-foundation.md
• references/dimensions/feedback-loops.md
• references/quality-gates.md（フィードバックループの範囲のみ：実行可能性、再現性、ゲートテスト）

プロンプト：

You are a senior engineering consultant specializing in test infrastructure and developer feedback loops. Assess how well this codebase's testing and CI/CD setup supports autonomous AI agent work.

Codebase Snapshot:

[INSERT FULL CODEBASE SNAPSHOT]

LANGUAGE_TIER: [static | dynamic | gradual]
PRIMARY_LANGUAGE: [Ruby | Python | TypeScript | Go | etc.]

## Assessment Instructions

Use the dimension guides and language-specific criteria below to assess two dimensions: **Test Foundation** and **Feedback Loops**. Run the evidence-gathering commands from both the dimension guides and the language file to collect data. Score each dimension 0-100 following the scoring bands, then apply any score modifiers.

Reference only the Test Foundation and Feedback Loops sections from the language file.

### Dimension Guide: Test Foundation

[INSERT CONTENT OF references/dimensions/test-foundation.md]

### Dimension Guide: Feedback Loops

[INSERT CONTENT OF references/dimensions/feedback-loops.md]

### Shared Reference: Regression-Aware Quality Gates

Use the Gate Maturity Level from the snapshot. Score only the Feedback Loops slice from the credit-ownership table (actionability, reproducibility, gate tests). Do not credit tool coverage or blocking behaviour here.

[INSERT CONTENT OF references/quality-gates.md]

### Language-Specific Criteria

[INSERT CONTENT OF references/languages/{PRIMARY_LANGUAGE}.md]

Return the full scored assessment for both dimensions in the output format specified in each dimension guide. Be specific — reference actual files, counts, and statistics.

---

パス 2：ドキュメント

読み込んで含めるディメンションファイル：

• references/dimensions/documentation.md

プロンプト：

You are a senior engineering consultant specializing in developer experience and knowledge management. Assess how well this codebase's documentation enables AI agents to work autonomously without constant human clarification.

Codebase Snapshot:

[INSERT FULL CODEBASE SNAPSHOT]

LANGUAGE_TIER: [static | dynamic | gradual]
PRIMARY_LANGUAGE: [Ruby | Python | TypeScript | Go | etc.]

## Assessment Instructions

Use the dimension guide and language-specific criteria below to assess one dimension: **Documentation & Context**. Run the evidence-gathering commands to collect data. Score 0-100 following the scoring bands.

Reference only the Documentation sections from the language file.

### Dimension Guide: Documentation & Context

[INSERT CONTENT OF references/dimensions/documentation.md]

### Language-Specific Criteria

[INSERT CONTENT OF references/languages/{PRIMARY_LANGUAGE}.md]

Return the full scored assessment in the output format specified in the dimension guide. Be specific — reference actual files found. Treat the project's canonical agent instruction entrypoint as primary: AGENTS.md when CLAUDE.md is its symlink, otherwise the existing root instruction file. Assess conflicting duplicate files as a coherence risk.

---

パス 3：コード品質

読み込んで含めるディメンションファイル：

• references/dimensions/code-clarity.md
• references/dimensions/consistency.md
• references/quality-gates.md（コードの明瞭性の範囲：構造的カバレッジ、一貫性の範囲：リンター負債の扱い）

プロンプト：

You are a senior engineering consultant specializing in code quality and developer tooling. Assess how navigable and consistent this codebase is for AI agents — agents perform better in codebases with small, focused files and enforced conventions.

Codebase Snapshot:

[INSERT FULL CODEBASE SNAPSHOT]

LANGUAGE_TIER: [static | dynamic | gradual]
PRIMARY_LANGUAGE: [Ruby | Python | TypeScript | Go | etc.]

## Assessment Instructions

Use the dimension guides and language-specific criteria below to assess two dimensions: **Code Clarity** and **Consistency & Conventions**. Run the evidence-gathering commands from both the dimension guides and the language file to collect data. Score each dimension 0-100 following the scoring bands.

Reference only the Code Clarity and Consistency sections from the language file.

### Dimension Guide: Code Clarity

[INSERT CONTENT OF references/dimensions/code-clarity.md]

### Dimension Guide: Consistency & Conventions

[INSERT CONTENT OF references/dimensions/consistency.md]

### Shared Reference: Regression-Aware Quality Gates

Use the Gate Maturity Level from the snapshot. Code Clarity credits which structural properties (complexity, duplication, dead code) are covered and whether each is blocked at L3+. Consistency credits lint/format enforcement and how lint legacy debt is treated. Do not credit CI ergonomics or baseline governance in either dimension.

[INSERT CONTENT OF references/quality-gates.md]

### Language-Specific Criteria

[INSERT CONTENT OF references/languages/{PRIMARY_LANGUAGE}.md]

Return the full scored assessment for both dimensions in the output format specified in each dimension guide. Be specific — reference actual files and line counts.

---

パス 4：アーキテクチャ

読み込んで含めるディメンションファイル：

• references/dimensions/type-safety.md
• references/dimensions/architecture-clarity.md
• references/dimensions/change-safety.md
• references/quality-gates.md（変更安全性の範囲のみ：ブロッキングの意味論とベースラインのガバナンス）

プロンプト：

You are a senior engineering consultant specializing in software architecture and developer safety systems. Assess how safely and predictably AI agents can modify this codebase — guard rails vary by language: type systems for statically-typed languages, contract/test systems for dynamically-typed ones.

Codebase Snapshot:

[INSERT FULL CODEBASE SNAPSHOT]

LANGUAGE_TIER: [static | dynamic | gradual]
PRIMARY_LANGUAGE: [Ruby | Python | TypeScript | Go | etc.]

## Assessment Instructions

Use the dimension guides and language-specific criteria below to assess three dimensions: **Type Safety**, **Architecture Clarity**, and **Change Safety**. Run the evidence-gathering commands from both the dimension guides and the language file to collect data. Score each dimension 0-100 following the scoring bands, then apply any score modifiers. Apply the language-appropriate Type Safety rubric based on LANGUAGE_TIER.

Reference only the Type Safety, Architecture, and Change Safety sections from the language file.

### Dimension Guide: Type Safety

[INSERT CONTENT OF references/dimensions/type-safety.md]

### Dimension Guide: Architecture Clarity

[INSERT CONTENT OF references/dimensions/architecture-clarity.md]

### Dimension Guide: Change Safety

[INSERT CONTENT OF references/dimensions/change-safety.md]

### Shared Reference: Regression-Aware Quality Gates

Use the Gate Maturity Level from the snapshot. Score only the Change Safety slice: whether CI blocks new or worsened structural debt (L3+) and how the baseline is governed. Do not credit tool selection or CI ergonomics here.

[INSERT CONTENT OF references/quality-gates.md]

### Language-Specific Criteria

[INSERT CONTENT OF references/languages/{PRIMARY_LANGUAGE}.md]

Return the full scored assessment for all three dimensions in the output format specified in each dimension guide. Be specific — reference actual files, line counts, and git statistics.

---

次に進む前に、4つすべてのパスからの応答を待ってください。順次実行の場合は、4つ目のパスが完了した時点で条件を満たします。

---

フェーズ 3：スコアの計算

重みは言語に応じて変わります。コードベースのスナップショットにある LANGUAGE_TIER に基づいて、適切な表を選択してください。

動的型付け言語（Ruby、Python、JavaScript、PHP）

動的型付け言語では、テストが型システムの役割を果たします。テスト基盤の重みを高くし、型安全性では型チェッカーではなく、コントラクトとインターフェースの明瞭さを評価します。

ディメンション	重み	エージェントスコア	加重スコア
テスト基盤	25%	XX/100	XX
ドキュメントとコンテキスト	15%	XX/100	XX
コードの明瞭性	15%	XX/100	XX
アーキテクチャの明瞭性	15%	XX/100	XX
フィードバックループ	10%	XX/100	XX
型安全性*	10%	XX/100	XX
一貫性と規約	5%	XX/100	XX
変更安全性	5%	XX/100	XX

*動的型付け言語における型安全性＝コントラクト（dry-rb、Pydantic）、ActiveRecord/Eloquent のバリデーション、Form Requests、PHPStan/Larastan、Result パターンの一貫性を指します。コンパイル型チェッカーがないことは減点対象になりません。

静的型付け言語（TypeScript、Go、Java、Scala、Rust）

ディメンション	重み	エージェントスコア	加重スコア
型安全性	20%	XX/100	XX
テスト基盤	15%	XX/100	XX
ドキュメントとコンテキスト	15%	XX/100	XX
コードの明瞭性	15%	XX/100	XX
アーキテクチャの明瞭性	15%	XX/100	XX
フィードバックループ	10%	XX/100	XX
一貫性と規約	5%	XX/100	XX
変更安全性	5%	XX/100	XX

総合スコア =（エージェントスコア × 重み）の合計

スコア帯：

• 85-100：エージェント対応 — コードベースはエージェントによる自律的な作業をサポートします
• 70-84：エージェント支援 — エージェントは人間の監督があれば効果的に作業できます
• 50-69：エージェント監督必須 — マージ前にエージェントの成果を十分にレビューする必要があります
• 30-49：エージェント利用注意 — まず基盤の改善が必要です
• 0-29：エージェント非対応 — エージェントによる作業の前に大幅な投資が必要です

---

フェーズ 4：レポートの作成

assets/report-template.md からレポートのテンプレートを読み込みます。各パスの結果と、フェーズ 3 でコードベースの LANGUAGE_TIER に一致する重みテーブルを使ってテンプレートに記入します。

コードベースのスナップショットは、Quality gates 行も含め、各パスに渡されたものと完全に同じ内容でレポートに含めてください。また、その行を Quality Gate Maturity セクションでも一字一句そのまま繰り返してください。スナップショットとセクションの内容に食い違いがあってはなりません。

重要： フェーズ 3 の該当するテーブル（動的または静的）にある重みを正確に使用してください。重みをハードコードしないでください。重みは言語ティアによって異なります。

完成したレポートを出力します。

---

フェーズ 5：レポートの保存を提案する

レポートを提示した後、次のように尋ねます。

「この評価をプロジェクトのルートに AGENT_READY_ASSESSMENT.md として保存しますか？ 改善状況を長期的に追跡するベースラインとして役立ち、チームとの共有にも便利です。」

ユーザーが承諾した場合、レポート全体を現在のディレクトリにある AGENT_READY_ASSESSMENT.md に書き込みます。

---

フェーズ 6：CI 統合の推奨

保存後（またはユーザーが保存を辞退した場合）、ゲート成熟度レベルが L0～L2 であれば、agent-ready プラグインの quality-gates モードを使うと、プロジェクトのネイティブツールを活用した回帰対応ゲート（レポート／チェック／ベースラインコマンド、マージベースを考慮した CI、レビュー済みベースライン、テスト）が導入できることを伝えます。

品質ゲートのスコアは [Lx] でした。agent-ready を quality-gates モードで実行すると、新規または悪化した複雑度、重複、デッドコードをブロックするゲートを導入できます。既存の負債を先に一掃する必要はありません。

次に、以下のように伝えます。

継続的な追跡には： btar を CI パイプラインに追加することをご検討ください。検証インフラ（型エラー、リンター違反、テストカバレッジ）を高速かつ決定論的に測定でき、スコアが悪化した場合に PR をゲートできます。この評価は戦略的なベースラインを提供し、btar は最も重要なメトリクスを日々 CI でチェックします。

npm install -g btar
btar analyze .          # クイックスコア：型 + リンター + カバレッジ
btar context generate agents-md  # ビルド／テストコマンドを記載した AGENTS.md を自動生成