agent-native-project-design

エージェントネイティブ・プロジェクト設計憲章

Claude Code / Codex のような既製ハーネスをランタイムとして採用する場合、エンジニアリングの対象はリポジトリ/プロジェクトそのものになる。指示ファイル・スキル・スクリプト・ディレクトリ構造・検証手段が、そのプロジェクトにおけるハーネスである。

エージェントは確率的に指示を読み落とし、確率的に手順を間違える。このスキルは、確率的な実行者を前提に、構造で信頼性を作るための憲章である。

---

0. コア公理

この公理は agent-harness-engineering / agent-native-project-design の2スキルへ意図的に同一内容で複製している（改訂時は両ファイルを同時に更新すること）。mastra-ai-architecture-rules の「設計の根本原則」とも整合するよう維持する。

1. 判断にはモデルを使う。保証にはハーネスを使う。決定的な実行にはコードを使う。 サービスに LLM を組み込むとき（その検証を含む）、開発者やコーディングエージェントは、LLM に任せるべき判断まで自分が書くコードで決めてしまう傾向がある。判定のためのコードを足す前に、その判定を LLM に任せられないかを先に検討する。
2. エージェント = モデル + ハーネス。同じモデルでもハーネスで成果は大きく変わる。 ハーネスは改善対象の第一級変数である。
3. コアループは 「コンテキスト収集 → 行動 → 検証」。検証の設計が品質の上限を決める。
4. 可能な限り単純な構成から始め、必要が実証されたときだけ複雑さを足す。 最も成功している実装は複雑なフレームワークではなく、シンプルで composable なパターンを使っている。
5. コンテキストは有限資源である。ただし情報を失わせて節約しない。 望む結果の尤度を最大化する最小の高シグナルトークン集合は、量を削って作るのではなく、その場に載せる分と取りに行ける分を分けて作る。載せる範囲はユーザーの要求の目的から決め、範囲の中は切らず、範囲の外は所在と取り方をモデルに示して到達可能にする（必要十分に見えるときも取り方は残す）。何を追加で読むかはモデルが判断する。開発者やコーディングエージェントは、目的と無関係な全量を返すことと、文字数・件数の定数で黙って切り詰めることの両極に振れやすい。上限として置いてよいのは受け手が実際に持つ限界だけで、超えるときは切らずにファイル等で全文を渡す。不可逆な圧縮・要約は、まず圧縮せずに渡して品質を担保できることを確認し、コンテキスト量が課題として顕在化してから導入する。payload ではなく reference を、transcript ではなく decision を保持する。
6. 指示は助言（advisory）、コードとゲートは保証（deterministic）。 100%守られるべきものを指示（プロンプト）に置かない。コードに任せるのは、閉じた集合（ID・enum・schema・DB の行・権限・状態遷移）の検査、安全・認可・不可逆な副作用の保証、判定に使う事実の収集である。自然言語の言い回し・意図・応答の妥当性のように列挙で閉じない対象は、正規表現・語句リスト・例外分岐・固定文言で判定せず、LLM に判定させる。
7. 安全は監視より封じ込め。ただし、どこまで任せるかを決めるのはユーザーである。 ここでのユーザーは、エージェントに作業を任せる人を指す（サービスなら利用者、Claude Code / Codex を開発作業や CI で使う場合はその開発者）。開発者やコーディングエージェントは、自分の不安から能力を削り、禁止や承認を固定しがちである。リスクは能力を提供しない理由にせず、ユーザーに示して判断を委ねる。境界（sandbox・権限）は先に定義し、境界越えだけを承認に上げる。fail-closed は、認可情報の欠落・不正（誰の代理か分からない）、管理者の制限を確かめられないこと、安全・不可逆な副作用の保証に限って使う。サービスに LLM を組み込むときは、エージェントにできることを、代理する人間にできることと揃える。上限は代理する人間自身の権限とし、コードが保証する（人間がアクセスできる情報は、ユーザーが許可すれば全てアクセスできる）。上限の内側では、ユーザーが操作ごと（または操作の種類ごと）に「完全に任せる（allow）／承認付きで任せる（ask）／禁止（deny）」を選べる設定をサービスが用意し、ハーネスが決定的に執行する。リスクは未設定時の既定とユーザーへの開示で扱い、ユーザーが未設定の操作を禁止にする根拠に fail-closed を使わない。
8. 停止条件・予算・エスカレーションはハーネスの一級市民である。 後付けにしない。
9. モデルが賢くなるたびにハーネスを剪定する。 「以前は必要だった」は「今も必要」を意味しない。既定モデルを変えるときは、指示文の制約と、検証・コードにある決定的な判定を、入れた理由とともに列挙し、外せるものを外す。
10. 失敗から学んだルールには理由を残す。 ハーネスはインシデント駆動で漸進強化する資産である。ただし失敗1件ごとにルールを足さず、複数の失敗に共通する原則を書く。

