setup-agentic-repository

setup-agentic-repository

AI エージェントが各セッションの開始時に読み、プロジェクトでの作業方法を理解するための指示ファイル一式を作成します。出力されるのは、汎用テンプレートをまとめただけのものではなく、プロジェクト固有の完全な指示ツリーです。

---

フェーズ 1 — 自動調査

何かを書く前に調査してください。速度を最大限に高めるため、3 つのサブエージェントを並行して起動してください。それぞれが独立した調査タスクを担当します。次に進む前に、それぞれの調査結果を集めてください。

サブエージェントのディスパッチ

次の3つのサブエージェントを同時に起動します（1回のツール呼び出しで複数の Agent を呼び出します）。

サブエージェント A — 技術スタックとコマンド。 設定ファイル（package.json、pyproject.toml、go.mod、Cargo.toml、tsconfig.json、Dockerfile、Makefile、.prettierrc*、.eslintrc*、ruff.toml、.golangci.yml など）を読み、次の内容を報告します。

• 言語とバージョン
• ランタイムとフレームワーク（Fastify、Express、Next.js、Django、FastAPI、chi など）
• テストフレームワークとテストの構成方法
• データベースとクエリレイヤー（使用している場合）
• 認証方式（使用している場合）
• AI／LLM ライブラリ（使用している場合）
• パッケージマネージャー
• 型チェックツール（例：tsc、mypy、pyright）
• フォーマッター（例：Prettier、Black、Ruff format、gofmt、rustfmt）— リンターとは別に記載します。多くのスタックでは、これらを別々のコマンドとして実行します。
• リンター（例：ESLint、Ruff、golangci-lint、Clippy）
• 次の操作に使える、正確でコピー＆ペースト可能なコマンド：セットアップ／インストール、テスト実行、型チェック、開発サーバー、ビルド、フォーマット、リント（package.json のスクリプト、Makefile のターゲット、pyproject.toml のスクリプト、Dockerfile のエントリーポイントを確認してください）。フォーマットとリントで同じスクリプトを使う場合はその旨を記載し、別々の場合は両方を記録します。

サブエージェント B — プロジェクト構成と規約。 トップレベルのディレクトリを一覧表示し、次の内容を報告します。

• 特定されたサブドメイン（アプリの異なる部分を表すトップレベルのディレクトリ）：
  • 単一パッケージのリポジトリ：通常は src/、app/、internal/、cmd/
  • モノレポ：packages/<name>/ または apps/<name>/ の各ディレクトリ
  • 複数部分からなるリポジトリ：backend/、frontend/、server/、client/、api/、web/
  • 除外対象：node_modules/、dist/、build/、.git/、テスト用フィクスチャ、設定ディレクトリ
• 各サブドメインの役割（バックエンド API、フロントエンドアプリ、共有ライブラリ、CLI ツールなど）
• ファイル名のパターン（kebab-case、camelCase、snake_case）
• テストファイルの配置（ソースコードと同じ場所か、独立した __tests__/ や tests/ ディレクトリか）
• モジュール構成のスタイル（機能別、レイヤー別、ドメイン別など）
• 既存のドキュメント（README.md の内容、docs/ フォルダの有無）

サブエージェント C — Git プラットフォーム、CI/CD、フック、既存ファイル。 .git/config を読み、CI およびフックの設定ファイルを確認し、最近のコミットをサンプルとして調べ、既存のドキュメントを確認します。

• リモート URL から Git プラットフォームを特定：github.com → GitHub、dev.azure.com / visualstudio.com → Azure DevOps、gitlab.com → GitLab、bitbucket.org → Bitbucket
• CI/CD：.github/workflows/ → GitHub Actions、azure-pipelines.yml → Azure Pipelines、.gitlab-ci.yml → GitLab CI
• コミット前フック：.husky/、.pre-commit-config.yaml、lefthook.yml／lefthook.yaml、およびサンプルファイル以外のファイルがある .git/hooks/ を確認します。見つかった場合は、使用されているフレームワークと各フックの実行内容（設定を開いて要約）を報告します。エージェントがこれらのフックによってコミットを阻止される可能性があることを把握できるようにし、セットアップ手順にはインストール手順（pnpm install による Husky の prepare スクリプト実行、pre-commit install、lefthook install など）を含めます。
• コミットメッセージの規約：git log -n 100 --pretty=%s を実行し、確認できたパターンを報告します。
  • Conventional Commits のプレフィックス（feat:、fix:、chore:、feat(api): のようなスコープ）
  • チケットキーのプレフィックス／サフィックス（AB#123、PROJ-456、#789）— これにより、プラットフォームから推測した課題トラッカーを確認または修正できます。
  • 命令形か過去形か、行の長さの傾向、10件以上のコミットで一貫して見られるその他の特徴
  • コミットに一貫性がない場合、またはリポジトリのコミット数が約10件未満の場合は、その旨を記載します。規約を推測で作らないでください。
