forge-setup-project

プロジェクトのコンテキスト基盤を設定または更新する

コンテキストは次の3層で構成されます。

層	ファイル	役割
1 — ホットメモリー	AGENTS.md	常に読み込まれます。簡潔で、規約を密に記載します。エージェントが常に必要とする情報だけを含めます。
2 — ウォームメモリー	docs/*.md	トピックに応じてオンデマンドで読み込まれます。トークンコストに見合う内容がある場合にのみ作成します。
3 — コールドメモリー	仕様書、スキーマ、運用手順書	複雑なプロジェクト向けのオンデマンド参照資料です。このスキルでは作成しません。

中心となる原則：コンテキストはトークンコストに見合う価値が必要です。 エージェントが Grep、Glob、Read を使ってコードベースを調べても発見できない知識だけを含めます。

AGENTS.md が唯一のガイダンスファイルです。CLAUDE.md は作成しないでください。CLAUDE.md も CLAUDE.local.md も存在しない場合、Claude Code は AGENTS.md をネイティブに読み込むため、シンボリックリンクやコピーを作成しても名前がもう1つ増えるだけです。CLAUDE.md が正当化されるのは、ユーザーが保持したい Claude 固有の内容がある場合だけです。その場合は、@AGENTS.md に続けてその内容を記載し、コピーは作成しません。

入力

任意のプロジェクトルートパス（$ARGUMENTS。既定値は cwd）。任意の実行ガイダンスとして -- <additional context> を指定できます。

プロセス

Step 1: 既存の内容を確認する

プロジェクトルートで AGENTS.md、CLAUDE.md、README.md、および docs/ をスキャンします。ファイルの状態によって作業内容が決まります。何も存在しない場合は一から生成します。従来の CLAUDE.md があり AGENTS.md がない場合は、AGENTS.md に移行してから更新します。AGENTS.md が存在する場合は、監査して更新します。AGENTS.md へのシンボリックリンクまたはコピーである CLAUDE.md は、Step 7 で削除します。

Step 2: コードベースを調査する

構成、ツール、CI/CD、ドキュメントを調査します（グリーンフィールドプロジェクトでは省略します）。調査で得た各項目を、発見可能（エージェント自身で見つけられる）か、ドキュメント化が必要（決定事項、規約、障害モード）に分類します。コンテキストファイルに含めるのは後者だけです。

エージェントの準備状況を評価します。フィードバックループ（テスト、リンター、ビルドサイクルの速度）、モジュール構成、アプリケーションの可読性、既知のリスクを確認します。成功時に大量の出力を表示するチェックは、エージェントのコンテキストをノイズで埋めてしまいます。フィードバックループの項目では、ツールに静粛モードのフラグがあればその名前を記載してください。なければ、成功時には1行だけ、失敗時にはすべてを出力するラッパー用の `` を記載します。

Step 3: 既存のガイダンスを監査する

ガイダンスファイルがすでにある場合は、各セクションを評価します。

基準	確認事項
具体性	これはこのプロジェクトについての説明ですか。それとも、どのプロジェクトにも当てはまりますか。
発見困難性	エージェントが調査して見つけられる内容ですか。そうであれば、コンテキストの無駄です。
最新性	現在のコードベースと一致していますか。コマンド、パス、パターンを検証してください。
情報密度	実行可能な情報と総語数の比率はどの程度ですか。
適用範囲	すべてのタスクに必要ですか。それとも一部だけですか。特定の領域（マイグレーションやサービスのログなど）に関するガイダンスは、条件付きブロックに記載するか、参照先のドキュメントに記載します。

影響度ごとにまとめた監査レポートを提示し、変更を適用する前に AskUserQuestion でユーザーの確認を得ます。

Step 4: プロジェクト情報を収集する

コードからは明らかにならない内容、すなわち基本原則、繰り返し発生する障害モード、ドメインの不変条件について AskUserQuestion を使って質問します。また、調査で曖昧だった点や Step 3 の監査で判明した不足点についても質問します。コードから発見できる内容は決して質問しないでください。質問内容を決める際は、末尾に追加されたコンテキストも考慮します。

Step 5: AGENTS.md を生成または更新する

AGENTS.md を作成または更新します。約200行未満に収めてください。長さは、発見困難性の基準を満たす内容によって決まるため、小規模なプロジェクトのファイルは短くなります。構成については agents-md-template.md を参照してください。移行時は、採用した従来の内容を統合し、Step 7 で古いファイルを削除します。

ステップ 6：Tier 2 — docs/ を生成または更新する

docs/architecture.md（設計上の決定、データフロー、モジュールの役割）と docs/pr-workflow.md（ブランチ命名、PR チェックリスト、レビュー手順）を作成します。探索の結果、作成する価値のある内容が見つかった場合に限り、AskUserQuestion を使って追加ドキュメント（開発、コーディングガイドライン、テスト、ドメイン固有の内容）の作成を提案します。各ドキュメントは、発見可能性テストに合格する必要があります。空のドキュメントはコンテキストを無駄にします。

ステップ 7：冗長な CLAUDE.md を削除し、.gitignore を更新する

CLAUDE.md が AGENTS.md へのシンボリックリンク、そのコピー、またはその内容に移行済みの古い内容である場合は削除します（追跡対象の場合は git rm を使用します）。AGENTS.md にない内容が残っている場合は、削除する前に AskUserQuestion を使ってユーザーに確認します。ユーザーが保持したい Claude 固有の内容がある場合は、@AGENTS.md とその内容だけに整理します。CLAUDE.local.md が存在する場合は、ファイルが存在する間、Claude Code は AGENTS.md をスキップすることをユーザーに伝えます。CLAUDE.md を削除する場合は、Claude Code の一部のバージョンや設定では CLAUDE.md のみが読み込まれること（対象はこちら）を伝えます。その場合の解決策は、@AGENTS.md を含む CLAUDE.md を作成することです。.gitignore に不足している、スタックに適したエントリを追加します。既存のものを上書きしてはいけません。

ステップ 8：人間向けのファイルを作成する

存在しない場合は README.md を作成します（プロジェクトの説明、クイックスタート、ドキュメントへのリンクを記載し、エージェントのコンテキストではなく人間向けにします）。既に存在する場合は、AskUserQuestion を使って置き換え、統合、または維持のいずれにするかを確認します。

ステップ 9：コミットする

新規または変更したファイルをステージングしてコミットします。コミットメッセージは docs: set up agentic context infrastructure（更新の場合は docs: update context infrastructure）です。無関係な変更がステージング済みの場合、または生成ファイルについて未解決の質問がある場合は、コミットをスキップします。

ステップ 10：要約する

作成・変更した内容を報告します。output-format.md を参照してください。Tier のステータスと行数、エージェント対応状況の評価、次のステップを含めます。

ガイドライン

• 発見可能性テスト —「エージェントは探索してこれを見つけられるか？」見つけられる場合は、記述しません。
• 量より有用性 — 段落より表を優先し、空のセクションは省略します。
• Tier の管理 — AGENTS.md は約 200 行未満に保ちます。200 行を超える場合は Tier 2 に移します。
• エッジケース — モノレポでは、パッケージごとの AGENTS.md を提案します。テストや CI がない場合は、次のステップとして言及します。

関連スキル

次のステップ： 最初の作業を計画するには forge-create-issue を使用します。アイデアがまだ粗く、まず収束に向けた質問が必要な場合は forge-shape を使用します。

使用例

/forge-setup-project
/forge-setup-project /path/to/project
/forge-setup-project -- keep the setup lean and call out missing feedback loops