setup

セットアップ

• 機能： リポジトリについてユーザーに質問し、docs/dev-agents/ を作成して、他のすべてのスキルが読み込む docs/dev-agents/config.md を書き込みます。
• 使用するタイミング： このセットに含まれる他のスキルを使う前に、リポジトリごとに一度実行します。トラッカーを変更する場合や、古い設定を現在の項目に更新する場合は、再実行してください。
• 依存関係： git。GitHub トラッカーには gh、Linear トラッカーには Linear MCP サーバーが必要です。ローカルトラッカーにはどちらも必要ありません。
• 呼び出し方法： Claude Code /setup、Codex $setup、Kiro CLI /setup。
• 入力： 現在のリポジトリと、インタビューへのユーザーの回答。
• 出力： docs/dev-agents/config.md、docs/dev-agents/rules/、プロジェクトのコンテキストファイル内の参照行、およびトラッカーの初回セットアップ（必要な場合）。

冪等性があります。安全に再実行できます。既存ファイルは、確認なしに上書きしません。

1. モードの判定

現在のディレクトリを調べ、状態を確認します（ファイルを読み込み、推測しないでください）。

• グリーンフィールド： 空、またはほぼ空（ソースツリーがない）。
• ブラウンフィールド： 既存のコードがある（ソースディレクトリ、パッケージマニフェスト、Git の履歴）。

質問を始める前に、次の項目も読み込みます。

• 既存の docs/dev-agents/config.md。プロジェクトですでに決定した選択肢が保持されているため、インタビューでは未設定の項目だけを補います。
• git rev-parse --git-dir。Git リポジトリかどうかを確認します。
• git remote -v。GitHub のリモートがあるかどうかを確認します。
• ルートにある AGENTS.md と CLAUDE.md。すでに存在するコンテキストファイルを確認します。
• すでに存在するプロダクトの意図に関するドキュメント（docs/PRD.md、docs/product/、AGENTS.md 内の仕様）。
• プロジェクトのマニフェストからテストコマンドを確認します（package.json のスクリプト、pyproject.toml、Makefile）。

Git リポジトリがない場合は、最初に解決します。 インタビューを始める前に git init を提案してください。各バックエンドはステップ 7 でコミットを提案し、github バックエンドでは、紐付け先となるリポジトリがなければリモートを設定できません。そのため、この確認が 3 セクション後になると、インタビューを巻き戻すことになります。セクション A を表示する前に、これだけを単独で質問してください。インタビューの内容も含む選択肢の 1 つとして尋ねてはいけません。セクション A の GitHub 確認には、リポジトリがすでに存在している必要があります。

2. ヒアリング

何が設定済みで、何が不足しているかを要約します。その後、セクションを順番に進めます。1 セクションにつき回答を 1 つ受け取ってから、次に進みます。

選択肢によって本当に分岐する場合に限り、1 行で説明を加えます。ステップ 1 ですでに決まっているセクションは丸ごと省略します。

質問したら、そこで止まります。 質問をしたターンでは、質問が最後の内容です。その後にツールを呼び出したり、回答があるまで作業を進めたりしてはいけません。ハーネスがまだ作業中の場合、通常の返信は受け取れません。

回答しやすくします。 選択肢に番号を付け、おすすめを最初に示し、数字だけでよいと伝えます。ハーネスに専用の選択機能があればそれを使います。ほとんどのハーネスにはないため、その場合は番号付きのテキストで聞くのが適切です。代わりの手段として謝る必要はありません。すでに画面に表示されているパスは聞き返さず、表示して、はい、の一言で確認します。

複数質問に対応する選択機能があっても、ヒアリングの順番は変えません。 Claude Code では 1 回の呼び出しで 4 つの質問ができますが、それは 1 つのセクションをより速く尋ねるために使います。セクション A から D までをまとめて表示してはいけません。どのハーネスでも、セクション A と、その表にあるすべての前提条件が解決するまでは、セクション B を表示しません。回答によってバックエンドがそもそも機能するかが決まり、機能しない場合、それ以降のセクションは無駄になるためです。回答が互いに影響しない、同一セクション内の質問だけをまとめます。

セクション A：課題トラッカー。

説明：このリポジトリの課題を管理する場所です。他のすべてのスキルは tracker を通じて課題を読み書きします。実際に作業を管理している場所を選んでください。