• 同じコミットメッセージから課題トラッカーの手掛かりを特定（#123 → GitHub Issues、AB#456 → Azure DevOps、PROJ-789 → Jira／Linear）
• CLAUDE.md、AGENTS.md、README.md の有無と、意味のある内容があるかどうか（内容の簡単な要約を報告）

サブエージェントが戻った後

3つのレポートを統合し、全体像をまとめます。サブエージェントが何かを特定できなかった場合（例：データベースが見つからない、CI が検出されないなど）は問題ありません。「未検出」と記録して先に進んでください。

既存のファイルについて：

• README のプロジェクト説明をルートの AGENTS.md の概要に取り込みます
• 文書化されている規約を ENGINEERING.md に反映します
• 既存の AGENTS.md または CLAUDE.md が空、もしくはプレースホルダーの場合は置き換えます
• 内容が記載されている CLAUDE.md はそのまま残します。用途が異なるためです

---

フェーズ 2 — 調査結果を確認し、ガイドラインを収集する

調査結果を提示し、それぞれの判断について確認します。

2a. 調査結果を提示する

書式付きの概要として、発見した内容をユーザーに提示します。

Here's what I found:

  Stack:        [language] / [framework] / [db] / [test framework]
  Format/Lint:  [formatter] / [linter]  (or "shared: <tool>" if same)
  Platform:     [GitHub | Azure DevOps | GitLab | Bitbucket | unknown]
  CI:           [GitHub Actions | Azure Pipelines | GitLab CI | none detected]
  Tracker:      [GitHub Issues | Azure DevOps | Jira | Linear | none detected]
  Commits:      [Conventional Commits | ticket-prefixed | freeform | none detected]
  Hooks:        [Husky | pre-commit | lefthook | none detected]
  Subdomains:   [list of discovered subdomains]

次に AskUserQuestion を使い、1 回の呼び出しで調査結果を確認し、作業の追跡方法について質問します。追跡ツールを確実に特定できた場合は、追跡に関する質問を省略します。1 回の呼び出しにつき、質問は最大 4 つまでです。適切なものをまとめてください。

questions:
  - question: "Does this look right, or should I correct anything?"
    header: "Findings"
    multiSelect: false
    options:
      - label: "Looks good (Recommended)"
        description: "Proceed with the detected stack, platform, and subdomains as shown above."
      - label: "Needs corrections"
        description: "I'll tell you what to fix before we continue."
  - question: "Where do you track issues / work items?"
    header: "Tracker"
    multiSelect: false
    options:
      - label: "GitHub Issues"
        description: "Issues tracked in GitHub, linked with #123 in commits and PRs."
      - label: "Azure DevOps"
        description: "Work items tracked in Azure DevOps, linked with AB#123."
      - label: "Jira"
        description: "Issues tracked in Jira, linked with PROJECT-123."
      - label: "Linear"
        description: "Issues tracked in Linear, linked with TEAM-123."

ユーザーが「修正が必要」を選んだ場合は、続行する前に修正内容を待ちます。

2b. 組織のガイドライン（任意）

組織のガイドラインについて、AskUserQuestion を使って質問します。

questions:
  - question: "Do you have coding guidelines or standards to include?"
    header: "Guidelines"
    multiSelect: false
    options:
      - label: "Skip"
        description: "No org-specific guidelines — use only the auto-detected conventions."
      - label: "Yes, I'll provide them"
        description: "I'll paste a file path, URL, or content to weave into ENGINEERING.md."

ユーザーがガイドラインの提供を選んだ場合は、入力を待ちます。ガイドラインを ENGINEERING.md の該当するセクション（コーディング規約、命名規則、レビュー手順など）に反映します。内容をそのまま貼り付けず、技術スタック固有の規約と自然に統合してください。

---

フェーズ 3 — 定型ファイルをそのまま生成する（スクリプト）

