bmad-project-context

概要

リポジトリのエージェント指示を生成する会話です。AGENTS.md 内の、検証済みの小さなブロックを作成します。ユーザーは守ってほしいルール（ガバナンス、セキュリティ、標準）を持ち込み、リポジトリが残りを提供し、それが検証されます。

常に対話形式で進め、すべての書き込みをユーザーが承認します。

引数: intent (setup | adopt | refresh | record | audit)、対象リポジトリまたはパス、追加のソースパスまたは URL。

解決ルール

• ベアパスと {skill-root}（例: references/best-practices.md）は、このスキルのインストールディレクトリから解決されます。
• {project-root} → プロジェクトの作業ディレクトリ。
• Target → 記述対象のリポジトリで、デフォルトは {project-root} です。複数の作業ツリーに解決される場合、またはユーザーがコミットできない作業ツリーに解決される場合は、書き込む前に確認してください。

有効化時

1. カスタマイズを解決します: uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --project-root {project-root} --key workflow。

   • スクリプトが見つからない場合: ここでは BMad がセットアップされていません。bmad スキルのセットアップを実行することを提案し、まだお持ちでなければ先に bmad をインストールして（npx skills add bmad-code-org/BMAD-METHOD --skill bmad）、その後コマンドを再度実行してください。
   • その他の失敗: {skill-root}/customize.toml を直接読み、デフォルトを使用してください。

   {workflow.activation_steps_prepend} を実行し、{workflow.persistent_facts} のエントリを常設コンテキストとして扱ってください（file: = 読み込むパス/glob、それ以外はそのまま）。

2. 設定: {project-root}/_bmad が存在する場合は、uv run {project-root}/_bmad/scripts/resolve_config.py --project-root {project-root} を実行し、{output_folder} を読み取ってください。スタンドアロンの場合はスキップします。

3. 何よりも先に references/best-practices.md と references/template.md を読み込んでください。 以下のすべての判断は、これらに基づいて行われます。

4. intent を検出してユーザーに挨拶します: setup（対象内のどの指示ファイルにも意味のある内容がない場合 — 足場だけ、空の見出し、コメント、単独の import 行は意味があるとは見なしません。判断に迷う場合は adopt を選んでください。ほぼ空のファイルを adopt しても小さな台帳が 1 つ増えるだけですが、意味のあるファイルを setup すると指示が失われるためです）、adopt（指示ファイルに内容はあるが管理対象ブロックがない場合。その状態や作成者が誰であっても該当します — refresh の移行形態です。そのファイルがベースラインとなり、その中のすべての指示がステップ 1 の台帳に入ります）、refresh（管理対象ブロックが存在する場合）、record（ユーザーがエージェントの犯したミスを報告する場合）、audit（再検証して不要なものを削除する場合）。提供された intent が検出結果と矛盾する場合 — たとえば内容のあるファイルに対して setup — は、それを明示して確認を求め、決して黙って従わないでください。{workflow.external_sources} をソース一覧に組み込んでください。{workflow.activation_steps_append} を実行してください。

セットアップ、導入、リフレッシュのステップ

ステップ 5 まで書き込みは行いません!

1. 評価と報告

AGENTS.md、ハーネスまたはエージェント固有のルールファイル、docs フォルダー、および教訓を含むあらゆるメモを読みます。best-practices.md に従って、何が存在するか、それがどの程度基準を満たしているかを報告します。

既存の指示は改善対象のベースラインであり、決して捨てるべき原材料ではありません。台帳を開きます。既存のセクションごと、および独立して意味を持つ指示ごとに 1 項目を作成し、retain または rewrite として起票し、それがないとエージェントが何を誤るかを記載します。項目はステップ 2～4 で証拠が集まるにつれて確定します — retain | rewrite | relocate | automate | delete、それぞれに理由、証拠、それが失われた場合のリスク、移転の場合は移転先、および承認フラグを伴います。削除には best-practices.md にある 4 つの根拠のいずれかが必要であり、移転先はそれ自体が読み込まれるか、観測可能なトリガーの背後に置かれていなければなりません — 何も読まないファイルへの移動は削除であり、その根拠が必要です。セットアップにはマッピングするものがなく、台帳も開きません。リフレッシュでは、変更または削除を提案する行について項目を開きます。ブロック自身の行も含みます。指示ファイルの外で見つかった教訓 — README の警告、メモファイルなど — は通常の候補であり、台帳の項目ではありません。

対象に分離可能な単位が含まれる場合 — メンバーを列挙するワークスペースマニフェスト、または独自のビルドマニフェストを持つディレクトリ — それらに名前を付け、この実行がルートのみを対象とするのか、それらすべてを対象とするのか、あるいはどれを対象とするのかを尋ねます。その証拠がなければ、尋ねません。兄弟リポジトリは子ではありません。それぞれが独自の対象であり、順番に提示されます。

2. 何を持ち込むかを尋ねる

