Agent Native Project Design

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

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

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

0. コア公理

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

1. 判断にはモデルを使う。保証にはハーネスを使う。決定的な実行にはコードを使う。
2. エージェント = モデル + ハーネス。同じモデルでもハーネスで成果は大きく変わる。 ハーネスは改善対象の第一級変数である。
3. コアループは 「コンテキスト収集 → 行動 → 検証」。検証の設計が品質の上限を決める。
4. 可能な限り単純な構成から始め、必要が実証されたときだけ複雑さを足す。 最も成功している実装は複雑なフレームワークではなく、シンプルで composable なパターンを使っている。
5. コンテキストは有限資源である。ただし削減は品質確認の後に行う。 望む結果の尤度を最大化する最小の高シグナルトークン集合を目指すが、まず圧縮せずに渡して品質を担保できることを確認し、コンテキスト量が課題として顕在化してから対処する。payload ではなく reference を、transcript ではなく decision を保持する。
6. 指示は助言（advisory）、コードとゲートは保証（deterministic）。 100%守られるべきものを指示（プロンプト）に置かない。
7. 安全は監視より封じ込め。 境界（sandbox・権限）を先に定義し、境界越えだけを承認に上げる。既定は fail-closed。
8. 停止条件・予算・エスカレーションはハーネスの一級市民である。 後付けにしない。
9. モデルが賢くなるたびにハーネスを剪定する。 「以前は必要だった」は「今も必要」を意味しない。
10. 失敗から学んだルールには理由を残す。 ハーネスはインシデント駆動で漸進強化する資産である。

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. 拡張機構の選択

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

判定ヒューリスティック：「must always / never」と書きたくなったら hook（保証）、「X のときは Y を優先」なら skill（助言）。

3. Agent Skills の作成

• progressive disclosure の3階層で設計すること：name + description（常時ロード、約100〜150トークン）→ SKILL.md 本文（発火時ロード、500行以下）→ 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. ディレクトリ契約

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

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

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

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

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

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

7. 外部連携（CLI vs MCP）

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

8. headless / CI / 並列運用

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

詳細: references/operations.md

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

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

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

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