スキャフォールディングスクリプトを実行し、ディレクトリ、共通テンプレート、合成した AGENT_WORKFLOW.md、および CLAUDE.md ブリッジファイルなど、定型のファイルをすべて作成します。定型内容の生成に LLM を使わずに済むため、トークンを節約できます。

bash scripts/scaffold.sh --target <repo-root> --platform <platform>

--platform フラグによって、agents-docs/AGENT_WORKFLOW.md に挿入される PR/MR ワークフローのセクションが決まります。デフォルトでは docs/ と並ぶ agents-docs/ に生成されるため、人が管理するプロジェクト文書には影響しません。エージェントのファイルツリーを別の場所（例：docs/agents）に置く強い理由がある場合は、任意の --docs-dir <dir> フラグを使えますが、ほとんどの場合はデフォルトが適切です。

スクリプトは次のファイルを作成します。

ファイル	方法
CLAUDE.md	作成します（既存の場合は追記）。Claude に AGENTS.md を参照させます
agents-docs/AGENT_WORKFLOW.md	ベーステンプレートとプラットフォーム別 PR/MR セクションから合成します
agents-docs/AGENTS_FEATURES.md	そのままコピーします — 汎用の機能文書契約
agents-docs/AGENTS_CONTEXT.md	そのままコピーします — CONTEXT.md の利用側／提供側の契約
agents-docs/AGENTS_ADRS.md	そのままコピーします — ADR の利用側／提供側の契約
agents-docs/features/feature-template.md	そのままコピーします — 今後の機能文書用テンプレート
agents-docs/LESSONS.md	そのままコピーします — 教訓ファイルの形式と、初期例 1 件
agents-docs/adr/0001-record-architectural-decisions.md	そのままコピーします — Nygard の簡易形式を示す初期メタ ADR

このスクリプトは冪等です。再実行時には既存のファイルをスキップします。

利用可能なスクリプト

• scripts/scaffold.sh — 定型ファイルを生成し、AGENT_WORKFLOW.md を合成します

---

フェーズ 4 — プロジェクト固有のファイルを生成する（LLM）

これらのファイルには LLM による推論が必要であり、スクリプトでは生成できません。作成前に、次の参照ファイルを読みます。

• references/file-templates.md — 各ファイルの基本テンプレート
• references/tech-adapters.md — 技術スタック固有のセクション
• references/platform-adapters.md — ENGINEERING.md 用の CI/CD と課題リンクのセクション

すべての {{placeholder}} を、実際に発見した内容に置き換えます。参照ファイルでは、エージェント文書のルートパスが現れる箇所に {{DOCS_DIR}} が使われています。各ファイルを作成する際に、すべての箇所で agents-docs に置き換えてください（または上書きされた場合は、--docs-dir に渡された値を使ってください）。最終出力にプレースホルダーを残さないでください。生成するすべてのファイルは、プロジェクトのシニアエンジニアが書いたかのように仕上げてください。

生成するファイル

ファイル	目的
/AGENTS.md	エントリーポイント — ドキュメントへのリンク、重要なルール、完了チェックリスト
agents-docs/ENGINEERING.md	エンジニアリング標準 — テスト、言語、命名、DB、認証、CI/CD、コマンド
agents-docs/FEATURES.md	機能領域のインデックス（最小限または空の状態から開始）
<subdomain>/CONTEXT.md	発見したサブドメインごとに1つ — ドメインを表す内容：語彙、関係、入出力、不変条件
agents-docs/CONTEXT-MAP.md	サブドメインが2つ以上の場合のみ — 境界づけられたコンテキストとコンテキスト間の関係のインデックス

サブドメインの CONTEXT.md ルール

各サブドメインのトップレベルに CONTEXT.md を1つ作成します。より深い階層には作成しません。

• src/ → src/CONTEXT.md（src/routes/CONTEXT.md ではありません）
• internal/ → internal/CONTEXT.md（internal/handlers/CONTEXT.md ではありません）
• packages/auth/ → packages/auth/CONTEXT.md
• frontend/ → frontend/CONTEXT.md

各サブドメインの CONTEXT.md は、そのサブツリー内のすべてを対象とします。ユーティリティフォルダー、設定ディレクトリ、生成された出力には作成しないでください。

