# Agent Native Project Design > Claude Code / Codex 等の既製AIエージェント・ハーネス上で運用するリポジトリ/プロジェクト側（CLAUDE.md / AGENTS.md・Agent Skills・hooks・subagents）を設計・整理・刈り込みするスキル。『CLAUDE.mdを設計/整理して』『この作業をエージェントに任せたい』『スキルを作りたい』『エージェントが指示を守らない』という相談で使用する。ハーネス/ランタイム自体の開発は agent-harness-engineering を参照。 - Skill: `efoo-team/agent-native-project-design` (Agent Skill, multi-file: 6 files) - Install (CLI): `npx skillmds@latest add efoo-team/agent-native-project-design` - Raw SKILL.md: https://api.skillmd.com/api/skills/efoo-team/agent-native-project-design/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: efoo-team (https://skillmd.com/u/efoo-team) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/efoo-team/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](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（助言）**。 --- ## 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/skill-authoring.md)（執筆原則の正本）/ [references/authoring-insights.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 比較・スクリーンショット。検証手段の優先順位はルールベース > 視覚 > LLM-as-judge。 - **検証ゲートの強度は4段階**から選ぶこと：プロンプトで検証を指示 → 完了条件（goal）として宣言 → Stop hook で決定的にブロック → 検証専用サブエージェント（作業者と採点者の分離）。重要度に応じて強度を上げる。 - **証拠主義**：「ツールを実行した」≠「証拠を観察した」。成功の主張ではなく、確認した証拠（時刻・出力・スクリーンショット）を要求する。 - **不確実性を持ったまま完了する経路を用意すること**。確定できない箇所を推測で埋めさせず、provenance マーカー（例:〔裏取り済み：根拠〕/〔要確認：理由〕）で構造化して残させる。マーカーはそのまま人間へのハンドオフプロトコルになる。 - **検証予算と停止条件を数値化すること**：検証対象の発動条件、1論点あたりの上限、許容誤差、超過時のフォールバック。上限なしの検証指示は過剰検証ループを生む。 - **本作業前に前提のスモークテストを置くこと**（入力データの健全性を2〜3点で確認）。入力の既知欠陥と、矛盾時の信頼順位（例: 参考資料 > 映像 > 自動字幕）を明文化する。 - **人間ゲートは高価な工程の直前に置くこと**：発散（複数案）→ ハードストップ（選択を待つ）→ 収束（精緻化）。確認質問は依頼者にしか答えられないものに絞り、選択肢付きで冒頭に集約する。 - **黙った歪曲を禁止しエスカレーションさせること**：制約に収まらない場合（尺超過等）は黙って品質を犠牲にせず、超過の事実と削減候補を提示させる。 - **インシデント駆動で強化すること**：実際に起きた失敗をルールに還元し、「なぜこのルールがあるか」を変更履歴に残す。ルールは失敗の証拠とともに増え、モデル更新とともに剪定される。 詳細と実例: [references/verification-and-provenance.md](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](references/operations.md) --- ## 9. アンチパターン → 是正 | アンチパターン | なぜ失敗するか | 是正 | |---|---|---| | 肥大した CLAUDE.md / AGENTS.md | 全指示が一様に無視される | 一律1000行以下に厳選 + 3層分離 | | 常時ロード部への網羅的なツリー・ファイル列挙 | 実証上効果がなくコストだけ増える | ルートは高レベル地図（1行/パッケージ）まで、詳細はオンデマンド階層の知識ベースへ | | LLM 生成の指示ファイルを無検証で放置 | 成功率を下げコストを増やす | 検証ループ付きで生成し、更新機構で追従させる | | 警告のみの禁止事項 | 禁止だけでは行動が変わらない | 具体的代替とペアにする | | linter/CI でできる強制を指示文で行う | 助言は確率的にしか守られない | hooks・CI・スクリプトで機械強制 | | 「must always」を skill に書く | オンデマンド機構に保証を置いている | hook（決定的）へ移す | | 参照ファイルの深いネスト | 部分読みで情報が欠落する | 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 のどれに還元するかの運用があるか