---

1. 指示ファイルの設計（CLAUDE.md / AGENTS.md）

指示ファイルは毎セッション、コンテキスト予算から課金される最高レバレッジ点である。肥大化した指示ファイルは、すべての指示を一様に無視させる。

• 上限は一律1000行（ルート・ネスト階層・全プロジェクト共通）。各行に「この行を消すと実際にミスが起きるか？」を問い、No なら削る。エージェントが既に守れている指示は削除するか機械強制に移す。
• 「コードから逆算できない決定」だけを書くこと：推測不能なコマンド、デフォルトと異なるスタイル決定、コードに痕跡のない境界・制約、環境の癖。ファイル単位の網羅的説明・詳細なディレクトリツリーの列挙は実証上効果がない。ただし大規模リポジトリ・モノレポのルートに置く高レベルの構造地図（パッケージごとに1行）は例外として有用であり、公式にも推奨される。
• 手で書くか、検証ループを通して生成すること。LLM に生成させた指示ファイルを無検証のまま放置するのは、書かないより悪い結果を生みうる（有害性の主因は既存ドキュメントとの冗長性）。生成する場合はレビュー・刈り込み・更新の仕組みとセットで運用する。「書けば得」ではなく「厳選しなければ損」の非対称がある。
• 禁止は必ず具体的な代替とペアにすること。警告のみの禁止は効かない。ツールやコマンドは名指しする（言及されたツールは実際に使われる）。
• 3層に分離すること：
  1. 常時ロードの不変条項（CLAUDE.md / AGENTS.md）— 短い憲法。検証ルール・絶対制約のみ
  2. オンデマンドの手順書（skills / docs へのポインタ）— 詳細はコピーせずポインタで参照させる
  3. 人間向けマニュアル（README）— エージェント向けと混ぜない
• オンデマンドでロードされるネスト階層には、条件付きで知識ベース型を推奨する。サブディレクトリの指示ファイルは該当ディレクトリの作業時のみロードされるため、常時ロードとはコスト構造が異なる。（a）常時ロードされない階層に置く（b）検証ループ（レビュー・刈り込み）を通して生成する（c）更新機構でコードベースへの追従を維持する——の3条件を満たす形で、STRUCTURE・CODE MAP・WHERE TO LOOK を含む知識ベース型を置くことを推奨する。条件を欠く運用（無検証生成・放置）は成功率を下げる。
• 単一ソース化すること。AGENTS.md はクロスハーネス標準になっており、CLAUDE.md との二重管理は drift を生む。片方を正本にし、もう片方は symlink または参照にする。
• 重大ルールには防御的冗長性を認めること。絶対に破られてはならない少数のルール（検証ルール等）は、読者別の表現で複数箇所に重複記載してよい。DRY より読み落とし耐性を優先する意図的な判断であり、対象は最重要ルールに限る。

詳細と実例: references/instruction-files.md

---

2. 拡張機構の選択

機構は「何をするか」ではなく**「コンテキストへどう載るか」**で選ぶこと：

コンテキストへの載り方	機構
毎セッション常時ロード	CLAUDE.md / AGENTS.md（最小限に）
特定ディレクトリで作業するときだけ	ネストした CLAUDE.md / paths 指定の rules
モデルが状況判断でオンデマンドに読む	Agent Skills
ユーザーが明示起動する定型手順	slash command
毎回必ず決定的に実行される（保証）	hooks
隔離されたコンテキストで実行し要約だけ戻す	subagents

