想定する読者

すでにClaude Code、Codex CLI、CursorなどのAI coding agentでコードを書いている人を想定しています。Agentは、あるときは非常に良い仕事をし、別のときには理由も分からないまま勝手なことをします。同じモデルがプロジェクトAでは信頼できるのに、プロジェクトBでは的外れな行動をします。問題はモデルではなく、与えている「環境」にあるのではないかと疑っているでしょう。

その疑いは正しいものです。

2026年2月、OpenAIはHarness Engineering: Leveraging Codex in an Agent-First Worldという記事を公開し、Codex agentを使ってゼロから100万行規模の製品を構築した経験を説明しました。中核的な発見は、ボトルネックはモデルのコーディング能力ではなく、構造、ツール、フィードバック機構の不足にある ということです。LangChainがTerminal Bench 2.0で行った実験も、同じ結論を裏付けています。同じモデルを使い、harness、つまり環境と制約だけを変えると、スコアは52.8%から66.5%へ上がり、ランキング中位から一気にTop 5へ入りました。

この記事では、その中でも最も重要な要素である、プロジェクト文書——Agentの「目」と「地図」 に焦点を当てます。

第一原則：Agentから見えないものは存在しない

具体的な実践を議論する前に、根本的な認識を一つ確立します。

OpenAIはHarness Engineeringの記事で、Agentの視点では、contextからアクセスできない知識はすべて存在しない と明確に述べています。Slackの会話、Google Docs、人の頭の中にある知識は、Agentにとって透明です。Agentが届く場所へ意識的に形として残さない限り、利用できません。

最も信頼できる方法は、知識を コードリポジトリ内へ具体化すること です。バージョン管理でき、レビューでき、テストできる形にします。リポジトリが唯一の事実源、single source of truthになります。

つまり、Agentに守らせたいルールをConfluenceへ書いても効果はなく、リポジトリ内の文書へ書く必要があります。

入口ファイル：Agentへ百科事典ではなく地図を渡す

教訓：一つの巨大ファイルが失敗した理由

OpenAIが最初に試したのは、「一つの巨大なAGENTS.md」へすべての指示を詰め込む方法でした。予想どおり、三つの理由で失敗しました。

  1. Contextは希少な資源です。 巨大な指示ファイルが、タスク記述、コード、関連文書のための空間を奪い、Agentは重要な制約を見落としたり、誤った方向を最適化したりします。
  2. すべてが「重要」なら、何も重要ではありません。 Agentは全体的なpattern matchingから、局所的なpattern matchingへ退化します。
  3. 単一の巨大な手引きは、すぐに劣化します。 古いルールと現在のルールが混ざり、Agentには区別できません。

HumanLayerのチームは、もう一つ重要な点を発見しました。Claude CodeがCLAUDE.mdを注入するとき、「これらのcontextはタスクに関係する場合も、関係しない場合もある。関連性が非常に高い場合を除き、応答しないこと」というsystem promptを追加します。つまり、CLAUDE.mdに現在のタスクと無関係な内容が多いほど、Agentが指示全体を無視する可能性が高くなります。

ベストプラクティス：短い入口 + 段階的な開示

OpenAIが最終的に採用したのは、約100行のAGENTS.mdを入口として使う方法でした。本質的には、より深い文書を指し示す 地図 です。

Anthropicの公式文書もまったく同じ方法を推奨しています。/initを実行して最初のCLAUDE.mdを生成し、その後継続して簡潔にします。内容には、shell command、コードスタイル、workflow rule、つまりAgentがコード自体から推測できない持続的なcontextを含めます。

業界の共通見解は、CLAUDE.md / AGENTS.mdを 300行以内 に抑え、できるだけ短くすることです。HumanLayer自身のルートCLAUDE.mdは60行未満です。

入口ファイルには、次の情報を含めます。

  • プロジェクトの一文説明 + 技術スタック。 「Reactプロジェクト」ではなく、「React 18 + TypeScript + Vite + Tailwind CSS」のように具体的なversionまで書きます。
  • コピーしてそのまま実行できるbuild/test/lint command。 npm run test、npm run buildなどです。
  • プロジェクト構造の概要。 「src/にアプリケーションコード、tests/にテスト、docs/に文書を置く」といった説明です。
  • 絶対的な境界。 secret、vendorディレクトリ、本番設定など、Agentが絶対に触れてはいけないものです。
  • 深い文書へのナビゲーションリンク。 「アーキテクチャの詳細はdocs/architecture.mdを参照」のように示します。