• GitHub：課題はリポジトリの GitHub Issues にあります（gh CLI を使用）
• Linear：課題は linear.app にあります（Linear MCP サーバーを使用）。チームキーとプロジェクト名を尋ねます。どちらも設定に記録します。
• ローカル Markdown：課題はこのリポジトリ内の docs/dev-agents/issues/ にファイルとして保存します（個人プロジェクトやリモートのないリポジトリに適しています）。一度に作業できるのは 1 セッションです。ブランチで行った割り当ては、そのブランチがマージされるまで main からは見えません。
• その他（Jira、GitLab など）：ワークフローを 1 段落で説明してもらい、その内容を設定本文の自由記述として記録し、issue_tracker: other を設定します。

セクション B の前に、バックエンドの前提条件をここで解決します。 前提条件が満たされていない場合は、実行の最後に報告するのではなく、今すぐ質問します。ユーザーはこのバックエンドを選んだばかりで、すぐそこにいます。問題をステップ 5 まで持ち越すと、最初のセクションが機能するかどうかもわからないまま、さらに 3 つのセクションに回答してもらうことになります。

バックエンド	確認事項	不足している場合
github	gh auth status、および git remote -v に GitHub のリモートがあること	どのリポジトリを使うか尋ね、既存のリポジトリを使う場合は git remote add origin <url>、新しく作る場合は gh repo create <name> --private --source=. --remote=origin と、両方の方法を提示します。リポジトリを作成するかどうかはユーザーが決めることなので、選択肢を提示して回答を待ちます。
linear	Linear MCP サーバーが list_teams に応答すること	停止します。接続方法を伝え、応答があるまでは設定に Linear のフィールドを一切記録しません。
local	なし

解決済みの OWNER/REPO、または解決済みのチームとプロジェクトを設定に記録します。後で設定する予定があることは決して記録しません。

セクション B：プロダクト意図のドキュメント。 要件、仕様、ロードマップがどこにあるかを確認し、後続のスキルが正しいファイルを読むようにします。デフォルトは docs/dev-agents/PRD.md、SPEC.md、ROADMAP.md です。すでに AGENTS.md または CLAUDE.md が該当ドキュメントである場合は、そのファイルをフィールドに指定します。

セクション C：コンテキストファイル。 コーディングエージェントがプロジェクトに入るための入り口です。デフォルトは AGENTS.md です。意図的に Claude Code のみを対象とするプロジェクトでは CLAUDE.md を使います。プロジェクトに既存の規約がある場合は、それを維持します。context_file には、どのハーネスからでも最終的に到達するファイルを指定し、決してその関係を逆転させてはいけません。

セクション D：テストコマンド。 ステップ 1 で推測したコマンドを確認するか、コマンドを尋ねます。後続のスキルが作業を引き渡す前に実行するコマンドです。

3. スキャフォールド

開発スキルが管理するものはすべて docs/dev-agents/ の下に置き、それ以外はプロジェクトが管理します。 不足しているものだけを作成します：

docs/dev-agents/
docs/dev-agents/config.md             # entry point on how to use these skills for AI-SDLC
docs/dev-agents/rules/                # promoted learnings, one file per rule
docs/dev-agents/issues/               # only when issue_tracker: local

最初のルールが追加される前に Git がディレクトリを追跡できるよう、docs/dev-agents/rules/.gitkeep を追加します。

空の PRD.md、SPEC.md、ROADMAP.md は作成しないでください。これらのパスは設定に記録され、 research、architect、plan がファイルを書き込みます。例外はステップ 6 のみで、既存のコードベースから仕様書を書き込みます。

テンプレート： config-template.md を基に docs/dev-agents/config.md を作成し、 該当しないフィールドは削除します。すべての値はインタビューまたはステップ 1 から取得します。設定に記載するパスを推測してはいけません。

既存のプロジェクト： 既存の config.md に記載された選択はそのまま維持します。不足しているフィールドを追加し、変更内容を報告してください。本文を書き換えてはいけません。

所有権ルール： AGENTS.md と CLAUDE.md はプロジェクトが管理します。セットアップではステップ 4 の参照行を追加する場合がありますが、既存の内容を移動、統合、書き換えしてはいけません。rules_dir の既定値は docs/dev-agents/rules/ です。独自の規約があるプロジェクトでは、Claude Code が自動読み込みする .claude/rules/ などを指定できます。依頼されていないルールファイルの移行は行わないでください。

4. 参照行を追加する

すべてのセッションで開発設定が読み込まれるよう、設定済みの context_file に1行追加します：