内容は手順ではなく、ドメインを表すものにします。 ファイルテンプレート（references/file-templates.md 内）には、語彙、関係、境界 / 入出力、不変条件、要確認の曖昧点の各セクションがあります。エージェントが記入場所を把握できるよう、骨組みは早めに用意しますが、セクションの内容を埋めるのはフェーズ1で実際に発見した事項だけにしてください。

• 語彙：フェーズ1で明確なドメイン用語（ルート名、テーブル名、特徴的な型名など）が見つからなかった場合は、プレースホルダー行を残した表にします。項目を創作しないでください。agents-docs/AGENT_WORKFLOW.md の作成トリガーによって、後から内容が埋められます。
• 境界 / 入出力：観察できたエントリーポイント（HTTP ルート、イベントハンドラー、エクスポートされたモジュール）を記入します。不明な場合はプレースホルダーを残してください。
• 不変条件：通常、ひな形を作成する時点では空のままです。これらは使用中に明らかになります。

エージェント向けの手順ルール（TDD、型チェック、注力領域）は CONTEXT.md に記載しません。これらは /AGENTS.md と agents-docs/ENGINEERING.md に記載します。

CONTEXT-MAP.md ルール

独自の CONTEXT.md を持つサブドメインが2つ以上ある場合に限り、agents-docs/CONTEXT-MAP.md を生成します。コンテキストが1つだけのリポジトリでは、このファイルを作成しません。

フェーズ1で発見した内容を記入します。サブドメインごとに1行とし、名前、目的の一行説明、観察できた公開インターフェース（HTTP ルート / 発行イベント / エクスポートされた型）、その CONTEXT.md へのパスを記載します。関係セクションには、調査中に確認できたコンテキスト間の結合（共有型、イベントフロー、依存関係の方向）を記載します。コードから関係が明確でない場合は、セクションにプレースホルダーの箇条書きを残してください。内容は後から埋められます。

機能インデックス

agents-docs/FEATURES.md は最小限の内容から開始します。意味のある実装がある機能領域を見つけた場合にのみ項目を追加してください。ルートのスタブや空のハンドラーだけでは該当しません。項目を追加する場合も、インデックス項目だけを追加してください。agents-docs/features/<area>.md ファイル自体は作成しないでください。

AGENTS.md と ENGINEERING.md のプラットフォーム固有の内容

生成するファイルには、references/platform-adapters.md のプラットフォーム関連の内容を取り入れます。

• AGENTS.md の完了チェックリスト：プラットフォーム固有の項目（PR の作成、CI の成功、Issue のリンク）を追加します。
• agents-docs/ENGINEERING.md：CI/CD セクションと Issue のリンク規約を追加します。

プラットフォームが検出されず、ユーザーからの指定もない場合は、プラットフォーム固有のセクションを一切含めないでください。推測で追加しないでください。

注：agents-docs/AGENT_WORKFLOW.md はスクリプトによって適切なプラットフォームセクションとともにすでに処理されています。

フェーズ 1 のシグナルの記載先

調査フェーズでは、技術スタックやプラットフォーム以外にもいくつかのシグナルを収集します。それぞれが適切なファイルに記載されていることを確認してください。

• フォーマッターとリンター（サブエージェント A）：agents-docs/ENGINEERING.md のコマンドセクションに、別々のコマンドとして両方を記載してください。プロジェクトが単一のスクリプトで両方を実行する場合はその旨を明記し、そうでない場合はそれぞれを記載してください。完了チェックリストにも、型チェック／テストとあわせてフォーマッターを記載してください。
• プレコミットフック（サブエージェント C）：フックが見つかった場合は、セットアップの項目にフレームワークとインストール手順（pre-commit install、lefthook install、または「Husky は pnpm install 時に自動でインストールされる」）を agents-docs/ENGINEERING.md に記載し、エージェントがコミットにゲートが設けられていると分かるよう、AGENTS.md に短い注記を追加してください。コミットが拒否された理由をエージェントが理解できるよう、各フックが実行する内容も明記してください。
• コミット規約（サブエージェント C）：明確なパターンが検出された場合は、リポジトリで実際に使われているスタイルに沿った例を 1 つ添えて、agents-docs/ENGINEERING.md のコミットメッセージのセクションに記載してください。コミットの形式に一貫性がない場合や、パターンを判断するには数が少なすぎる場合は、デフォルトで Conventional Commits を押し付けず、このセクションを省略してください。
• サブドメイン（サブエージェント B）：検出されたサブドメインごとに、ドメインの内容を含む <subdomain>/CONTEXT.md を作成します（スケルトンを用意し、観察したエントリーポイントや命名に基づいて内容を埋めます）。サブドメインが 2 つ以上ある場合は、agents-docs/CONTEXT-MAP.md も生成し、サブドメインごとに 1 行を記載します。単一サブドメインのリポジトリでは、マップを作成しません。