良い入口ファイルは、会社の全規定集ではなく、新入社員が初日に受け取るonboarding checklistのように読めるべきです。

文書の階層：OpenAIの知識ベース構造

OpenAIはHarness Engineeringの実践で、リポジトリ内文書を次のような階層ディレクトリへ整理しました。

AGENTS.md                 ← 目次（約100行）
ARCHITECTURE.md            ← 最上位のdomain map
docs/
├── design-docs/           ← index化され検証されたアーキテクチャ判断
├── exec-plans/
│   ├── active/            ← 進行中の実行計画
│   ├── completed/         ← 完了済みの実行計画
│   └── tech-debt-tracker.md
├── generated/
│   └── db-schema.md       ← 自動生成された参照文書
├── product-specs/         ← 製品仕様
├── references/            ← 外部参考資料
└── ...

この構造には、いくつかの重要な設計原則が表れています。

1. 段階的な開示（Progressive Disclosure）。 Agentは小さく安定した入口から始め、一度に情報の洪水を浴びるのではなく、「次にどこを見ればよいか」を教えられます。OpenAIの表現では、active plans、completed plans、既知の技術的負債がすべてversion管理され、リポジトリ内に共存するため、Agentは外部contextへ依存せずに作業できます。

2. 実行計画も文書です。 従来のソフトウェア開発は、計画状態をJira、Confluence、Slackへ置きます。Agent-first開発では、Agentがcontext外の情報へアクセスできないため、これは根本的なアーキテクチャ上の欠陥です。OpenAIチームは実行計画をversion管理されたリポジトリartifactとして扱います。後続タスクを担当するAgentは、以前のタスクで行われた判断、その理由、現在の状態を推論できます。

3. 文書の保守も自動化します。 専用linterとCI jobが、知識ベースが最新か、相互参照が正しいか、構造が規則どおりかを検証します。定期実行する「文書整理Agent」が古い文書を走査し、修正PRを作成します。Agentが読む文書をAgentで保守する仕組みです。

OpenAIの主要リポジトリには現在、主要サブシステムごとに一つ、合計 88個のAGENTS.mdファイル があります。これは偶然ではなく、指示の局所性と最小性を保つための意図的な設計です。

Anthropicの方法：セッションをまたぐAgent向けに文書を設計する

Anthropicは別の角度から同じ問題に取り組みました。Effective Harnesses for Long-Running Agentsでは、中心的な課題を次のように説明しています。Agentは分離したセッションで作業し、新しいセッションは以前に起きたことを何も覚えていません。交代勤務のエンジニアのように、各担当者が前の勤務をまったく知らずに仕事を始めます。

解決策は、二つのAgentから成るアーキテクチャです。

Initializer Agent（初回実行） が環境の基盤を作ります。

  • feature_list.json——200以上の細かなfeatureをすべて「failing」として記録。MarkdownではなくJSONを使うのは、AgentがJSON形式の構造化データを不適切に変更しにくいためです。
  • init.sh——一つのcommandで起動するscript。
  • claude-progress.txt——進捗log。
  • 最初のGit commit。

Coding Agent（2回目以降の各実行） は、決まった手順で開始します。

  1. Git logとprogress fileを読み、現在の状態を理解する。
  2. dev serverとエンドツーエンドテストを実行する。
  3. 実装するfeatureを一つ選ぶ。
  4. 内容を説明するcommit messageでcommitする。
  5. progress fileを更新する。

重要な洞察は、外部artifactがAgentの記憶になること です。Progress file、Git history、構造化されたfeature listはセッションをまたいで残ります。各Agentセッションは作業開始前に、これらのartifactからcontextを再構築します。

文書設計にとって重要な示唆があります。文書は「ルールブック」だけではなく、状態追跡ファイル も含むべきです。Agentへ「どう作業すべきか」だけでなく、「現在どこまで進んだか」を伝えます。

文書の種類ごとの責務と書き方

OpenAI、Anthropic、コミュニティの実践をまとめると、プロジェクト文書は次の種類に分けられます。それぞれに異なる責務と書き方の原則があります。

1. 入口ファイル（AGENTS.md / CLAUDE.md）

責務： 地図とナビゲーション。プロジェクトの内容、重要なcommand、詳細情報の場所をAgentへ伝えます。

