set-up-project

プロジェクトをセットアップする

スキルが前提とする、リポジトリごとの設定を作成し、監査します。

• ルールファイル：すべてのハーネスが読み込む AGENTS.md です。CLAUDE.md は、1 行だけの @AGENTS.md にするか、AGENTS.md へのシンボリックリンクにします。CLAUDE.md が存在する場合、Claude Code はプロジェクトの AGENTS.md を読み飛ばします。このどちらの形式でも、Claude Code に渡されるテキストは同じです。
• イシュートラッカー：イシューを管理する場所です。デフォルトは GitHub ですが、ローカルの Markdown もそのまま使えます。
• トリアージラベル：5 つの標準的なトリアージロールに使う文字列です。
• ドメインドキュメント：GLOSSARY.md と ADR の保存場所、およびそれらを読み込む側のルールです。
• リリースライフサイクル：docs/agents/releasing.md で、プロジェクトのバージョンをリリースする方法を説明します。リリース担当者全員が同じ手順に従えるようにします。ワークステーションのリポジトリにユーザー共通のリリースルールがある場合は、そこから開始します。
• フォルダー標準：orchestrating/folder-standard.md の .gitignore の行です。
• 許可のみのプロジェクト権限：グローバルルールはマシンの安全柵であり、プロジェクト独自のハーネスファイルは利便性を加えるだけです。監査では、グローバルルールを弱めるプロジェクトファイルをすべて検出します。

現状を調査して、見つかった内容を提示し、ユーザーの確認を得てから書き込みます。再実行すると監査になります。

手順

1. マシンを確認する

このスキルと同じ場所にインストールされている set-up-machine スキルから、検証スクリプト python3 <set-up-machine skill>/scripts/verify.py を実行します。成功時の終了コードは 0 です。終了コードが 0 でない場合は、まず set-up-machine スキルを実行してから、ここに戻ってください。検証スクリプトの終了コードが 0 になれば完了です。

2. 調査する

現在のリポジトリを調べ、初期状態を把握します。存在するファイルを読み、決めつけないでください。

