🧭 本記事は Claude Code実務運用シリーズ の STEP 2「指示ファイルを整理する」です。
CLAUDE.md/AGENTS.mdが100行を超えて無視され始めたら、この記事の分割基準で立て直します。
シリーズ全体の地図と読む順は 親記事 にまとめています。
はじめに
Claude Code や Codex をチーム導入すると、AGENTS.md / CLAUDE.md にルールをどんどん追記したくなります。
しかし、指示ファイルを丁寧に育てすぎると、あるタイミングでメンバーがこう言い始めます。
「そのファイル、最初にAIへ“無視して”って言ってます」
この記事では、約300行まで膨らんだ CLAUDE.md を100行弱まで削り、残りをスキル7本・サブエージェント3本に分けたときの判断基準を書きます。
結論はシンプルです。
AGENTS.md/CLAUDE.mdに残すのは、「全員そろっていないと協業が壊れるもの」だけ。
参考までに、Anthropic公式ページでは Boris Cherny 氏が Claude Code の inventor / founder として紹介されています。
また、二次解説では、Boris 氏の CLAUDE.md は約2,500 tokens、英語ベースの目安で約100行程度だと紹介されています。
- How the Creator of Claude Code Actually Uses It
- Your CLAUDE.md Is Probably Wrong: 7 Mistakes Boris Cherny Never Makes
ただし、日本語の AGENTS.md / CLAUDE.md では、同じ100行でもトークン数が同じになるとは限りません。
日本語は英語とトークン化のされ方が異なるため、100行という数字をそのまま上限として扱うのは少し危険です。
実務上は、英語で約100行という目安をそのまま採用するより、日本語ではもう少し安全側に倒して、70〜80行程度を一つの目安にした方がよさそうです。
AGENTS.md / CLAUDE.md は毎回コンテキストに入る前提のファイルなので、常時読み込ませる内容はできるだけ絞るべきです。
メンバーが「無視して」と言い始める
きっかけは雑談の中の一言だった。「自分、最初にそのファイル読まなくていいって指示してる」。
CLAUDE.md はチーム共通のAI指針として置いてあった。規約、Git運用、ビルド手順、社内ツールの使い方。開発に必要なことが網羅的にまとまっていて、出来は良かった。なのに、何人かが毎回それをスキップしていた。
最初は好みの問題かと思った。聞いてみると、みんな同じようなことを言う。関係ない手順まで毎回出てきて応答が遠回りになる。自分のやり方と食い違う指示が混ざっていて、いちいち打ち消すのが面倒。そもそも量が多くて、どれが絶対でどれが「ある時だけの話」なのか見分けがつかない。
中身が悪いんじゃない。全員に同じ分厚い指針を毎回読ませる、その構造が合わない人を生んでいた。
特定のプロダクトや個人の話ではない。AIエージェントを業務に入れたチームなら、言語も規模も問わず起きうる話として読んでほしい。本文中の CLAUDE.md の例はすべて架空のサンプルに置き換えている。
どれだけ膨らんでいたか（ビフォー）
実物は出せないので、雰囲気を架空で再現する。当時の CLAUDE.md は、たとえばこんな調子の記述が延々と続いていた。
## ビルド・テスト手順
- 普段の検証は <workspace> を優先する
- shared scheme は A-Release / A-AdHoc / A-Tests / Sandbox
- 既定の simulator はその時点で最新世代の Pro Max を優先し、
無ければ Pro、さらに無ければ通常モデル。OS は最新の Runtime を優先
- CLI で destination を明示する場合も name=機種17 / OS=26.2 のような
固定値を埋め込まず、上のルールで選んだ機種 + OS=latest を使う
- Build 例: xcodebuild build -workspace ... -scheme 'A-Release' -destination '...'
- Test 例: xcodebuild test -workspace ... -testPlan StandardTests -destination '...' -parallel-testing-enabled NO
- 通常は -derivedDataPath などの特殊オプションを足さず、まず標準コマンドで実行する
- 権限昇格が拒否されたら /tmp 退避で無理に続行せず、その時点で実行不能として扱う
## チケット記法
- 説明欄・コメントは textile で書く。本文全体を <pre> で囲まない
- インラインコードは @...@、見出しは h3. h4.、箇条書きは行頭 *
- コードブロックは <pre><code class="swift"> ... </code></pre>
- 他チケット参照は ##番号、コメント参照は #note-N
...
これがこの調子で、ビルド、テスト、記法、ドキュメント執筆、調査ツールの使い方、リリース履歴の更新手順……と、約300行続く。
悪いのは内容そのものではなく、性質の混ざり方だ。見てのとおり、
-
特定作業の時しか使わない手順（
xcodebuildのオプション）が常駐している - 人によって好みが割れるもの（記法を textile に固定）が全員への強制になっている
- 細則が多すぎて、どれが「絶対」でどれが「ある状況だけ」なのか平坦で見分けられない
そして、これがAIに毎ターンまるごと読み込まれる。
中身は丁寧だ。手を抜いた形跡はどこにもない。だからこそ無視される、という話をする。
仕組みを知ると、無視される理由がわかる
ここが一番伝えたいところ。
AGENTS.md / CLAUDE.md は読み物ではなく、AIが毎ターン全文を読み込む前提のファイルです。
会話のどの場面でも、中身がまるごとコンテキストに載ります。
AGENTS.md / CLAUDE.md に、特定作業だけで使う手順まで書くと危険です。
たとえば、次のような情報です。
- ビルドコマンドの細かいオプション
- 社内ツールのサブコマンド一覧
- リリース履歴の更新手順
これらは本来、必要な作業のときだけ参照できれば十分です。
しかし、AGENTS.md / CLAUDE.md は全文読み込みされるため、雑談しているときも、バグを追っているときも、毎回コンテキストに入ります。
つまり、今の作業に関係ない手順まで、毎回トークンを消費します。
その結果、AIは毎回「これは今の作業に関係あるか？」を仕分ける必要があります。
指針が長いほど判断コストが増え、場合によっては関係ない手順に引っ張られます。
もう一つの問題は、指針の中に性質の違うものが混ざっていたことです。
ブランチ命名、コミット形式、壊してはいけない設定のように、全員でそろっていないと協業が壊れるものがあります。
一方で、チケットの記法、GitをGUIで使うかCLIで使うか、調査にどのツールを使うかのように、人や状況によって最適解が変わるものもあります。
前者を共有するのは必要です。
困るのは、後者まで全員に強制してしまうことです。
「チケットはこの記法で」と全員に固定すると、別の記法のほうが合う人にとっては、便利なルールではなく足かせになります。
そして、ここがやっかいです。
丁寧に全部書いた人ほど、この罠にはまります。
手を抜いて膨らんだのではなく、良かれと思って全部書いた結果として膨らむからです。
本人に悪気がないので、周りも言い出しにくい。
気づいたら誰も読んでいない、という状態になります。
ここを誤解してほしくありません。
肥大化は「ダメな人がやらかすこと」ではありません。
むしろ責任感が強く、チームのために漏れなく書こうとした人ほど起きます。
だから犯人探しをしても解決しません。
直すべきは、人ではなくファイルの構造です。
残すか、出すか。基準は1つ
立て直すとき、問いを1つに絞った。
それは「全員そろってないと協業が物理的に壊れるもの」か?
AGENTS.md / CLAUDE.md に残すもの・外に出すもののチェックリスト
判断に迷ったら、次の表で分ける。
| 判断項目 | AGENTS.md / CLAUDE.md に残す | スキル / サブエージェントへ出す |
|---|---|---|
| 全員が守らないとビルドや開発環境が壊れる | ✅ | - |
| Git履歴・PR品質・レビュー観点に影響する | ✅ | - |
| 一次情報の参照先として全員が知る必要がある | ✅ | - |
| 特定作業のときだけ使う手順である | - | ✅ |
| 人によってやり方や好みが分かれる | - | ✅ |
| 長いコマンド例や細かい手順説明が必要 | - | ✅ |
| 重い調査・解析・確認作業を任せたい | - | ✅ |
ポイントは、便利かどうかではなく、
全員が同じ状態で守らないと協業が壊れるかで判断すること。
意識したのは、「便利だから」を理由に残さないこと。便利さは、合わない人から見れば押し付けの言い訳になる。だから基準は「壊れるかどうか」まで削った。
この基準でふるいにかけると、CLAUDE.md に残ったのはこのあたりだった。応答言語、一次情報がどこにあるか、全員が破ると実害が出る技術的な前提、壊してはいけない設定、Git運用のうち履歴に残る規約。具体的にはこういう骨格になる（中身は架空のサンプル）。
# CLAUDE.md
ここに置くのは「全員そろってないと協業が壊れるもの」だけ。
記法の流儀・検証手順・ツールの使い方など、人や状況で最適が変わるものは
各自のスキル／サブエージェントに委ねる。一覧は docs/agents-catalog.md を参照（導入は任意）。
## 応答言語
- 回答・レビューコメント・要約は日本語で行う
## 一次情報の所在
- バックログはチケット管理ツールで管理（参照は ticket-mcp）
- 要件資料は <デザインツール> に格納
- 議論は <チャット> の #dev チャンネル
## 全員で守る技術的前提（破ると全員に実害が出る）
- 言語の strict モードを維持する。警告ゼロを保つ
## 変更しないもの（一人が変えると全員のビルドが壊れる）
- 署名設定 / bundle identifier / 依存ライブラリのバージョン / Package.resolved
## Git 運用規約（履歴は全員で共有する）
- ブランチ命名: feature/<番号> / fix/<番号>
- コミット1行目: #<番号>: <タイトル>
- PR には「変更内容」「レビュー観点」を必ず含める
逆に外へ出したのは、人や状況で最適が変わる「手順」だ。これをスキルとサブエージェントに振り分けた。
| 種類 | 例 | なぜ外に出すか |
|---|---|---|
| スキル | 記法整形 | 人によって好みの記法が違う |
| スキル | リリース履歴の更新 | リリース時にしか使わない |
| スキル | ビルド／テスト実行 | 普段のターンには無関係 |
| スキル | 調査ツールの使い方 | ツール固有・常時は不要 |
| スキル | 試験項目の作成 | ガイド前提の定型作業 |
| スキル | ドキュメント執筆 | 文体の強制は押し付けになりやすい |
| スキル | 記法選択の設定 | textile / Markdown を各自で選ぶ |
| サブエージェント | クラッシュlog解析 | 重い解析を別コンテキストで完結 |
| サブエージェント | ドキュメント整合性検査 | 専門タスク・並列向き |
| サブエージェント | 影響範囲の参照監査 | 削除前の安全確認を独立実行 |
スキルは「特定のキーワードで発火する定型手順」、サブエージェントは「独立したコンテキストで完結させたい重い専門タスク」と考えると分けやすい。
300行が100行弱になった。3分の1以下。
「強制しない」を仕組みで守る
外に出した手順をスキルやサブエージェントにするのは、手を動かせばできる。難しいのは強制せずに配るほうだった。分けたところで、また全員に同じものを強制したら何も変わらない。
使ったのは、置き場所の性質だ。AIエージェント用のツールを置くディレクトリを .gitignore に入れておく。そうすると、そこにツールを置いてもgitには載らない。つまり他のメンバーに共有も強制もされない。使いたい人は自分の環境に展開する。要らない人は展開しないか、個別に消す。「コピーすれば即使える」と「入れるか入れないかは本人の自由」が同時に成り立つ。
配置にするとこうなる。
<リポジトリ>/
├─ CLAUDE.md ← slim版。gitで共有する（全員の合意事項）
├─ docs/
│ └─ agents-catalog.md ← どんなツールがあるかの一覧。gitで共有
└─ .claude/ ← .gitignore 済み = gitに載らない・各自の手元だけ
├─ skills/ ← 入れた人だけ有効
│ ├─ format-notation/ 記法整形
│ │ ├─ SKILL.md
│ │ └─ references/
│ │ ├─ format-choice.md ← 既定の記法を各自で選ぶ設定
│ │ ├─ textile.md
│ │ └─ markdown.md
│ ├─ release-changelog/ リリース履歴の更新
│ ├─ build-and-test/ ビルド／テスト実行
│ ├─ symbol-search/ 調査ツールの使い方
│ ├─ test-authoring/ 試験項目の作成
│ ├─ docs-authoring/ ドキュメント執筆
│ └─ storyboard-analysis/ 画面定義の調査
└─ agents/ ← 入れた人だけ有効
├─ crash-analysis.md クラッシュlog解析
├─ docs-consistency.md ドキュメント整合性検査
└─ reference-audit.md 影響範囲の参照監査
.gitignore に1行入れるだけ。
.claude/
ポイントは、共有したいもの（CLAUDE.md と一覧カタログ）はgit管理に残し、各自で選ぶもの（.claude/ 配下のスキル・サブエージェント）だけをgitから外すこと。エージェントツールはこのディレクトリを自動で見つけるので、置いた時点で有効になる。それでいてgitには載らないから、誰かに押し付けることにはならない。
CLAUDE.md には、用意してあるツールの一覧（docs/agents-catalog.md）へのリンクを1行だけ残した。どんな手順があるかは分かるけど、入れるかどうかは任せる、と書いておく。記法整形ツールも、複数の記法から各自が既定を選べるようにした。「全員で1つ」をやめて、「使う人が、使うものだけ入れる」に変えた。
やってみて思うこと
正直、最初から分けておくべきだったとは思っていない。立ち上げの頃は、1つのファイルに全部書くほうがむしろ速い。指針が育って、人が増えて、それぞれのやり方が固まってきた頃に、ようやく「全員に同じものを読ませる」コストが表に出てくる。だから肥大化は、失敗というよりチームが育った証拠でもある。
ただ、その段階に来てもなお1ファイルで押し通すと、メンバーは黙って避け始める。やっかいなのは、これが表に出ないこと。「無視してます」とわざわざ言いに来る人はいない。だから書いた本人だけが気づかないまま、指針が飾りになっていく。
もし自分のチームの AGENTS.md や CLAUDE.md が数百行に育っていて、最近やけに長いなと感じているなら、一度メンバーに聞いてみるといいと思う。これ、毎回ちゃんと効いてる? と。たぶん、うすうす答えは分かっているはずだ。
このシリーズの歩き方
Claude Code実務運用シリーズ ― 暴走させない、から仕組みにするまで。
- ◀ 前の記事: 18万スター超のCLAUDE.mdに学ぶ、Claude Codeを暴走させない運用術
- ▶ 次の記事: チームの AGENTS.md / CLAUDE.md が重すぎてAIエージェントが使い物にならないとき、自分の環境だけ守る方法
- 🔍 あわせて読む: Fable 5が復活したので、Claude Codeの運用ルールを3つのプロンプトで棚卸しした【プロンプト全公開】 ― 分割後の定期棚卸しはFable 5で
- 🗺 シリーズ全記事の地図(親記事)