setup-codebase-harness

コードベースのハーネスをセットアップする

ハーネスエンジニアリング： モデルは固定されています。エージェントが人の注意を最小限に抑えながらソフトウェアを構築・検証できるよう、その周囲の足場（環境、ドキュメント、フィードバックループ）をエンジニアリングします。人間が方向を示し、エージェントが実行します。リポジトリを理解しやすく、実行可能で、検証可能にすることがあなたの役目です。

段階的に、深掘りしながら進めます。現状を把握し、不足している機能を一つ構築し、それを使って次の機能に取り組みます。すべてを一度に解決しようとせず、リポジトリが実際に必要としているものをセットアップします。エージェントが苦戦したとき、解決策はたいてい「もっと頑張る」ことではありません。「不足している機能は何か、どうすれば理解しやすく、確実に適用できるか」と考え、それを追加してください。

このスキルは、用途を絞ったサブスキルを統括します。dev-local-setup、e2e-setup、crabbox-setup（クラウド／並列）、verifier-setup（リポジトリ固有の**/verifyループを用意します。以前のpr**スキルに代わるものです）。

0. 現状を把握する

リポジトリを調査します。技術スタック、パッケージマネージャー、サービス／ポート、インフラ依存関係、既存のドキュメント／テスト／CI、そして暗黙のルール（README、PR のコメント、関係者の頭の中に埋もれているもの）を確認します。以下の各柱について、不足しているものを記録します。

1. 理解しやすい — エージェントがリポジトリを推論できる

エージェントから見えないものは、存在しないも同然です。チャットスレッドや人の頭の中にある知識は見えません。バージョン管理される、リポジトリ内の成果物に移しましょう。

• a) 手順書ではなく地図を。 ルートにあるエージェント向けドキュメント（AGENTS.md / CLAUDE.md）を、約100行の目次に整理します。1行の概要、プロジェクトツリー、基本ルール（変えてはならない前提）、そして「参照先」テーブルを含めます。詳細は、構成を整理した**docs/ の情報源**（アーキテクチャ、フロントエンド、テスト、ドメイン別のトピック）に移し、docs/index.md を用意します。巨大な指示ファイルは古くなりやすく、作業の妨げになります。地図は小さく安定させ、詳細は必要に応じて段階的に示します。
• b) 修正方法を示すカスタム Lint。 基本ルールを文章だけにせず、機械的なチェックにします。一度取り込んだ人の判断基準を、毎回、あらゆる場所で適用します。各不変条件につき Lint を一つ設けます（レイヤー／依存関係の方向、命名、any の禁止、禁止されたインポート、ファイルサイズ、構造化ログなど）。エラーメッセージに修正方法を含め（「ここでは X は使用できません。Y を行ってください」）、エージェントのコンテキストに修正方法が伝わるようにします。リポジトリの Linter と CI に組み込みます。
• c) クエリ可能なコードグラフ。 codebase-memory-mcp でリポジトリをインデックス化し、エージェントが手当たり次第に検索するのではなく、ナレッジグラフから呼び出し元、データフロー、アーキテクチャを追跡できるようにします。大規模なコードベースでも、より速く正確に移動できます。
• d) （後で）ドキュメントを現状に合わせる。 コードと一致しなくなったドキュメントにフラグを立て、修正 PR を作成する、鮮度維持／ドキュメント整備の工程を設けます。

2. 実行可能 — エージェントがアプリを起動し、操作できる

• dev-local-setup → すべてのサービスとインフラを起動する、ワンコマンドで再現可能なローカルスタック（scripts/dev-local.sh up）。
• アプリを操作可能にします。verifier-setup がインストールする playwright-cli スキルを使ったブラウザー操作や、ログへのアクセスを可能にします。
• crabbox-setup → エージェントごとに隔離されたクラウド環境を用意します。dev-local を並列処理に対応させたものです。ループが同時に実行される場合に利用します。1台のノートパソコンでは、固定ポート、1つの Docker デーモン、1つの DB といった制約があるため、N 個の完全なスタックをホストできません。ワークツリーごとにローカル環境を用意しても解決しません。ワークツリーがホストを共有するためです。crabbox なら各エージェントが独自のスタックと、ボックス内のブラウザーを使えるので、並列検証が衝突しません。
• 上級: パフォーマンス／信頼性に関するプロンプト向けに、ローカルで一時的に起動できるオブザーバビリティスタック（クエリ可能なログ／メトリクス）を用意します。

3. 検証可能性 — エージェントが動作を証明できる

• e2e-setup → 信頼できる E2E ゲートです。実際のフロー（回避策ではありません）、再利用可能な認証／セッションヘルパー、クライアント → サーバー → プロダクトの階層的なアサーション、動画／トレースの証拠、サンドボックス専用の外部サービスを備えます。
• verifier-setup → リポジトリ固有の /verify スキル（出荷前に検証するループ）を生成します。新しい 検証サブエージェントが実際のアプリを操作して、構築したばかりの機能が動作することを確認します。メインエージェントはテストが成功するまで修正を重ね、定義済みの回帰テスト一式を実行し、レビュー可能な証明リンクを付けて PR を作成します。ログインが必要な機能に検証エージェントがアクセスできるよう、セッションヘルパーを追加します。

4. その他 — 長期にわたって一貫性を保つ

• コミットの衛生管理：Conventional Commits と、コミット時のフォーマット／Lint（例：husky lint-staged + commitlint）を導入します。マージゲートは軽量に保ちます。エージェントの処理量が多い場合、修正は安価ですが、待機にはコストがかかります。
• 不要物の整理：「黄金律」を明文化し、定期的なクリーンアップで小規模なリファクタリング PR を作成します。技術的負債は、苦しい一括返済ではなく、継続的に減らします。人間の審美眼を一度記録し、すべての行に適用します。
• 正確性が重要な変更には、エージェント同士のレビューを行います（独立したレビュアーを使い、自己レビューは避けます）。

順序と残すもの

**1a（マップ）→ 2（dev-local）→ 3（e2e + verifier-setup）**の順で進め、その後、リポジトリの成熟に応じて 1b（Lint） と 4 に取り組みます。成果物 — 簡潔なマップ + docs/、scripts/dev-local.sh、e2e/ スイート、生成された /verify スキル、独自の Lint — はそれぞれ、再利用可能で分かりやすく、使うほど価値が積み重なる機能です。エージェントが全体を正確に把握できる、地味で、組み合わせ可能で、安定した技術を優先します。