AIエージェント向けの指示書を整えるとき、つい「どのフォルダーに何を置くか」という話になりがちです。しかし、ディレクトリー名をそろえるだけでは、情報の重複や古い計画の上書き、実行環境ごとの読み込み差は解消できません。

軸にしたいのは、情報の役割、正本となる場所、保存期間、読み込み契約の4つです。BMADの作業管理と、プロジェクト知識を領域ごとに分ける「ブループリント」は組み合わせられますが、計画の保存やテストの扱いまで一律に決める必要はありません。

BMADが示すのは、固定のフォルダー構成ではない

手元で確認したBMADの資料では、対象のブランチはV7プレビュー、v6.12は安定版の位置づけとして説明されています。ここで扱うのはあくまで確認したローカル資料の内容であり、現在の最新リリースを示すものではありません。

その資料から読み取れるのは、特定のディレクトリーを全プロジェクトに強制することより、次のような運用上の考え方です。

• 標準とカスタマイズを分ける。 標準の資産を丸ごと複製するのではなく、チームや個人の変更点を必要な範囲に絞る。
• 作業の所属先を明確にする。 initiative、epic、個別タスクといった作業の階層に、要件、設計、計画、振り返りを結び付ける。複数リポジトリーにまたがる計画は、独立して管理する場合もある。
• 詳細は必要になってから具体化する。 早い段階で大量の詳細を書き切るのではなく、精緻化や実装などの段階に応じて成果物を整える。
• 完了した計画も追跡できるようにする。 状態、着手時のバージョン、実装の証拠、レビューで見つかった事項などを残せば、過去の作業を後から確認できる。

要するに、共通するのは「作業に帰属先がある」「参照先を特定できる」「状態の正本が分かる」「完了の根拠を追える」という点です。

ブループリントとBMADは、同じ課題を扱っていない

ブループリントが中心に置くのは、プロジェクト知識の分類や読み込み方です。一方、BMADは作業の進め方と成果物の管理にも重きを置きます。どちらか一方で他方を置き換えるというより、異なる層の設計として考えるのが自然です。

• 小規模で一人が順番に進めるプロジェクトなら、作業中の焦点を一つに絞り、必要な領域の資料を読む方式は始めやすいでしょう。ただし、活動中の一覧が唯一の計画記録を上書きする形にはしないほうが安全です。
• チームで並行作業をする場合や複数リポジトリーにまたがる場合は、安定したタスクIDと個別の計画を持たせるほうが追跡しやすくなります。「活動中の計画が一つ」というルールは、チーム全体に一つしか計画ファイルを認めない意味ではなく、セッションごとの作業焦点として捉えるのが適切です。
• 特定のエージェント環境に依存しない運用では、常設ルールを絞り、どの条件でどの資料を読むかを明示するのが有効です。
• 独自の拡張を行う場合は、状態の集約や証拠の検査など、その仕組みが実際に用意されていることを確かめます。ディレクトリーやプロンプトの存在だけで、そうした機能が実現したとは言えません。

見直したい5つのルール

1. 完了したら上書き、ではなく「表示を圧縮して記録は残す」

完了した計画を普段の読み込み対象から外すことと、計画そのものを消したり上書きしたりすることは別です。履歴を簡潔な一覧にまとめながら、状態や根拠をたどれる記録は残す。これなら、作業の見通しと追跡可能性を両立できます。

2. 共通の橋渡しルールだけで、すべての実行環境に対応できるとは限らない

エージェントがどのファイルを、どの範囲で読み込むかは、ホストとなるツールに左右されます。BMADの資料でも読み込み機構、特に入れ子になったルールの扱いを検証する必要性が示されています。OpenAIの例でも、Codexが認識するAGENTS.mdと、利用者が調整するワークフロー上のファイル構成は区別されています。6

したがって、共通の指示書を用意したうえで、各ホストの読み込み方は個別に確認するのが現実的です。

3. 行数の上限を、幻覚を防ぐ万能策にしない

常設ルールを短く保つことは役立ちますが、特定の行数を超えたら一律に機能しなくなる、という基準はここで確認できる資料からは導けません。実際の読み込み量、重複、他の指示との意味上の依存関係を見て調整し、重要な契約が分割によって切り離されないようにします。

4. テスト用ディレクトリーのJSONを、すべて同じ扱いにしない

固定され、機密情報を含まず、再現可能なテスト用フィクスチャと、一度の実行で生成されるログや出力は性質が異なります。ユニット、統合、エンドツーエンド、実環境での検証についても、実行環境や副作用を分けて定義すべきです。