用意された agents-docs/LESSONS.md の例を調整する

スキャフォールドスクリプトは agents-docs/LESSONS.md をそのままコピーし、用意された例ではプレースホルダーの型チェックコマンドとして npx tsc --noEmit を使っています。スクリプトの実行後、例をこのプロジェクトで実際に使われている型チェックコマンドに合わせて編集してください。

• TypeScript → npx tsc --noEmit のままにする（または package.json にある正確なスクリプト、たとえば pnpm typecheck に置き換える）
• Python（mypy） → mypy . に置き換える（またはプロジェクトで実際に使われているコマンドにする）
• Python（pyright） → pyright に置き換える
• Go → go vet ./... に置き換える
• Rust → cargo check または cargo clippy に置き換える
• 静的型付けなし → プロジェクトの技術スタックに適した検証手順で例全体を置き換える（例：JS プロジェクトの場合は「完了したと主張する前に、プロジェクトの lint コマンドを実行し、終了コードが 0 であることを確認する。」）

例のタイトル、トリガー、ルール、例のブロックを実際に使われているものに合わせて更新してください。例を用意する目的は、エージェントがそれを読んだとき、このリポジトリで実際に実行できるコマンドが目に入るようにすることです。技術スタックに合わない例は、例がないよりもよくありません。

---

優れた出力とは

一般論ではなく、具体的であること。 リポジトリが Vitest を使っているなら、「テストフレームワーク」とは書かずに「Vitest」と書いてください。型チェックが npx tsc --noEmit なら、正確にそう書いてください。

実際のプロジェクト名を使うこと。 README、package.json、または go.mod で確認した名前でプロジェクトに言及してください。推測した名前や独自に考えた名前は使わないでください。

コマンドを正確にすること。 テスト、型チェック、開発サーバー、ビルド、セットアップのコマンドは、正確でコピーして実行できるものでなければなりません。

適切な範囲にとどめること。 フロントエンドのみのリポジトリに「データベースのガイドライン」のセクションを追加しないでください。Python プロジェクトに「TypeScript の標準」のセクションを追加しないでください。該当する内容だけを記載してください。

重要な点については明確な方針を示すこと。 以下のルールは、技術スタックにかかわらず必ず含めてください。

• TDD（レッド・グリーン・リファクター）は必須
• 複雑なタスクではプランモードを使う
• 作業完了とする前に検証する
• 自己改善のサイクル（学んだ教訓）
• 機能ドキュメントの要件

ルートの AGENTS.md は簡潔に保つこと。 インデックスと、譲れない最重要ルールだけを含めます。詳細は参照先のドキュメントに記載します。

生成後

ユーザーに次の内容を伝えてください。

1. 作成されたファイル（パス付きの全リスト）
2. 検出され、独自の CONTEXT.md が作成されたサブドメイン
3. プラットフォーム固有のコンテンツに使用されたプラットフォーム／トラッカー
4. 不確かな技術スタックの詳細（把握できていない点は正直に伝えてください）
5. コミットする前に確認し、カスタマイズすべき内容

続いて、このスキャフォールドで作成される空の agents-docs/features/ ツリーにコンテンツを追加するための、次のワークフローをおすすめしてください。

次のおすすめステップ：機能ドキュメントを作成しましょう。

スキャフォールドでは、意図的に agents-docs/features/ を空にしています。これを埋める最も手早い方法は、Mimas リポジトリにある 2 つのスキルを、新しいセッションで続けて実行することです。

1. find-features — コードベースをスキャンし、主要な機能領域を特定して、agents-docs/FEATURES.md に追加します。
2. document-feature — 各領域をテンプレートから内容のそろった agents-docs/features/<area>.md に仕上げる、ガイド付きのウォークスルーです。

これら 2 つのスキルと、確認する価値のあるその他のスキルは、https://github.com/Grade-AI-Labs/Mimas にあります。インストールして、まず find-features を実行し、検出された項目ごとに document-feature を繰り返し実行してください。

完了したら、生成されたファイルを確認してコミットしてください。