TL;DR
CLAUDE.mdは入口であって、全部入り辞典ではない- ただし
AGENTS.md/ タスク台帳 /REPORT.mdを Claude Code の公式標準構成と誤解してはいけない。この記事はこのリポジトリの運用例である - 守るべきルール、現在の状態、再利用ワークフロー、強制したいガードレールは置き場を分けたほうが安定する
- このリポジトリでは
AGENTS.md = 規範、タスク台帳 /REPORT.md = 状態、skills = 再利用手順、hooks = 強制と分けている - AI運用の品質は、モデルの賢さよりコンテキストの配線で決まる
はじめに
CLAUDE.md を整備し始めると、多くのリポジトリで同じことが起きる。
背景、禁止事項、設計思想、よく使うコマンド、レビュー基準、作業手順、チームの約束事。全部をそこへ押し込みたくなる。でも、その設計は長続きしない。
Anthropic の公式ドキュメントでも、CLAUDE.md は毎回読み込まれるメモリの入口として扱われている。skills や hooks は別の責務を持ち、必要なときだけ呼ばれる、あるいは決定論的に強制される。つまり、文脈は1ファイルに集約するものではなく、役割ごとに配線するものだ。
このサイトでも、CLAUDE.md最適化の本質で「何をどこに分離するか」が重要だと書いた。今回はその続きとして、このリポジトリでは実際にどのファイルへ何を置いているかを、運用例として整理する。
なぜ CLAUDE.md だけでは足りないのか
CLAUDE.md に全部を書く設計が破綻しやすい理由は単純だ。1つのファイルに、性質の違う情報が混ざるからである。
- ずっと有効なルール
- いまこの瞬間だけ重要な状態
- たまにしか使わない手順
- 絶対に守らせたい制御
この4種類は更新頻度も、参照タイミングも、求める厳密さも違う。同じ箱に入れると、どれも中途半端になる。
たとえば「このリポジトリではタスク台帳が状態の正本である」は長期ルールだが、「いま進行中のタスクは何か」は状態情報だ。同列に扱うと、ルールは埋もれ、状態は古くなる。
4層で分けると整理しやすい
コンテキスト設計は、次の4層で分けると扱いやすい。ここでの表は Claude Code の公式必須構成ではなく、このリポジトリでの整理法だ。
| 層 | 役割 | 代表ファイル |
|---|---|---|
| Rules | 何を守るか | AGENTS.md, CLAUDE.md |
| State | いま何が起きているか | タスク台帳, REPORT.md |
| Workflow | どう進めるか | SKILL.md, workflows/*.md |
| Enforcement | 必ず実行させる | hooks |
この表のポイントは、CLAUDE.md を万能にしないことだ。CLAUDE.md は Rules 層の入口であり、State や Workflow を代替しない。
1. AGENTS.md は規範の正本
このリポジトリでは AGENTS.md が SSoT として置かれている。ここに書くべきなのは、全セッション・全エージェントに広く効く原則だ。
- 出力言語
- 変更手順
- 破壊的操作の禁止
- ディレクトリごとの責務
ここへ「今日の作業ログ」を書き始めたら崩れる。規範と状態を混ぜないことが重要だ。
2. タスク台帳と REPORT.md は状態の正本
AI運用でよくある事故は、「会話では進んでいるのに、ファイル上の状態が残っていない」ことだ。だから状態は別ファイルに分ける。
このリポジトリではタスク台帳が現在状態、REPORT.md が監査ログを持つ。これはかなり合理的だ。
- タスク台帳: いま何をやっているか
REPORT.md: いつ何をしたか
この2つがあると、セッションが切れても、別エージェントに引き継いでも、現在地を復元しやすい。
3. skills は再利用手順の置き場
Claude Code の skills は、たまにしか使わないが、使うときは毎回同じ品質で回したい作業に向いている。
たとえばこの記事制作なら、article-preflight、article-writing、article-self-review がそれに当たる。これを CLAUDE.md に毎回ベタ書きすると、普段はノイズでしかない。AIエージェント開発を支える共通基盤でも触れた通り、エージェント運用の安定化は「全部覚えさせる」より「必要なときに正しい文脈へ到達させる」設計のほうが効く。
4. hooks は自然言語ではなく強制の層
Anthropic の hooks ドキュメントでは、特定イベントに対してコマンドを実行し、必要なら処理継続を止めることまでできる。つまり hooks は「覚えておいてほしい」ではなく、「必ず通したい」を置く層だ。
pnpm test の実行、危険なコマンドのブロック、出力ファイルの存在確認。こういうものは rules より enforcement に置いたほうが事故が減る。
実装上も、単に .claude/hooks/ というディレクトリを置くだけでは動かない。実際には .claude/settings.json などでイベント、matcher、実行コマンドを結び付ける必要がある。スクリプト置き場として hooks/ を切るのは便利だが、強制が有効になるのは設定まで書いて初めてである。
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "pnpm test"
}
]
}
]
}
}
実装イメージ
リポジトリ全体を雑に整理すると、こういう役割分担になる。
AGENTS.md # 全体規範（このリポジトリ固有）
task-state file # 現在状態（このリポジトリ固有）
REPORT.md # 監査ログ（このリポジトリ固有）
.agents/skills/*/SKILL.md # 再利用ワークフロー
.agents/workflows/*.md # 手順の連結
.claude/settings.json # hooks 設定
scripts/* or .claude/hooks/* # hooks から呼ぶコマンド置き場
この形にしておくと、エージェントは「何を守るか」「今どこにいるか」「どう進めるか」「何が強制されるか」を別々に理解できる。
ここが曖昧だと、AIは賢い/賢くない以前に、単に迷う。コンテキスト不足というより、責務分離不足であることが多い。
失敗しやすいパターン
1. CLAUDE.md に全部書く
一番ありがちな失敗。規範、状態、手順、例外処理を全部入れて肥大化する。結果として重要なルールほど埋もれる。
2. 状態を会話履歴にしか残さない
その場では前に進めるが、次のセッションで位置を見失う。これはタスク台帳や REPORT.md がない運用で起きやすい。
3. 自然言語で祈る
「危険な変更はしないでください」「最後にテストしてください」と書いて終わるパターンだ。重要なら hooks や CI に落とすべきで、自然言語だけでは弱い。
どこから整備すべきか
ゼロから始めるなら、順番は次で十分だ。
- Claude Code の入口として
CLAUDE.mdを整える - このリポジトリのように独自の規範ファイルを使うなら
AGENTS.mdを分ける - タスク台帳と
REPORT.mdを作り、状態を会話から分離する - 反復作業を 3つだけ skill 化する
- 壊したくない箇所だけ hooks で強制する
ここで重要なのは、一気に完璧な構造を目指さないことだ。まずは rules / state / workflow / enforcement の4層を意識し、混ざっているものを少しずつ分ければいい。仕様や作業の時間軸をファイルに残す発想は、会話は流れるがファイルは残る：Requirements/Design/Tasksによる時間軸管理術や、エージェント開発の人間役割：コードを書かずに承認する仕事へともそのまま接続できる。
まとめ
CLAUDE.md を整備しただけで運用が安定しないのは普通だ。足りないのは熱量ではなく、コンテキストの分業である。
押さえるべき役割分担はシンプルだ。
AGENTS.mdで規範を定義する- タスク台帳 /
REPORT.mdで状態を残す - skills で再利用手順を持つ
- hooks で本当に大事な制御を強制する
まずは自分のリポジトリを見て、「規範」「状態」「手順」「強制」がどこで混ざっているかを洗い出してみてほしい。Claude Code 運用の安定化は、長いお願い文を書くことではなく、文脈を正しい置き場に戻すことから始まる。