5. 無視対象の領域を、そのまま履歴保管庫にしない

Gitの除外設定、通常の検索対象から外すこと、アクセスを禁止することは別の制御です。さらに、履歴を残したい一方でGitには登録しない、という運用には整合性の問題が生じます。何を保管し、何を検索対象にし、誰がアクセスできるかを分けて設計しましょう。

公開事例から学べること、一般化しすぎないこと

Geoffrey HuntleyのRalphに関する記事は、単一プロセスのループで一度に一つの作業に取り組む方法を説明しています。14 また、同氏のガイドでは、関心領域ごとに仕様をまとめたり、ビルドやテストの実務上の知見をプロジェクトの案内に置いたりする例が示されています。11

ここから得られるのは、小さな作業単位、明確な仕様、限られたコンテキスト、実際のフィードバックを組み合わせるという考え方です。すべてのプロジェクトに同じディレクトリー構成を強制する根拠ではありません。

一方、OpenAIの複雑なタスク向けの例は、長い作業では詳しい実行計画を使う方法を示しています。5 常設の案内を簡潔にすることと、個別タスクに十分な計画を持たせることは両立します。

実務では、次のように整理できます。

• 常設ルールは簡潔にし、タスク計画の詳しさはリスクや所要時間に応じて変える。
• 領域別の仕様を用意しつつ、領域をまたぐ重要な不変条件への参照も残す。
• ループやセッションを再開するときは、会話履歴全体ではなく、現在のタスクに必要な文脈を組み直す。
• ビルドやテストの案内には、確認できたコマンドと前提条件を書く。

なお、Ralphの派生実装やコミュニティーの説明を、Huntley本人の原文の主張として扱うべきではありません。特定の実装に関するテスト隔離の詳細など、根拠を確認できない点は一般論として断定しないことが大切です。

エージェント向け文書を整える10の原則

1. 書き手ではなく、情報の役割で分類する。 人が書いたから正しい、機械が生成したから一時的、と決めつけず、方針、確認済みの事実、提案、作業状態、検証記録、探索中の草稿を区別します。
2. 重要な事実には、編集できる正本を一つ設ける。 要約や索引で情報を再掲する場合は、出典、版、古くなる条件を分かるようにします。
3. ソースコードからは分からない知識を優先して記録する。 意図、採用しなかった理由、外部制約、コンポーネント間の責任分担は、コードの構造を読むだけでは確定できないことがあります。
4. 入口の文書には、制約と案内を書く。 「必要なら読む」のような曖昧な指示に頼らず、対象のパスやインターフェース、タスクの種類など、観察できる条件で参照先を示します。
5. 仕様・状態・証拠の役割を分ける。 仕様は「何を満たすべきか」、状態は「どこまで進んだか」、証拠は「なぜ満たしたと言えるのか」を示します。同じファイルに置く場合も、正本がどれかを明確にします。
6. 要約しても、再開に必要な情報は落とさない。 未完了事項、阻害要因、依存関係、権限の境界、証拠の場所を残します。過去の成功が、新しい実行の成功を保証するわけではありません。
7. 履歴を追える状態と、現在有効なルールの見つけやすさを両立する。 置き換えられた判断も根拠と関係を残し、領域別の仕様には現在有効な決定を参照させます。
8. テスト用の資産と実行時の出力を分ける。 既存の言語・フレームワークの慣習を尊重し、ログなどの出力は機密性、容量、保存期間に応じて扱います。
9. 機械で守れるルールは、実際の検査機構に任せる。 ただし、誰も読まない文書へルールを移しただけでは負担軽減になりません。チェックが未実装なら、文章上の制約を置き換えたことにもなりません。
10. ディレクトリー上の約束を、実行権限と混同しない。 文書生成、コマンド実行、外部への通信、デプロイ、保管はそれぞれ別に許可します。草稿用のフォルダーが実行時のサンドボックスになるわけではありません。

まず文書の役割を決め、移行はその後に

おすすめの順序は、最初に成果物の役割と正本を定め、次に利用するホストの読み込み仕様を確かめることです。その後、現在の作業を見渡す簡潔なビューを用意し、実際の作業で得たフィードバックをもとに情報量や保存方針を調整します。いきなりプロジェクト全体のディレクトリーを移し替える必要はありません。

また、静的な構造の調査、業務上の事実、ホストによる指示書の読み込みは、それぞれ別の問題です。自動生成した文書が存在することだけで、それが承認済みの規範になったと見なさず、確認と採用の手順を設けることが重要です。

ここでの提案は文書管理の設計指針であり、特定のプロジェクトへの実装や変更を承認するものではありません。