書き方の原則：

  • 100〜300行に抑える。
  • commandを優先する。コピーして実行できるshell commandは、説明文よりはるかに有用です。
  • スタイルを文章で説明するのではなく、実際のコード例で示す。実在するコード片一つは、三段落の説明より価値があります。
  • 絶対的な境界を明記する。「secretを絶対にcommitしない」は、最も有効な単一制約であることが実証されています。

2. アーキテクチャ文書（ARCHITECTURE.md / docs/architecture.md）

責務： システムの階層規則、依存方向、モジュール境界を定義します。

書き方の原則：

  • Types → Config → Repo → Service → Runtime → UIのように、階層と依存方向を明確に定義します。
  • 同じ制約をlinterで機械的に実行します。文書はAgentが読む「soft constraint」、linterは「hard constraint」です。
  • linterがerrorを出すとき、error message自体に修正方法を含めます。error messageがAgentにとっての「学習の機会」になります。

OpenAIは、Codex自身が生成したcustom linterと構造テストで、これらの規則を実行します。人を中心とするworkflowでは過度に厳格に見えるかもしれませんが、Agentを中心とする環境では効率の増幅器になります。一度コード化すれば、すべての場所で同時に機能するからです。

3. コーディング規約（docs/conventions.md）

責務： 命名規則、コードスタイル、Git workflow。

書き方の原則：

  • 「説明」ではなく「提示」を使い、実際のコード片を例として示します。
  • Git workflowを具体化します。branch名の形式、commit messageの形式、PR要件を書きます。
  • Agentにhelperを書かせるのではなく、優先して使う共有toolkitを指定し、不変条件を一元管理します。

4. 状態追跡ファイル（進捗log、feature list）

責務： 新しいセッションのAgentが「現在どこまで進んだか」をすぐに理解できるようにします。

書き方の原則：

  • MarkdownではなくJSON形式を使います。Anthropicは、AgentがJSONの構造化データを不適切に変更しにくいことを発見しました。
  • 各セッションの終了時にAgentが更新します。
  • Git commit historyと組み合わせます。内容を説明するcommit message自体が、最良の進捗文書です。

5. 設計判断記録（ADR / Design Docs）

責務： 「なぜ」を記録します。Pineconeではなくpgvectorを選んだ理由や、認証flowをその形にした理由です。

書き方の原則：

  • 番号付きindexを使い、Agentが必要に応じて参照できるようにします。
  • 判断のcontext、検討した代替案、最終的な理由を含めます。
  • version管理し、後続のAgentが以前の判断chainを推論できるようにします。

6. サブモジュール文書（各サブディレクトリのAGENTS.md）

責務： 局所的なcontext。Agentがbackend/ディレクトリで作業するときは、バックエンド関連の制約だけを見せます。

書き方の原則：

  • Agentはディレクトリtree内で最も近いファイルを自動的に読み、近いものを優先します。
  • サブモジュール文書は、ルート文書の規則を上書きできます。
  • 局所性を守り、そのサブモジュールに固有の情報だけを置きます。

反pattern：文書がAgentを悪化させる場合

複数チームの失敗経験をまとめると、次の方法はAgentの性能を大幅に下げます。

1. 情報過多。 研究では「指示の呪い」が確認されています。指示が増えるほど、モデルが各指示に従う能力は低下します。複数チームが独立して、context利用率が約40%を超えると性能が低下し始めることを発見しました。過剰なツール、長い文書、蓄積した履歴は、Agentを良くするのではなく悪化させます。

2. ルール同士の矛盾。 ある文書は「Tailwindを使う」と書き、別の文書は「CSS Modulesを使う」と書いています。矛盾した情報に出会うと、Agentの振る舞いは予測不能になります。

3. 古い情報を削除しない。 文書を作るのは簡単ですが、保守が本当の課題です。完全に見えるCLAUDE.mdでも、生成から数週間で誤った内容を伝え始める可能性があります。プロジェクト構造が変わり、技術スタックが更新され、規約が変わっても、文書が追随しないからです。Anthropicの社内チームは、CLAUDE.mdが正確であるほどClaude Codeの性能が良くなることを確認しています。

4. 例の代わりに説明を書く。 「関数componentを使ってください」と書くより、要件に従ったcomponentコードを直接示すほうが有効です。Agentはpattern matchingから学び、実際のコードが最も強いpattern信号になります。