判定ヒューリスティック：「must always / never」と書きたくなったら hook（保証）、「X のときは Y を優先」なら skill（助言）。ただし must の対象が自然言語の言い回し・意図・応答の妥当性であれば、正規表現で判定する hook にせず、LLM が判定する仕組み（検証専用サブエージェント、LLM に判定させる hook など）に置く。

---

3. Agent Skills の作成

• progressive disclosure の3階層で設計すること：name + description（常時ロード、約100〜150トークン）→ SKILL.md 本文（発火時ロード。行数上限は置かず、必要十分な最小集合を references/skill-authoring.md §1「本文量の判定」の4質問で決める）→ references / scripts（必要時のみ）。コンテキストウィンドウは公共財である。
• 発火は description がすべて：三人称で「何をするか + いつ使うか + トリガー語」を書く。発火しない原因の大半は description の曖昧さである。
• 参照ファイルは SKILL.md から1階層のみ。深いネストは部分読みによる情報欠落を生む。長い参照ファイルには冒頭に目次を付ける。
• 憲章は常時ロード側（CLAUDE.md）に一元化し、skill には参照とフェーズ固有の差分のみ書くこと。同じルールを複数スキルへコピーすると drift する。フェーズによってルール強度を変える場合（叩き台段階は裏取り不要等）はその差分だけを書く。
• 実運用の失敗観察から反復すること。スキルは書いて終わりではなく、発火漏れ・誤発火・指示の読み落としを観察してdescription と本文を直し続ける。

詳細: references/skill-authoring.md（執筆原則の正本）/ references/authoring-insights.md（外部知見の補遺: スキル4類型・ガイダンス形式・トリガー評価・外部スキル監査。create-skill もここを参照する）

文面そのもの（記述高度・既習概念の指名・工程とメンタルモデルの切替・停止条件の書き方）の執筆原則は agent-prompt-design を参照。本スキルは機構と規約（どこに・どう載せるか）を、agent-prompt-design は文面（何をどう書くか）を担う。

---

4. 自然言語指示と決定的スクリプトの分担

分担は degrees of freedom（自由度） で決めること：判断が文脈依存なら高自由度のテキスト指針、壊れやすく順序厳守・正確性必須なら自由度ゼロの固定スクリプト。ただし自然言語の言い回し・意図は列挙で閉じない対象であり、正確性が必要でも固定スクリプトで解釈せず、モデルに解釈させる。

• 決定的操作はスクリプトに焼き込み、間違える自由を構造的に奪うこと。出力先パス・命名規則・変換パラメータをスクリプト内で強制導出すれば、エージェントが「間違った場所に保存する」故障モード自体が消える。
• スクリプトには「いつ・何のために呼ぶか」だけを指示に書くこと。フラグやパラメータの詳細は指示に書かずスクリプトへ封じる。「実行するのか、参照として読むのか」を明示する。
• スクリプトは solve, don't punt：エラー処理をエージェントに丸投げしない。能力検出 → 段階的縮退 → 実行可能な対処案内まで面倒を見る。根拠不明の定数（voodoo constants）を置かない。
• エラーメッセージと stdout はプロンプトの一部として設計すること。スクリプト完了時に「次の工程はこうする」を印字（stdout ナッジ）すれば、重要ルールをツール実行の瞬間にコンテキスト直近へ再注入できる（冒頭指示の減衰対策）。
• 知覚アダプタ：LLM が消費できない入力（長大な動画・音声・巨大ログ・数万行のデータ）は、決定的ツールで消費可能な形（フレーム・要約表・スライス）に変換し、判断だけをモデルに残す。ツール出力自体にドメイン解釈（候補・注目点）を付けてよい。ただしこれは消費不能な入力の変換であり、消費可能なコンテキストの事前圧縮ではない。消費できるものはまず圧縮せず渡して品質を確認する（公理5）。
• グラウンドトゥルースの埋め込み：時刻換算・ID照合などエージェントが誤りやすい算術・参照は、成果物側に焼き込む（タイムコードを画像に焼く等）ことで工程ごと消す。

---

5. ディレクトリ契約

エージェントが操作するリポジトリには、区分ごとに所有者とライフサイクルを定めたディレクトリ契約を置くこと。

