Harness Engineering 2026年4月12日 (更新: 2026年8月12日)

CLAUDE.md / AGENTS.md 設計パターン集

AIエージェントの記憶ファイル（CLAUDE.md / AGENTS.md）を効果的に設計するためのパターンとアンチパターンを解説する

#harness-engineering #claude-code #agents-md #context-engineering

難易度開発の実務経験がある方向けです種別リファレンス

CLAUDE.md / AGENTS.md とは何か

LLMは推論中にモデルの重みを更新しません。CLAUDE.mdやAGENTS.mdは、この制約を補う永続メモリそのものではなく、エージェントへプロジェクトの指示と参照先を渡すリポジトリ内の設定入口です。

読み込み順、探索範囲、上書き規則は製品ごとに異なります。OpenAI CodexはAGENTS.mdの階層的な探索を、Claude CodeはCLAUDE.mdとrulesの仕組みを持つため、利用中ツールの公式仕様を確認します。

WHY / WHAT / HOW フレームワーク

記憶ファイルの設計は3つの軸で考える。

軸	記述すべき内容	例
WHY	プロジェクトの目的・機能的な意図	「個人ポートフォリオサイト。技術発信とナレッジ蓄積が目的」
WHAT	技術スタック・ディレクトリ構成	「Astro + React + Cloudflare Pages」
HOW	開発ワークフロー・テスト・ビルド手順	`npm run dev` / `npm run test`

この3軸が揃うことで、エージェントはコードを読む前にプロジェクト全体像を把握できる。

設計パターン

パターン1: 段階的開示（Progressive Disclosure）

ルートの指示ファイルは短い入口に保ち、詳細は役割別の正本へ分離します。共通の最適行数はありません。重複、矛盾、常時不要な情報が増えたら分割します。

.claude/
  rules/
    coding-standards.md    # コーディング規約
    architecture.md        # アーキテクチャルール
    testing-strategy.md    # テスト戦略
CLAUDE.md                  # エントリポイント（簡潔に）

CLAUDE.md には各ファイルの存在と目的だけ書く。

## 最初に必ず読むファイル
- 仕様・技術スタック: docs/SPEC.md
- アーキテクチャ決定: docs/ARCH.md

## 開発ルール
1. 実装前に必ずプランモードで設計を確認すること
2. テストを先に書く（TDD）
3. 1ファイル1責務を守ること

エージェントは必要に応じて外部ファイルを Read で読み込む。すべてのコンテキストを常にロードする必要がなくなり、トークン効率が大幅に向上する。

パターン2: ファイルポインタ参照

コードスニペットを直接記載するのではなく、file:line 形式でポインタを書く。

## 型定義の場所
- 共通型: src/types/index.ts
- API レスポンス型: src/types/api.ts:15-45

直接コードを貼ると、リファクタリングのたびに CLAUDE.md が古くなる。ポインタなら常に最新のコードを参照できる。

パターン3: 否定形ルール（Don’t ルール）

エージェントが繰り返す失敗は、明示的な禁止事項として記録する。

## 禁止事項
- README・ドキュメントを勝手に生成・変更しない
- テストコードを確認なしに削除・コメントアウトしない
- main への直接プッシュ禁止
- .env の内容をコードにハードコード禁止

Mitchell Hashimoto のハーネスエンジニアリングの原則——「エージェントが失敗するたびに、同じ失敗を二度としないよう設定を工夫する」——の実践形である。

パターン4: コマンドチートシート

エージェントが最も時間を無駄にするのは「起動方法の解析」だ。頻出コマンドを明示する。

## 基本コマンド
npm run dev       # 開発サーバー起動
npm run build     # ビルド（astro check + astro build）
npm run test      # テスト実行
npm run check     # 型チェック

アンチパターン

アンチパターン1: 命令の過積載

指示が増えるほど、重複、優先順位の衝突、条件の見落としが起きやすくなります。固定の命令数を安全上限として扱わず、機械検証できる規則はlint、型、テスト、権限制御へ移します。

<!-- BAD: すべてを詰め込みすぎ -->
## コーディング規約
- 変数名はcamelCase
- 関数名もcamelCase
- 定数はUPPER_SNAKE_CASE
- インデントは2スペース
- セミコロンなし
- シングルクォート使用
- ...（50行続く）

こうしたスタイルルールは ESLint / Biome / Prettier に任せるべきだ。LLMにリンターの仕事をさせてはいけない。

アンチパターン2: 自動生成した内容を未確認で採用する

自動生成は初期ドラフトとして使えますが、存在しないコマンド、古い構成、過剰な一般則が入る場合があります。実際の正本とコマンドを確認し、人間が意図をレビューします。

アンチパターン3: タスク固有の指示

データベーススキーマの詳細や特定機能の実装方針など、すべてのセッションで必要ではない情報を含めると、無関係なタスクでノイズになる。

<!-- BAD: 特定タスクの指示 -->
## ユーザー認証の実装方針
OAuth2 + PKCE フローを使用し、トークンは httpOnly cookie に...

これは .claude/rules/ やタスク固有のドキュメントに分離する。

階層的な配置戦略

Claude Code は CLAUDE.md を複数階層から読み込む。

~/.claude/CLAUDE.md              # グローバル（全プロジェクト共通）
project-root/CLAUDE.md           # プロジェクトルート
project-root/.claude/rules/*.md  # ルールファイル群

レイヤー	記述内容	例
グローバル	個人の普遍的ルール	日本語応答、Conventional Commits
プロジェクト	プロジェクト固有の文脈	技術スタック、ビルドコマンド
ルールファイル	ドメイン別の詳細ルール	コーディング規約、テスト戦略

実践ポイント

定期的な棚卸し: 月1回、CLAUDE.md を見直す。守られていないルールは表現を変えるか、Hookで強制する
失敗駆動の追記: エージェントが同じミスを繰り返したら、その都度禁止事項を追加する
情報密度の監視: 重複・矛盾・タスク固有情報が増えたら、分離を検討する
チーム共有: CLAUDE.md はリポジトリにコミットし、チーム全員が同じハーネスで作業する