リポジトリが何をするかに関係なく従うべきルール：ガバナンス、セキュリティとコンプライアンス、コーディング標準、スタイルガイド、凍結領域。外部ドキュメントも求めます — ハンドブック、wiki、アーキテクチャドキュメント、MCP ナレッジベース。パスを記録し、まだ読みません。

グリーンフィールド：これが内容のすべてです。ブラウンフィールド：これはスキャンが届かない半分です。

3. 発見と検証

セクションが必要とするものに対して、並列サブエージェントで展開します — ポリシーおよびそれらがすでに述べている内容については実行可能な設定と CI、規約と境界については追跡されたソース、理由が今も成り立たなければならない制約については的を絞った履歴。

package.json、Makefile、pyproject.toml、コントリビューションガイド、プルリクエストテンプレート、および CI 設定は、ブロックが繰り返してはならないものを知るために読みます。それらの注意事項はステップ 4 で人間から得ます。ファイルに言及するすべての主張をパスチェックします。ブロックがコマンドの動作について行うすべての主張について、それを実行する対象またはスクリプトを読み、主張を検証します。

ステップ 1 で合意された各子は、独自のマニフェストに対して、独自のスコープとしてスキャンされます。

4. ギャップをインタビューする

スキャンが届かないものだけ：ここでエージェントが繰り返し間違えること、立ち入り禁止の領域、ドメイン用語の意味、制約が存在する理由。

• スキャンが答えられることを決して尋ねないでください。パスチェック済みの主張、または設定ファイルがすでに述べている主張の確認をユーザーに求めるのは、欠陥です。
• レビューリストではなく、想起質問をしてください。スキャンが生み出した選択問題をユーザーに決して渡さないでください。
• このセッションで犯し、捕捉した誤りは観測された証拠です — それを提示してください。
• このセッションで読んだもの — ログ、ドキュメント、それ自体の実行 — の中で見つかった再現可能なコマンドで、その正しい形式が明白な推測ではないものは候補行です：それを提示してください。例：uv run pytest、ここでは単なる pytest が正しそうに見えますが、プロジェクト環境の外で実行されます。
• バッチは最大 8 件、少ないほど良いです。新しいものが何も得られないバッチは、書くという意味です。
• リポジトリがユーザーと矛盾する場合、証拠を示して尋ねます。主張をそのまま書いたり、黙って落としたりしないでください。

5. ブロックを提示してから、書き込む

template.md に対して構成します。各候補について、まずフック、lint ルール、または CI チェックのほうが散文よりもうまくそれを強制できるかどうかを問い、そうであればそのチェックを提案し、その行はユーザーが断った場合のフォールバックになります。automate と記された台帳エントリは、そのチェックが整うまで指示を保持します（チェックが稼働した後の実行で、根拠 2 に基づいてその行を削除します）。

書き込む前に完全なブロックを提示し、それと並べてすべての子ブロックも提示します — 1 回の承認でそのセット全体をカバーします。確定した台帳も一緒に提示します: 置換テキストだけでは不完全な提案です。ユーザーが何を得るかは示しますが、何を失うかは隠すからです。既存のすべての指示は、その決定と理由とともに示されます。完全なルールを保つ保持と書き換えは、まとめてグループ化してもかまいません。書き換えがルールの一部を弱めたり、狭めたり、落としたりする場合は、失われた部分を削除として扱い、別途リストアップします。ルール自体は保ってください。例はそれを説明できますが、置き換えることはできません。すべての移設、自動化、削除は項目別に記載します。最初の 3 つの根拠のいずれにも依拠しない削除は、行単位の承認のために保留されます — ブロックを承認してもそれが承認されることはありません — また、断られた削除、移設、自動化は保持に戻ります。承認されたら、マーカーの間でスプライスします — スプライス自体はマーカーの外側に何も触れません。マーカーの外側のテキストは、確定した台帳エントリ、またはユーザーが確認した提案された修正を通じてのみ変更され、スプライスの副作用として変更されることは決してありません。各来歴行には、今日の日付と検証済みの SHA を記入します。

他の場所にある指示が、振る舞いを変える形でブロックと矛盾する場合 — 古くなった CLAUDE.md の行、廃止されたコマンドなど — そのファイルへの修正を提案します。2 つの生きた矛盾する指示は欠陥です。

決してコミットしないでください。

6. 締めくくり

• 何が入り、何が除外され、その理由、そして採用またはリフレッシュ後には、各既存の指示がどこに落ち着いたか。
• ユーザーの言葉で、best-practices.md に基づく理由 — なぜそれが小さいのか、なぜリポジトリがすでに述べていることは除外されるのか、なぜ落とし穴はその原因がなくなるまで残るのか。
• どのように読み込まれるか、そして他のハーネスファイルがそれを指し示せること。
• ユーザーがこれらの指示変更を提出する際に適用される、ブランチ、チケット、コミット、プルリクエストのルール。
• メンテナンス: 重要な変更の後に再実行し、エージェントが何かを間違えた瞬間に record し、新しい行よりもチェックを優先する。
• プロジェクト間で繰り返されるルール、またはチームのものではなく個人的なルールは、ユーザーのグローバルエージェント設定に属します。

