agent-ready-codebase

エージェント対応コードベース

概要

エージェントがコードベースに苦労している場合、コードベースにもともと存在する弱点が反映され、増幅されています。このスキルは、エージェントの有効性を左右する5つの原則に照らしてコードベースを評価し、それぞれを改善するための具体的な指針を提示します。プロジェクトの言語や技術スタックに合わせて調整します。

"AI Is Forcing Us To Write Good Code" に基づいています。

モードの選択

コンテキストに基づいて、どのモードで動作するかを判断します。

• 監査：ユーザーが既存のコードベースを持っていて、その現状を知りたい場合です。5つすべての原則を評価し、具体的な所見を含む評価表を作成します。
• ガイド：ユーザーが特定の原則を改善したい場合、または新しいプロジェクトを立ち上げたい場合です。対象の技術スタックに合わせた、具体的で実行可能な手順を提示します。

モードが不明な場合は、確認してください。

5つの原則

1. 100％のテストカバレッジ -- すべてのコード行が、実行可能な例によって動作を示すようにします
2. 考え抜かれたファイル構造 -- ファイルシステムを、エージェントがナビゲートできるインターフェースにします
3. エンドツーエンドの型 -- 不正な状態を排除し、エージェントが探索する範囲を狭めます
4. 高速で一時的、かつ並行利用可能な開発環境 -- フィードバックループを短く保ち、エージェントの並行ワークフローを可能にします
5. 自動化された強制 -- リンター、フォーマッター、フックによって、エージェントが選べる余地を減らします

監査のワークフロー

コードベースを監査するには、次の手順を進めます。

1. 技術スタックの検出

プロジェクトファイル（例：package.json、go.mod、Gemfile、pyproject.toml、Cargo.toml）を調べて、主な言語、テストフレームワーク、ビルドシステム、データベースを特定します。これにより、どのツールに関する推奨事項が適用されるかが決まります。

2. 各原則の評価

各原則の詳細な基準については、references/checklist.md を読んでください。各原則の現状を判断します。

• テストカバレッジ：カバレッジツールを実行するか、設定を調べます。CIでの強制を確認します。現在の割合と、カバーされていない行を特定できるかどうかを報告します。
• ファイル構造：ディレクトリツリーを一部確認します。ファイルサイズを測定します。何でも入れるファイル（utils、helpers、common）を指摘します。ファイル名からドメイン上の目的が伝わるかを評価します。
• 型システム：厳格モード、意味のある型名、APIコントラクトスキーマ、データベース制約を確認します。any や型指定のない箇所を特定します。
• 開発環境：ワンコマンドでのセットアップ、テストスイートの実行時間、ポート／DBの分離、worktreeまたはコンテナーのサポートを確認します。
• 自動化された強制：リンター／フォーマッターの設定、CIパイプライン、Gitフック、エージェントフックを確認します。

3. 評価表の作成

各原則につき1行の表で所見を提示します。

原則	評価	主な所見
テストカバレッジ	強い / 十分 / 弱い	例：「カバレッジ87％、CIでの強制なし」
ファイル構造	強い / 十分 / 弱い	例：「500行を超えるファイルが3つ、何でも入れるutilsファイルが2つ」
型	強い / 十分 / 弱い	例：「厳格なTSだが、APIスキーマ生成なし」
開発環境	強い / 十分 / 弱い	例：「手動で8段階のセットアップ、並行利用のサポートなし」
強制	強い / 十分 / 弱い	例：「ESLintは設定済みだが、CIでは未実行」

4. 改善の優先順位付け

最も弱い原則を順位付けし、上位2～3項目について具体的な次の手順を提案します。それぞれの推奨事項では、プロジェクトで実際に使用されている技術スタックとツールに言及してください。

ガイドのワークフロー

特定の原則の改善をガイドする場合：

1. 該当するセクションについて references/checklist.md を読む
2. プロジェクトにおける、その原則の現状を評価する
3. プロジェクトの技術スタックに合わせた、具体的で順序立てた変更一覧を提示する
4. 可能であれば、正確なコマンドや設定スニペットを示す

重要な洞察：なぜカバレッジ100％なのか

最も直感に反する原則なので、強調する価値があります。行カバレッジが100％の場合：

• 転換点が訪れます。未カバーの行は必ず最近の変更箇所にあるため、何をテストすべきか迷う余地がなくなります
• カバレッジレポートが、必要なテストをまとめたシンプルな TODO リストになります
• 「バグがない」ことを証明するのが目的ではありません。すべての行がどのように動作するかを、作成者に示させるためのものです
• 到達不能なコードがすぐに見つかり、削除されます
• レビュー担当者は具体的な動作例を確認できるため、コードレビューが容易になります
• 一度達成すれば、100％の維持は驚くほど簡単です。カバレッジレポートに、テストが必要な行が正確に列挙されます

リソース

references/

• checklist.md -- 5つの原則それぞれについて、スタック固有のツール、主要な指標（Strong／Adequate／Weak）、ガイダンスを含む詳細な評価基準です。監査を実施する場合や、いずれかの原則について詳細なガイダンスを提供する場合に、このファイルを読み込んでください。