Read dev workflow for AI-SDLC from docs/dev-agents/config.md

すでにその行がある場合は、このステップをスキップします。再実行しても同じ行を重複して追加してはいけません。既存プロジェクトの場合は、末尾に追加し、それ以外には触れないでください。新規プロジェクトでコンテキストファイルが存在しない場合は、プロジェクト名、トラッカーバックエンド、プロダクト文書のパスを記載した簡潔なファイル（50行未満）を作成し、最後に参照行を追加します。

Claude Code は AGENTS.md を自動読み込みしません。context_file: AGENTS.md で、Claude Code が使用中または使用される可能性がある場合は、CLAUDE.md に @AGENTS.md のインポート行が含まれていることも確認します。ファイルが存在しない場合は1行の CLAUDE.md を作成し、存在する場合はその行を追加します。既存の本文を置き換えてはいけません。

5. トラッカーのセットアップ

選択したバックエンドに対して、一度だけ行う作業です。実施内容を報告してください。ここで失敗しても、残りのセットアップを中止する理由にはしないでください。

• github： リモートと gh auth status はセクション A で設定済みです。gh label create を使って、すでに存在するものはスキップし、4 つのステータスラベルを作成します：backlog、ready、in-progress、in-review。done、cancel、duplicate のラベルはありません。この 3 つは GitHub のクローズ理由であり、tracker が読み書きするものです。認証済みユーザーにリポジトリへの書き込み権限がない場合は何も作成せず、メンテナーが実行する必要のある正確なコマンドを報告してください。

• linear： MCP 接続はセクション A で設定済みです。list_issue_statuses でチームのステータスを確認します。ステータスはチームごとに設定され、そのチーム内のすべてのプロジェクトで共有されます。以下のカテゴリに対応する 7 つのステータスが必要です：

  必須ステータス	カテゴリ
  Backlog	backlog
  Todo	unstarted
  In Progress	started
  In Review	started
  Done	completed
  Canceled	canceled
  Duplicate	duplicate

  In Review がないことを想定してください。 Linear のデフォルトテンプレートから作成したチームには 6 つのステータスがあり、In Review はありません。そのため、これは例外的なケースではなく、通常の初回実行時の状態です。ユーザーに何か誤りがあったかのように扱わず、その旨を明確に伝えてください。

  1 つでも不足していれば停止してください。 ステータスを作成または名前変更する MCP ツールはありません。そのため、チームの設定でどのカテゴリの下に何を追加すべきかを正確に示し、一致するまで Linear のフィールドを設定ファイルに書き込まないでください。チームに存在するステータスへ、勝手に対応付けないでください。誤ったステータスで作成されたチケットは、誰も確認していない場所に置かれてしまいます。

  余分なステータスがあっても停止せず、警告してください。 名前とカテゴリを明示して、はっきりと報告してください。また、そこに置かれたチケットはフロンティアから見えず、未マッピングとして報告されることも伝えてください。そのうえで、設定ファイルの本文の Tracker notes に書き込みます。そうすれば、ユーザーが覚えておかなければならないことではなく、後で AI と一緒に検討できる決定事項になります。

• local： docs/dev-agents/issues/.gitkeep を作成します。

• other： セットアップするものはありません。ユーザーが説明したワークフローが契約です。

6. ブラウンフィールド：アーキテクチャの調査

現在の状態をリバースエンジニアリングして、設定済みの spec_file にまとめることを提案してください（強制はしないでください）。

1. コードベースを調査します。エントリーポイント、コンポーネント、外部サービス、データストア、コンポーネント間の契約、テストの構成、ビルドとデプロイの経路を確認します。
2. 現在のアーキテクチャを説明する仕様を書きます。コンポーネント、インターフェース、データフロー、既知の技術的負債や不足事項を記載し、要件ではなく技術的負債であることを明確に示します。
3. 先を見越した要件を作り出さないでください。それは architect の役目です。

7. 報告

スキャフォールドと設定をコミットすることを提案してください。新しいリポジトリでは、これにより後続のタスクブランチが必要とするルートコミットが作成されます。

次に、モード、トラッカーのバックエンド、作成したファイル、実施した一度限りのトラッカー設定、ユーザー自身がまだ行う必要のあることを要約します。

次のステップ：このプロジェクトのハーネスを使って、バックエンドが応答することを確認します。Claude Code /tracker list、Codex $tracker list、Kiro CLI /tracker list。