AIエージェント向けの指示書を整えるとき、つい「どのフォルダーに何を置くか」という話になりがちです。しかし、ディレクトリー名をそろえるだけでは、情報の重複や古い計画の上書き、実行環境ごとの読み込み差は解消できません。

軸にしたいのは、情報の役割、正本となる場所、保存期間、読み込み契約の4つです。BMADの作業管理と、プロジェクト知識を領域ごとに分ける「ブループリント」は組み合わせられますが、計画の保存やテストの扱いまで一律に決める必要はありません。

BMADが示すのは、固定のフォルダー構成ではない

手元で確認したBMADの資料では、対象のブランチはV7プレビュー、v6.12は安定版の位置づけとして説明されています。ここで扱うのはあくまで確認したローカル資料の内容であり、現在の最新リリースを示すものではありません。

その資料から読み取れるのは、特定のディレクトリーを全プロジェクトに強制することより、次のような運用上の考え方です。

• 標準とカスタマイズを分ける。 標準の資産を丸ごと複製するのではなく、チームや個人の変更点を必要な範囲に絞る。
• 作業の所属先を明確にする。 initiative、epic、個別タスクといった作業の階層に、要件、設計、計画、振り返りを結び付ける。複数リポジトリーにまたがる計画は、独立して管理する場合もある。
• 詳細は必要になってから具体化する。 早い段階で大量の詳細を書き切るのではなく、精緻化や実装などの段階に応じて成果物を整える。
• 完了した計画も追跡できるようにする。 状態、着手時のバージョン、実装の証拠、レビューで見つかった事項などを残せば、過去の作業を後から確認できる。

要するに、共通するのは「作業に帰属先がある」「参照先を特定できる」「状態の正本が分かる」「完了の根拠を追える」という点です。

ブループリントとBMADは、同じ課題を扱っていない

ブループリントが中心に置くのは、プロジェクト知識の分類や読み込み方です。一方、BMADは作業の進め方と成果物の管理にも重きを置きます。どちらか一方で他方を置き換えるというより、異なる層の設計として考えるのが自然です。

• 小規模で一人が順番に進めるプロジェクトなら、作業中の焦点を一つに絞り、必要な領域の資料を読む方式は始めやすいでしょう。ただし、活動中の一覧が唯一の計画記録を上書きする形にはしないほうが安全です。
• チームで並行作業をする場合や複数リポジトリーにまたがる場合は、安定したタスクIDと個別の計画を持たせるほうが追跡しやすくなります。「活動中の計画が一つ」というルールは、チーム全体に一つしか計画ファイルを認めない意味ではなく、セッションごとの作業焦点として捉えるのが適切です。
• 特定のエージェント環境に依存しない運用では、常設ルールを絞り、どの条件でどの資料を読むかを明示するのが有効です。
• 独自の拡張を行う場合は、状態の集約や証拠の検査など、その仕組みが実際に用意されていることを確かめます。ディレクトリーやプロンプトの存在だけで、そうした機能が実現したとは言えません。

見直したい5つのルール

1. 完了したら上書き、ではなく「表示を圧縮して記録は残す」

完了した計画を普段の読み込み対象から外すことと、計画そのものを消したり上書きしたりすることは別です。履歴を簡潔な一覧にまとめながら、状態や根拠をたどれる記録は残す。これなら、作業の見通しと追跡可能性を両立できます。

2. 共通の橋渡しルールだけで、すべての実行環境に対応できるとは限らない

エージェントがどのファイルを、どの範囲で読み込むかは、ホストとなるツールに左右されます。BMADの資料でも読み込み機構、特に入れ子になったルールの扱いを検証する必要性が示されています。OpenAIの例でも、Codexが認識するAGENTS.mdと、利用者が調整するワークフロー上のファイル構成は区別されています。6

したがって、共通の指示書を用意したうえで、各ホストの読み込み方は個別に確認するのが現実的です。

3. 行数の上限を、幻覚を防ぐ万能策にしない

常設ルールを短く保つことは役立ちますが、特定の行数を超えたら一律に機能しなくなる、という基準はここで確認できる資料からは導けません。実際の読み込み量、重複、他の指示との意味上の依存関係を見て調整し、重要な契約が分割によって切り離されないようにします。

4. テスト用ディレクトリーのJSONを、すべて同じ扱いにしない

固定され、機密情報を含まず、再現可能なテスト用フィクスチャと、一度の実行で生成されるログや出力は性質が異なります。ユニット、統合、エンドツーエンド、実環境での検証についても、実行環境や副作用を分けて定義すべきです。