5. 技術文書をリポジトリ外へ置く。 外部API、ライブラリ、frameworkの文書は、コードの隣へ保存すべきです。Agentが外部resourceを検索すると、versionの違いで失敗することがよくあります。重要な参考文書をリポジトリへ組み込みます。

文書の保守：最も難しい部分

ほぼすべての実践者が同じ点を強調しています。誘導contextを最初に作ることは課題ではなく、保守こそが課題です。

/initを実行すれば、数秒でCLAUDE.mdを生成できます。これによって完全だという錯覚が生まれます。ファイルが存在し、情報があり、専門的に見えます。しかし数週間で劣化し始める可能性があります。

推奨する保守戦略：

1. 文書をコードとして扱う。 文書をCI検証に含めます。OpenAIはlinterとCI jobで、文書が最新か、相互参照が正しいかを検証します。

2. Agentが読む文書をAgentで保守する。 OpenAIは定期的な「文書整理Agent」を実行し、実際のコード動作を反映しなくなった古い文書を走査して、修正PRを作成します。自動化で文書のentropy増大へ対抗します。

3. specを「生きた文書」として扱う。 Agentと判断したときや新しい情報を発見したときに更新します。データモデルが変わったりfeatureが削除されたりした場合は、文書へ反映します。

4. PR reviewで文書の整合性を確認する。 コードを変更する各PRで、「この変更に伴って関連文書を更新する必要があるか」と問います。できればCIで自動確認します。

実行可能な開始案

今から始める場合、OpenAIのような88ファイルの体系を一度に作る必要はありません。最小限の実行可能な形から始めます。

第1週： ルートCLAUDE.md / AGENTS.mdを作るか、簡潔にします。プロジェクト説明、技術スタック、重要なcommand、絶対的な境界が含まれることを確認し、100行以内に抑えます。

第2週： アーキテクチャ規則をdocs/architecture.mdへ分け、入口ファイルからlinkします。明確な階層規則がある場合は、最小限のlinterを用意して実行します。

第3週： プロジェクトが複数のモジュールにまたがる場合、主要サブディレクトリへ局所的なAGENTS.mdを置きます。そのモジュール固有のcontextだけを含めます。

継続： Agentが繰り返してほしくない誤りを犯すたびに、「どの文書または制約が不足していたか」と自分に問い、その修正をリポジトリへコード化します。これがharness engineeringの中核的なloopです。

Terraformの創業者Mitchell Hashimotoは、最も正確に次のようにまとめています。「Agentが誤りを犯したことに気づくたび、その誤りを二度と犯さないようにする仕組みを設計するために時間を使う。それがHarness Engineeringである。」

まとめ

原則出典要点
Agentから見えないものは存在しないOpenAI Harness Engineeringリポジトリが唯一の事実源
百科事典ではなく地図OpenAI, Anthropic, HumanLayer入口ファイルを300行以内にし、深い文書へつなぐ
段階的な開示OpenAI, AGENTS.md標準一度にcontextを埋めず、必要に応じて読む
説明ではなく提示Addy Osmani, コミュニティの共通見解コード例 > 説明文
機械的な実行OpenAI Harness Engineering文書はsoft constraint、linterはhard constraint
状態も文書Anthropic Long-Running AgentsJSON進捗ファイル + Git history
Agent向け文書をAgentで保守OpenAI「文書整理」Agent自動化で文書のentropy増大へ対抗
作成より保守が重要Packmind, コミュニティの共通見解古い文書は文書がないことより危険

最後に一文： より良いモデルは、harness engineeringの重要性を下げるのではなく高めます。強いモデルは大きな自律性を可能にし、大きな自律性には優れたguardrailが必要です。Agentのために作る文書体系は、そのguardrailの最も基礎的な層です。

参考資料：

  • OpenAI, “Harness Engineering: Leveraging Codex in an Agent-First World”, 2026.02
  • Anthropic, “Effective Harnesses for Long-Running Agents”, 2025.11
  • Anthropic, “Best Practices for Claude Code”, 2026
  • AGENTS.md標準 (agents.md), Linux Foundation
  • Addy Osmani, “How to Write a Good Spec for AI Agents”, 2026.02
  • Martin Fowler / Birgitta Böckeler, “Harness Engineering”, 2026.02
  • HumanLayer, “Writing a Good CLAUDE.md”, 2025.11
  • Marmelab, “Agent Experience: Best Practices for Coding Agent Productivity”, 2026.01