区分	所有者	ライフサイクル	例
入力・素材	ユーザー	不可侵（エージェントは読むだけ）	materials/, videos/
中間物	エージェント	使い捨て。いつ消えてもよい	work/
成果物	人間が読む	恒久。本文のみ（作業ログ・前置き禁止）	output/
道具	リポジトリ	バージョン管理	scripts/, tools/

• 契約は .gitignore で機械的にも強制すること（大容量データの除外等）。指示と機械強制の多層防御にする。
• 中間物は冪等・再生成可能に設計すること。決定的なパス命名 + 上書き可能な生成にすれば、明示的なチェックポイント機構なしで「再実行 = 再開」になる。
• 成果物チャネルと報告チャネルを分離すること。成果物ファイルには本文のみ、会話では保存先パスと要確認事項だけを短く報告させる。
• 複数素材・複数セッションを扱う場合は、素材名でネームスペースを切り、マージを見越した ID 設計（連番にブロック ID を付ける等）をすること。

---

6. 検証ループと不確実性の設計

エージェントに、自分の出力が正しいかを自分で確かめる手段を与えること。 検証ループの有無が自律性の上限を決める。

• pass/fail シグナルを与えること：テスト・ビルド exit code・スキーマ検証・fixture 比較・スクリーンショット。検証方法は判定対象で使い分ける。テスト結果・schema・DB の行のような閉じた集合はルールベースで、画面の見た目は視覚比較で、自然言語の言い回し・意図・応答の妥当性のように列挙で閉じない対象は LLM judge で判定する。
• 検証ゲートの強度は4段階から選ぶこと：プロンプトで検証を指示 → 完了条件（goal）として宣言 → Stop hook で決定的にブロック → 検証専用サブエージェント（作業者と採点者の分離）。重要度に応じて強度を上げる。
• 証拠主義：「ツールを実行した」≠「証拠を観察した」。成功の主張ではなく、確認した証拠（時刻・出力・スクリーンショット）を要求する。
• 不確実性を持ったまま完了する経路を用意すること。確定できない箇所を推測で埋めさせず、provenance マーカー（例:〔裏取り済み：根拠〕/〔要確認：理由〕）で構造化して残させる。マーカーはそのまま人間へのハンドオフプロトコルになる。
• 検証予算と停止条件を数値化すること：検証対象の発動条件、1論点あたりの上限、許容誤差、超過時のフォールバック。上限なしの検証指示は過剰検証ループを生む。
• 本作業前に前提のスモークテストを置くこと（入力データの健全性を2〜3点で確認）。入力の既知欠陥と、矛盾時の信頼順位（例: 参考資料 > 映像 > 自動字幕）を明文化する。
• 人間ゲートは高価な工程の直前に置くこと：発散（複数案）→ ハードストップ（選択を待つ）→ 収束（精緻化）。確認質問は依頼者にしか答えられないものに絞り、選択肢付きで冒頭に集約する。
• 黙った歪曲を禁止しエスカレーションさせること：制約に収まらない場合（尺超過等）は黙って品質を犠牲にせず、超過の事実と削減候補を提示させる。
• インシデント駆動で強化すること：実際に起きた失敗から、複数の失敗に共通する原則を見つけてルールに還元し（失敗1件ごとにルールを足さない）、「なぜこのルールがあるか」を変更履歴に残す。ルールは失敗の証拠に基づいて改訂され、モデル更新とともに剪定される。

詳細と実例: references/verification-and-provenance.md

---

7. 外部連携（CLI vs MCP）

• CLI ファーストを既定とすること。CLI はトークンが軽く、--help で自習可能で、コンテキストを占有しない。MCP サーバはツール定義だけで数万トークンを消費しうる。
• MCP が正当化されるのはガバナンス要件（per-user OAuth・監査証跡・組織的な権限管理）が出たとき。
• 多数のツール・大きな中間結果が必要なら、コード実行でツール群を組み合わせるパターンを検討すること。

---

8. headless / CI / 並列運用

