codebase-readiness

コードベースのエージェント対応状況評価

エージェント対応コードベース評価を実行します。Stripe のベンチマークである、AI が生成したプルリクエストを週に 1,000 件以上処理することを基準に、コードベースが自律型 AI エージェントの作業をどの程度サポートできるかをスコア化して評価します。

以下のフェーズを順番に進めてください。

---

フェーズ 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]

品質ゲートの行は必須です。 recon.sh は === QUALITY GATES === セクションの最後に Suggested Gate Maturity Level: Lx -- <reason> を出力します。そのレベルと理由をスナップショットの品質ゲートの行に転記してください。次に 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. プロンプトを構成する — 役割の前置き + コードベーススナップショット + 評価軸の内容 + 品質ゲートの内容 + 言語の内容 + 出力指示

Read ツールを使って各リファレンスファイルを読み込み、その内容をエージェントのプロンプトに直接含めてください。言語ファイルを含める際は、各エージェントに対して、割り当てられた評価軸に関連するセクションのみを参照するよう指示してください。

エージェントプロンプト

4 つの Agent ツール呼び出し（subagent_type: general-purpose）を含む単一のメッセージを送信し、すべてのエージェントを同時に起動します。

---

エージェント 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 つすべてのエージェントが完了するのを待ちます。

---

フェーズ 3：スコア計算

重みは言語に応じて変わります。Codebase Snapshot の LANGUAGE_TIER に基づいて適切な表を選択してください。

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

動的型付け言語では、テストが型システムの役割を果たします。Test Foundation の比重が高くなります。Type Safety では、型チェッカーではなく、コントラクトとインターフェースの明確さを評価します。

Dimension	Weight	Agent Score	Weighted
テスト基盤	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）

Dimension	Weight	Agent Score	Weighted
型安全性	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 に一致する重み付けテーブルを使って、テンプレートに記入します。

Codebase Snapshot は、エージェントに提示したものとまったく同じ内容でレポートに含めてください。「Quality gates」の行も含め、その行を「Quality Gate Maturity」セクションにも一字一句そのまま繰り返してください。スナップショットとセクションの内容に食い違いがあってはなりません。

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

記入済みのレポートを出力します。

---

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

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

「この評価をプロジェクトのルートに AGENT_READY_ASSESSMENT.md として保存しますか？ 改善状況を継続的に追跡するための基準として活用でき、チームとの共有にも便利です。」

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

---

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

保存した後（またはユーザーが保存を断った場合）、Gate Maturity Level が L0〜L2 であれば、agent-ready プラグインの quality-gates モードを使うと、プロジェクト標準のツールで回帰を考慮したゲート（report／check／baseline コマンド、merge-base を考慮した CI、レビュー済みのベースライン、テスト）がインストールされることを伝えます。

品質ゲートのスコアは [Lx] でした。quality-gates モードで agent-ready を実行すると、既存の負債のクリーンアップを強制せずに、複雑度、重複、デッドコードの新規発生や悪化を防ぐゲートをインストールできます。

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

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

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