記事

Claude Codeでドキュメントを増やしすぎないための書き方

Claude Codeはドキュメントも量産します。CLAUDE.md・.claude/rules/・Skills・auto memory・docs/・コードコメントの役割分担と、必要な文書／不要な文書の判断基準、肥大化を防ぐ更新ルールを公式仕様ベースで整理します。

Claude Codeは頼んでいないのにdocs/配下にメモを足し、ディレクトリごとにREADMEを作り、CLAUDE.mdに説明文を書き足します。読まれないドキュメントは保守されず、やがて実装と矛盾して害になります。本記事は、何をどこに書き、何を書かないかを役割分担として決めるための記事です。

結論：ドキュメントは「層」で考える。全部1か所に書かない

Anthropic公式のメモリ仕様は、CLAUDE.mdについて「毎セッション読み込まれ、長いほど追従性が下がる。200行以内を目安にせよ」「各行について『これを消したらClaudeはミスするか？』を問い、ノーなら削れ」と明言しています（How Claude remembers your project、Best practices）。膨らんだCLAUDE.mdはかえって指示を無視させます。

だからドキュメントは1か所に積まず、読み込まれ方が違う層に振り分けます。

置き場所	読み込まれ方	書くもの
`CLAUDE.md`	毎セッション全文	毎回必要な事実（ビルド/テストコマンド・規約・構成・常に守るルール）
`.claude/rules/`	起動時、または`paths`一致時	テーマ別ルール（テスト・API設計など）。パス限定で必要時のみ
Skills（`.claude/skills/`）	必要と判断したとき随時	手順・ワークフロー・ドメイン知識
auto memory（`MEMORY.md`）	毎セッション先頭200行/25KB	Claudeが学んだ事実の索引。詳細は別トピックファイル
`docs/`	読まない（人間向け）	仕様・設計の意思決定・運用手順
コードコメント	該当ファイルを読むとき	「なぜそうしたか」

ファイル数そのものを増やさない設計は「AI開発でファイルが増えすぎる問題を防ぐ設計ルール」に詳しいので、本記事は「文書をどの層に書くか」に集中します。

必要な文書／不要な文書

公式のBest PracticesはCLAUDE.mdに書くべき／書かないべきを表で示しています。これはCLAUDE.mdに限らずドキュメント全体の判断軸として使えます。

書く価値があるもの

コードから推測できないBashコマンド（独自のビルド/テスト手順）
既定と違うコード規約・命名規則
リポジトリの作法（ブランチ命名・PR規約）
プロジェクト固有のアーキテクチャ決定
環境の癖（必須の環境変数）
非自明な落とし穴・gotcha

書かないほうがよいもの

コードを読めば分かること
言語の標準的な慣習（Claudeが既に知っている）
詳細なAPIドキュメント（公式へリンクするだけにする）
頻繁に変わる情報
ファイルごとの説明（コードベースの目次）
「きれいなコードを書く」のような自明な一般論

判断に迷ったら、公式の問いをそのまま使います。「これを消したらClaudeはミスするか？ノーなら消す」。 ドキュメントもコードと同じで、増やすほど保守債務になります。

CLAUDE.mdとの役割分担

「とりあえずCLAUDE.mdに書く」をやめ、次の基準で振り分けます。

毎回必要で短い事実 → CLAUDE.md（200行以内）
特定のディレクトリ/拡張子でだけ必要 → .claude/rules/にpaths付きで切り出す
手順や呼び出して使うワークフロー → Skill（オンデマンドで読み込まれ、毎回のコンテキストを汚さない）
人間のための仕様・設計記録 → docs/（Claudeには必要時だけ参照させる）

.claude/rules/はパス限定にできるので、関係ないファイルを触っているときは読み込まれません。

---
paths:
  - "src/api/**/*.ts"
---

# API実装ルール
- すべてのエンドポイントで入力検証を行う
- 標準のエラーレスポンス形式を使う

CLAUDE.mdが200行を超えそうなら、@pathインポートではなくpaths付きルールへ分割します。公式が明記しているとおり、@インポートは整理に役立つだけで、起動時に全文ロードされるためコンテキスト削減にはなりません。 人間向けの保守メモは、文脈トークンを消費しないブロックレベルHTMLコメント（）でCLAUDE.md内に残せます（コードブロック内のコメントは保持されます）。コンテキスト全体の3層設計は「Claude Codeに必要な情報だけ渡すコンテキスト設計」にまとめています。

auto memoryは別系統です。Claudeが学んだ事実を~/.claude/projects/<project>/memory/に自分で書き、MEMORY.mdは先頭200行または25KBだけが毎回読み込まれます。詳細トピックは別ファイルに逃がす設計なので、ここに人間が書く必要はありません。中身は/memoryで確認・編集できます。

増えすぎを防ぐ更新ルール

ドキュメントは「書いて終わり」にすると腐ります。次を運用ルールにします。

追記より置換：同じ話題が増えたら新規ファイルを足さず、既存を書き換える
生成ドキュメントは別PR：AIが作ったdocs/や設計メモは機能PRに混ぜず、人間が要否を判断してから別PRで入れる
サブディレクトリのREADMEは作らせない：依頼に無いREADME量産は禁止事項に明記する
「なぜ」だけコメントにする：「何をしているか」はコードで読める。コメントは意図・背景に限定
定期的に剪定する：矛盾・陳腐化した記述を月1で見直す（公式も「things go wrongのときに見直し、定期的に剪定せよ」と推奨）

依頼文の完了条件に検証を入れると、勝手な文書生成を抑えられます。

git diff --stat origin/main...HEAD -- '*.md' 'docs/**'

これをレビュー前に走らせ、依頼に無いMarkdownが増えていないかを人間が確認します。チームのナレッジをCLAUDE.md系で育てる運用は「CLAUDE.mdをチームのナレッジベースとして育てる方法」に分けてあります。

依頼文に入れるドキュメント禁止事項テンプレート

依頼文やCLAUDE.mdの禁止事項にそのまま貼れる形です。

## ドキュメントに関する禁止事項
- 依頼に明記がない限り、新規のREADME・docs配下ファイル・設計メモを作らない
- 既存ドキュメントの追記より、矛盾の修正を優先する
- コードを読めば分かる説明をコメントやドキュメントに書かない
- 詳細なAPI仕様はドキュメント本文に転記せず、公式へのリンクにとどめる
- ドキュメント生成は実装PRに混ぜず、必要なら別PRに分ける
完了時に、新規・変更したMarkdownファイルの一覧と各ファイルを足した理由を報告すること