{workflow.on_complete} を実行します。

リフレッシュ

同じ手順で、ステップ 1 を差分として行います。来歴行を読み、すべてのパスとすべての注意事項を再検証し、記録された SHA 以降の git log --diff-filter=DR --name-only をすべての行に対して実行します — 証拠が失われた行は更新または削除します。提案されたすべての削除は、ステップ 5 に示される台帳エントリであり、決して黙った編集ではありません。また、ブロック外の手書きの指示は採用時と同様に扱われます — それらに触れる提案は台帳に入ります。以前の実行が確定したことを再度尋ねないでください。インタビューは、チームの働き方がどう変わったかに縮小します。ブロックは新しい証拠にのみ基づいて成長します。

採用

このスキルが一度も触れたことのない指示に対してリフレッシュします。以前の実行では何も確定していないため、完全なインタビューが適用されます — そしてファイル自体がメンテナの証言であるため、台帳が実行の主要な成果物です: ユーザーはそれを読んで、自分の各指示がどこへ行ったかを確認できるべきです。

提案は、指示がそこから移された各ファイルに何が残るかを述べます — 一般には、使用中のすべてのハーネスに対してそのインポートが検証された後、他のあらゆる読み込みメカニズムと同様に、CLAUDE.md が @AGENTS.md に縮小されるといった形です。どの指示も 2 つの読み込まれたファイルに存在してはなりません。そこでは二重に支払うことになります。重複は、逐語的であれ言い換えであれ、一度だけ保たれます — ブロックが生き残ったほうを保持します — そしてそれで両方のエントリが確定します。

Greenfield

イニシアチブのチケット（initiative-.md、または古い SPEC*.md）を全文読むか、計画書を読むか、インタビューのみをもとに着手します。まだ存在しないコマンドは、決定済みのスタックを明記した明確な TODO として記載し、推測した実行方法を事実として書いてはいけません。コードができた後の最初の更新時に検証します。実際に意見が分かれる設計上の決定（現実的なトレードオフがあり、複数の有効な形があるもの）は、bmad-architecture に任せます。

Migration

移行対象に、廃止されたスキルから引き継いだ project-context.md がある場合（一般的には {output_folder} 内）、ステップ 1 で読み込み、その内容を取り込むことを提案します。合意なく削除したり、黙って取り残したりしてはいけません。

記録

発生したエージェントのミスを 1 件、その場で記録します。落とし穴の根拠として認められる情報源はこれだけです。

タスク、ミス、修正、その証拠を記録します。そのブロックに、すでに該当する行があるか確認します。1 回の発生は記録し、繰り返されるミスやコストの大きいミスは、今すぐ 1 行追加します。コマンドの誤りなら 実行と検証 に正確な実行方法を、それ以外なら落とし穴として記載します。記載したら差分を表示します。機械的に防げる場合は、代わりにフック、lint ルール、または CI チェックを提案します。{workflow.on_complete} を実行します。

監査

すべての注意事項を再確認し、すべてのファイルのパスを確認し、参照先をすべてたどります。また、各行について、削除するとエージェントの動作が変わるかを確認します。コマンドに関する記述は、対象または実行するスクリプトに照らして検証します。他の指示ファイルとの矛盾がないか確認します。

問題のある行は修正するか、観察可能なトリガーが発生するまで保留するか、台帳に記録します。削除する場合は、best-practices.md にある 4 つの根拠のいずれかを示し、ステップ 5 の手順に従って提示し、合意を得てから削除します。ポリシーや落とし穴を削除できるのは、それが防いでいる問題がなくなった場合、またはユーザーが廃止した場合だけです。最近問題が起きていないことは根拠になりません。 監査の結果、内容は同等以下になります。{workflow.on_complete} を実行します。

子要素

コンポーネント、ネストされたリポジトリ、または切り出したルールファイルについて、作業が継続的に発生し、かつ次の条件をすべて満たす場合は、同じ構成で独自のファイルを用意します。ルールがそのサブツリーに固有であること、相応の量があること（数個程度のルールではファイルにしません）、分割によって親ブロックが大幅に短くなること、使用中のすべてのハーネスで読み込み方法を確認済みであること（推測ではなく検証済みであること）、そしてユーザーが分割を承認していることです。読み込みが確認済みでも、セッションがそのディレクトリに入る前に適用する必要があるルールや、違反が子要素の外側の作業に影響しうるルールは、ルートに残します。それ以外のルールは、パスを指定した行（「src/importer/ では……」）として親ブロックに残します。誰も読み込まないファイルを作るより、そのほうが手間がかかりません。読み込みを確認する理由については best-practices.md を参照してください。

トリガーがパスではない場合に限り、リンクされたファイルを使います。

選択した子要素に、親ですでに記載されている内容しか残らない場合は、ファイルを作成しません。その旨を伝えて次に進みます。

子要素はすべて、親の 構成 にそれぞれ 1 行でパスとともに記載します。検出方法は、ハーネスがファイルを見つけられるかどうかに依存させません。