• headless 実行は許可範囲の明示 + 構造化出力 + 予算ガードの3点セット：承認付き（ask）を対話で受けられないため、許可するツールを allowlist で明示する。範囲はユーザーが決め、最小にすることを既定の要求にしない（公理7）。JSON schema による構造化出力、per-run のターン上限・コスト上限。予算ガードなしの自動実行を組まない。
• 並列エージェントは worktree 等で物理隔離すること。同一作業ツリーでの並列書き込みは成果物を壊す。fan-out は2〜3件で試してから全量に広げる。
• Writer / Reviewer は fresh context で分離すること。自分の書いたものを自分でレビューさせない。ただし「gap を探せ」と言われたレビューアーは健全な作業にも必ず何か指摘するため、指摘の全対応は over-engineering を生む。指摘にスコープ制約を掛け、採否判断を挟む。
• エージェントの出力は tainted として扱うこと：CI を強化し、人間レビューを必須にする。検証の根幹となるテストは人間が書く（または人間が審査する）。エージェントによるテストの削除・改変は不可と明示する。
• 同じ問題を2回修正したらセッションを捨てること。汚れたコンテキストで粘るより、学びを織り込んだ新しいプロンプトで新セッションを始めるほうが速い。

詳細: references/operations.md

---

9. アンチパターン → 是正

アンチパターン	なぜ失敗するか	是正
肥大した CLAUDE.md / AGENTS.md	全指示が一様に無視される	一律1000行以下に厳選 + 3層分離
常時ロード部への網羅的なツリー・ファイル列挙	実証上効果がなくコストだけ増える	ルートは高レベル地図（1行/パッケージ）まで、詳細はオンデマンド階層の知識ベースへ
LLM 生成の指示ファイルを無検証で放置	成功率を下げコストを増やす	検証ループ付きで生成し、更新機構で追従させる
警告のみの禁止事項	禁止だけでは行動が変わらない	具体的代替とペアにする
linter/CI でできる強制を指示文で行う	助言は確率的にしか守られない	hooks・CI・スクリプトで機械強制
「must always」を skill に書く	オンデマンド機構に保証を置いている	hook（決定的）へ移す。対象が自然言語の言い回し・意図・応答の妥当性なら、正規表現で判定する hook ではなく LLM が判定する仕組みに置く
参照ファイルの深いネスト	部分読みで情報が欠落する	SKILL.md から1階層まで
MCP サーバを山盛りにする	ツール定義だけで数万トークン消費	CLI ファースト、MCP はガバナンス要件時
成功例だけの few-shot	「必ず解決してしまう」バイアスを植える	失敗・未解決で終わる例を含める
会話に長文データを溜める	コンテキスト劣化は静かに起きる	外部メモリへ書き出し + 数値の発動条件
推測で空欄を埋めて完了	もっともらしい誤りが混入する	要確認マーカーで不確実性を残して完了
検証指示に上限がない	過剰検証ループで先に進まない	検証予算・許容誤差・フォールバックを数値化
エージェント出力の無審査マージ	tainted な変更が本流を汚す	CI 強化 + 人間レビュー + テスト改変禁止
同じ修正を何度も繰り返す	汚れたコンテキストが原因	セッションを捨て、学びを新プロンプトへ

---

10. 新規プロジェクト設計チェックリスト

エージェントに運用させるプロジェクトを新設・改修するとき、以下を確認すること：

• CLAUDE.md / AGENTS.md は一律1000行以下で、「コードから逆算できない決定」だけが書かれているか
• 絶対に破られてはならないルールは、指示ではなく hooks / CI / スクリプトで強制されているか
• 詳細手順は skills / docs に分離され、常時ロード部分はポインタになっているか
• 決定的操作（パス・命名・変換）はスクリプトに焼き込まれているか
• ディレクトリ契約（入力/中間物/成果物/道具の所有者とライフサイクル）が定義され、.gitignore で強制されているか
• 中間物は再生成可能で、「再実行 = 再開」になっているか
• エージェントが自分の出力を検証する pass/fail シグナルがあるか
• 不確実な箇所を推測で埋めずに完了できる経路（要確認マーカー等）があるか
• 人間ゲートは高価な工程の直前に置かれ、確認質問は絞られているか
• headless / CI 実行には許可範囲の明示（範囲はユーザーが決める）・構造化出力・予算ガードがあるか
• 失敗が起きたとき、それをルール・スクリプト・hook のどれに還元するかの運用があるか