• git remote -v と .git/config：GitHub リポジトリですか？どのリポジトリですか？
• リポジトリのルートにある AGENTS.md と CLAUDE.md：どちらかが存在しますか？どちらかに ## Agent skills または ## Environment defaults セクションがすでにありますか？
• リポジトリのルートにある GLOSSARY.md と GLOSSARY-MAP.md、およびリポジトリ内の CONTEXT.md や CONTEXT-MAP.md：スキルが現在は読み込まない、ドメインドキュメントの旧名称です。
• docs/adr/ と、src/*/docs/adr/ ディレクトリがあるかどうか
• docs/agents/：このスキルが以前に生成したファイルがすでにありますか？
• .efforts/：ローカル Markdown のイシュートラッカーがすでに使われている目印です。
• docs/assets/：フォルダー標準における旧画像フォルダーです。
• triage スキルがインストールされていますか？このスキルの隣に triage スキルのフォルダーがあるか、利用可能なスキルに triage が含まれていれば、インストール済みです。これにより、セクション B を実行するかどうかが決まります。
• モノレポの兆候：pnpm-workspace.yaml、package.json の workspaces フィールド、または独自の src/ を持つ、内容のある packages/*。これらが存在するのは、真に大規模な複数パッケージのリポジトリに限られます。存在しない場合は単一コンテキストであり、ほとんどのリポジトリが該当します。
• 現在のプロジェクトのリリース方法：CHANGELOG.md、バージョンを記載したファイル、タグ、gh release list で表示される GitHub リリース、レジストリに公開するもの、AGENTS.md や他のドキュメントに記載されたリリース手順を探します。"private": true の設定がない package.json、Homebrew cask、リリースワークフローは、それぞれレジストリに公開します。これらの兆候をもとに、セクション E を実行するかどうかを判断します。
• ユーザー共通のリリースルール：ポインター ~/.config/agents/source.md にワークステーションのリポジトリが指定されている場合、<path-to-workstation-repo>/setup/releasing.md があれば読み込みます。ポインターまたはファイルがない場合は、シードテンプレートのみを出発点にします。
• プロジェクト独自のドキュメントで、ロール用スキルの名前として必要とされているツール。たとえば、docs/worktrees.md に記載された worktree ツールや、スクリプトが前提とするセッションホストなどです。これにより、セクション D を実行するかどうかが決まります。

3. 調査結果を提示して質問する

存在するものと不足しているものを要約します。その後、セクションを順番に進めます。1つのセクションにつき回答を1つ受け取ってから、次へ進みます。

各セクションの冒頭では、ユーザーが一言で承諾できるよう、推奨する回答を提示します。選択肢によって結果が実際に分かれる場合に限り、1行で説明します。調査で結論が出ている場合は、そのセクションを省略します。 triage がインストールされていない場合はセクション B を、モノレポがなく、古い CONTEXT.md または CONTEXT-MAP.md もない場合はセクション C を、プロジェクトで役割に対応するツールが指定されていない場合はセクション D を、プロジェクトがリリースしたことがなく、リリースを示す兆候もない場合はセクション E を省略します。

セクション A：イシュートラッカー

説明：このリポジトリでイシューを管理する場所が「イシュートラッカー」です。to-tickets、triage、to-spec などのスキルは、そこからイシューを読み書きします。gh issue create を呼び出すのか、.efforts/ 配下に Markdown ファイルを書くのか、あるいは別のワークフローに従うのかを、それらのスキルが把握できるようにする必要があります。このリポジトリで実際に作業を追跡している場所を選びます。

デフォルトでは、これらのスキルは GitHub 向けに設計されています。git remote が GitHub を指している場合は、GitHub を提案します。git remote が GitLab（gitlab.com またはセルフホストのホスト）を指している場合は、GitLab を提案します。 それ以外の場合、またはユーザーが別のトラッカーを希望する場合は、次の選択肢を提示します。

• GitHub：イシューはリポジトリの GitHub Issues で管理し、gh CLI を使います。
• GitLab：イシューはリポジトリの GitLab Issues で管理し、glab CLI を使います。
• ローカル Markdown：イシューはこのリポジトリの .efforts/<effort>/ 配下のファイルとして管理します。個人プロジェクトやリモートのないリポジトリに適しています。
• その他（Jira や Linear など）：ユーザーにワークフローを1段落で説明してもらい、自由記述の文章として記録します。

選択内容は docs/agents/issue-tracker.md に記録します。GitHub と GitLab のテンプレートには、「PR を要望受付の窓口にする」フラグがあり、デフォルトではオフです。オフのままにして、この点は持ち出さないでください。外部からの PR を triage キューに入れたいユーザーは、後からファイル内のフラグを切り替えられます。

セクション B：triage のラベル語彙

調査の結果、triage スキルがインストールされていないと分かった場合、このセクション全体を省略します。インストールされていないスキルにはラベルが不要なためです。

インストールされている場合は、次の質問を1つだけします。

triage のデフォルトラベルを使い続けますか？推奨する回答は はい です。

デフォルトは、名前と同じ文字列をラベルとする5つの標準的な役割です。needs-triage、needs-info、ready-for-agent、ready-for-human、wontfix です。はいの場合は、そのまま記述します。ユーザーが「いいえ」と答えた場合に限り（通常は、トラッカーですでに needs-triage に対して bug:triage など別の名前を使っている場合）、triage が重複ラベルを作成するのではなく、既存のラベルを適用するように、上書きするラベル名を確認します。

セクション C：ドメイン文書

デフォルトは単一コンテキストとします。これは、リポジトリのルートに GLOSSARY.md を1つ、docs/adr/ を1つ置く構成です。 ほとんどすべてのリポジトリに適しているため、質問せずにこの構成を記述します。

マルチコンテキスト（ルートに GLOSSARY-MAP.md を置き、コンテキストごとの GLOSSARY.md を参照する構成）は、調査でモノレポの兆候が見つかった場合に限って提示します。そのうえで、どちらの構成にするか確認します。

調査で古い CONTEXT.md または CONTEXT-MAP.md が見つかった場合は、履歴を引き継ぐため、それぞれを git mv で名前変更することを提案します。git mv CONTEXT.md GLOSSARY.md、git mv CONTEXT-MAP.md GLOSSARY-MAP.md、およびコンテキストごとの各 CONTEXT.md についても同様です。新しい名前のファイルがすでに存在する場合、git mv は失敗します。その場合は、古いファイルの内容を新しいファイルに統合することを提案し、内容が食い違う箇所ではどちらを優先するか尋ねます。また、マップ内のリンクと、古いファイル名を記載しているその他のファイルを更新することも提案します。AGENTS.md と docs/agents/domain.md のドラフトでは、すでに新しい名前が使われています。

調査で docs/assets/ フォルダーが見つかった場合は、各トピックを git mv で移動することを提案します。方法は ../orchestrating/folder-standard.md の「古いレイアウトからの移行」に記載されています。プロジェクトが配布または表示する画像は assets/images/<topic>/ に、スクリーンショットは assets/screenshots/<topic>/ に移動し、それらへの相対リンクも更新します。

セクション D：プロジェクト環境のデフォルト

何も推奨しません。 調査でプロジェクトが特定の役割に必要とするツールが見つかった場合に限り、確認してください。その場合は、そのツールの ## Environment defaults の行を提案します。この行は、このプロジェクトにおいてユーザーのグローバルな行より優先されます。agents-md.md > 「Environment defaults」に、ここに記載できる内容が書かれています。

セクション E：リリースライフサイクル

releasing.md をもとに docs/agents/releasing.md を作成することを推奨します。ユーザー共通のリリースルールを適用し、調査で判明した内容、つまりリリースに含まれるもの、リリースの順序、各手順の担当者を記載します。 ページは短くし、各手順を1〜2行にまとめます。 バージョンルール、変更履歴の形式、タグとリリースノートの書式など、共通ルールにすでに記載されている内容は省きます。また、コマンド、インストール手順、プロジェクトがまだ使用していないレジストリの計画も省きます。 プロジェクトのやり方が共通ルールに記載されていない場合は、プロジェクトのやり方を維持し、その旨を明記します。 両者に相違がある場合は、両方を示し、このプロジェクトでどちらに従うかを確認します。 リリース手順がすでに別のドキュメントに記載されている場合は、docs/agents/releasing.md への移動を提案し、元の場所には参照を残します。

4. 確認して書き込む

次のドラフトをユーザーに提示します。

• AGENTS.md：新規作成する場合は agents-md.md をもとに作成します。既存のものがある場合は、## Agent skills ブロックと追加する ## Environment defaults の各行を加え、既存の CLAUDE.md の各行を移します
• CLAUDE.md：@AGENTS.md の1行のみ、または既存の AGENTS.md へのシンボリックリンクはそのままにします。CLAUDE.md が存在すると Claude Code はプロジェクトの AGENTS.md を読み込まず、どちらの形式でも同じ内容が適用されます
• .gitignore：.scratch/ と .claude/worktrees/。それぞれ不足している場合に限り追加します
• docs/agents/issue-tracker.md と docs/agents/domain.md の内容、triage がインストールされている場合は docs/agents/triage-labels.md の内容、セクション E を実行した場合は docs/agents/releasing.md の内容
• セクション C で提案した場合は、既存の CONTEXT.md または CONTEXT-MAP.md の名前変更または統合と、それらを参照するファイルへの編集
• 提案した場合は、docs/assets/ からの各移動と、その移動に伴うリンクの更新

ユーザーに編集してもらった後、すべての変更について一度だけ承認を得ます。その後、次の内容を書き込みます。

1. AGENTS.md を編集し、CLAUDE.md は決して編集しません。## Agent skills ブロックがすでにある場合は、重複を追加せず、その内容をブロック内で更新し、周囲にあるユーザーの編集は維持します。### Triage labels サブブロックは triage がインストールされ、セクション B を実行した場合に限り含めます。### Releases サブブロックはセクション E を実行した場合に限り含めます。

2. @AGENTS.md の1行を含む CLAUDE.md、または AGENTS.md へのシンボリックリンクはそのままにし、不足している .gitignore の行を追加します。

3. このスキルフォルダー内のシードテンプレートを出発点として、次のドキュメントファイルを作成します。

   • issue-tracker-github.md：GitHub の課題トラッカー
   • issue-tracker-gitlab.md：GitLab の課題トラッカー
   • issue-tracker-local.md：ローカル Markdown の課題トラッカー
   • triage-labels.md：ラベルのマッピング。triage がインストールされている場合に限り作成します
   • domain.md：ドメインドキュメントの利用ルールと構成
   • releasing.md：リリースライフサイクル。セクション E を実行した場合に限り作成します

   「その他」の課題トラッカーについては、ユーザーの説明をもとに docs/agents/issue-tracker.md を一から作成します。

   すべての docs/agents/issue-tracker.md に、テンプレートの ## Title prefixes セクションを含めます。これにより、各スキルが同じ形式で課題にタイトルを付けられます。その意味リストには、プロジェクトの未解決課題のタイトルにすでに使われている領域を選び、それぞれの領域が対象とする内容を1行ずつ記載します。

4. 承認された既存の CONTEXT.md または CONTEXT-MAP.md の名前変更や統合を実行し、それを参照していたファイルを更新します。

5. 承認された docs/assets/ からの移動を実行し、対象へのリンクを更新します。

承認された変更をすべて実施したら完了です。

5. 監査

このマシンでセットアップされているかどうかにかかわらず、プロジェクトが保持するすべてのハーネスファイルをルートから順に確認し、set-up-machine の rules.json と照合します。.claude/settings.jsonとsettings.local.json、.cursor/cli.json、opencode.jsonまたはopencode.jsoncと.opencode/、.codex/config.toml` が対象です。references/project-files.md には、各ハーネスでプロジェクトファイルがグローバルルールにどのような影響を与えられるか、また各項目をどう判断するかが記載されています。各指摘は次のように報告します。

• weakens：いずれかのハーネスで、マシンに設定された状態ではグローバルルールが適用されなくなっています。どのルールが、なぜ適用されなくなるかを説明し、修正案を提示します。項目を削除するか、プロジェクト独自のコマンドに範囲を絞ります。ファイルはプロジェクトのものなので、ユーザーの承認を得てから変更します。
• overlaps：ルールが有効なまま、そのコマンドを対象とする許可設定があります。範囲を絞ることを提案します。
• extra：プロジェクトの拒否または確認要求の設定です。gap：判断できない内容です。それぞれを明記します。

リポジトリ内に残っている古い CONTEXT.md または CONTEXT-MAP.md もすべて報告し、Section C が提案するそれぞれの改名先を示します。## Title prefixes セクションがない docs/agents/issue-tracker.md があれば報告し、ステップ 3 で作成するセクションを提案します。リリースの兆候があるのに docs/agents/releasing.md がないプロジェクト、およびユーザーの共有リリースルールと食い違う docs/agents/releasing.md があれば報告し、Section E で更新する内容を提案します。

weakens がなければ監査に合格です。合格するか、ユーザーが weakens の項目を残すことを選択した時点で完了です。その場合、監査は不合格のままであり、レポートには該当する項目を記載します。

6. 完了

セットアップが完了したこと、監査で見つかった内容、今後どのスキルがこれらのファイルを参照するかをユーザーに伝えます。後から AGENTS.md と docs/agents/*.md を直接編集できることも伝えます。このスキルを再実行すると、プロジェクトを再監査し、共有リリースルールが変わった場合はリリースページを更新し、ユーザーの希望に応じて課題トラッカーを切り替えます。コミットはユーザー、またはこのスキルを呼び出したスキルに任せます。