5. 無視対象の領域を、そのまま履歴保管庫にしない

Gitの除外設定、通常の検索対象から外すこと、アクセスを禁止することは別の制御です。さらに、履歴を残したい一方でGitには登録しない、という運用には整合性の問題が生じます。何を保管し、何を検索対象にし、誰がアクセスできるかを分けて設計しましょう。

公開事例から学べること、一般化しすぎないこと

Geoffrey HuntleyのRalphに関する記事は、単一プロセスのループで一度に一つの作業に取り組む方法を説明しています。14 また、同氏のガイドでは、関心領域ごとに仕様をまとめたり、ビルドやテストの実務上の知見をプロジェクトの案内に置いたりする例が示されています。11

ここから得られるのは、小さな作業単位、明確な仕様、限られたコンテキスト、実際のフィードバックを組み合わせるという考え方です。すべてのプロジェクトに同じディレクトリー構成を強制する根拠ではありません。

一方、OpenAIの複雑なタスク向けの例は、長い作業では詳しい実行計画を使う方法を示しています。5 常設の案内を簡潔にすることと、個別タスクに十分な計画を持たせることは両立します。

実務では、次のように整理できます。

• 常設ルールは簡潔にし、タスク計画の詳しさはリスクや所要時間に応じて変える。
• 領域別の仕様を用意しつつ、領域をまたぐ重要な不変条件への参照も残す。
• ループやセッションを再開するときは、会話履歴全体ではなく、現在のタスクに必要な文脈を組み直す。
• ビルドやテストの案内には、確認できたコマンドと前提条件を書く。

なお、Ralphの派生実装やコミュニティーの説明を、Huntley本人の原文の主張として扱うべきではありません。特定の実装に関するテスト隔離の詳細など、根拠を確認できない点は一般論として断定しないことが大切です。

エージェント向け文書を整える10の原則

1. 書き手ではなく、情報の役割で分類する。 人が書いたから正しい、機械が生成したから一時的、と決めつけず、方針、確認済みの事実、提案、作業状態、検証記録、探索中の草稿を区別します。
2. 重要な事実には、編集できる正本を一つ設ける。 要約や索引で情報を再掲する場合は、出典、版、古くなる条件を分かるようにします。
3. ソースコードからは分からない知識を優先して記録する。 意図、採用しなかった理由、外部制約、コンポーネント間の責任分担は、コードの構造を読むだけでは確定できないことがあります。
4. 入口の文書には、制約と案内を書く。 「必要なら読む」のような曖昧な指示に頼らず、対象のパスやインターフェース、タスクの種類など、観察できる条件で参照先を示します。
5. 仕様・状態・証拠の役割を分ける。 仕様は「何を満たすべきか」、状態は「どこまで進んだか」、証拠は「なぜ満たしたと言えるのか」を示します。同じファイルに置く場合も、正本がどれかを明確にします。
6. 要約しても、再開に必要な情報は落とさない。 未完了事項、阻害要因、依存関係、権限の境界、証拠の場所を残します。過去の成功が、新しい実行の成功を保証するわけではありません。
7. 履歴を追える状態と、現在有効なルールの見つけやすさを両立する。 置き換えられた判断も根拠と関係を残し、領域別の仕様には現在有効な決定を参照させます。
8. テスト用の資産と実行時の出力を分ける。 既存の言語・フレームワークの慣習を尊重し、ログなどの出力は機密性、容量、保存期間に応じて扱います。
9. 機械で守れるルールは、実際の検査機構に任せる。 ただし、誰も読まない文書へルールを移しただけでは負担軽減になりません。チェックが未実装なら、文章上の制約を置き換えたことにもなりません。
10. ディレクトリー上の約束を、実行権限と混同しない。 文書生成、コマンド実行、外部への通信、デプロイ、保管はそれぞれ別に許可します。草稿用のフォルダーが実行時のサンドボックスになるわけではありません。

まず文書の役割を決め、移行はその後に

おすすめの順序は、最初に成果物の役割と正本を定め、次に利用するホストの読み込み仕様を確かめることです。その後、現在の作業を見渡す簡潔なビューを用意し、実際の作業で得たフィードバックをもとに情報量や保存方針を調整します。いきなりプロジェクト全体のディレクトリーを移し替える必要はありません。

また、静的な構造の調査、業務上の事実、ホストによる指示書の読み込みは、それぞれ別の問題です。自動生成した文書が存在することだけで、それが承認済みの規範になったと見なさず、確認と採用の手順を設けることが重要です。

ここでの提案は文書管理の設計指針であり、特定のプロジェクトへの実装や変更を承認するものではありません。