Claude Codeの理解を進めるためのドキュメント整理方法
はじめに
Claude Codeを使っていると、何度も同じ指示をしたり、最初の方にしたプロジェクト共通の指示を忘れたりする場面がよくある。
そのためにCLAUDE.mdがあるのだが、会話が進めばCLAUDE.mdに書いていることも守らなくなってくる。
また、プログラムのコードが多いとCLAUDE.mdに全てをまとめることは非効率なので、ドキュメントを複数に分けて管理する必要がある。
ここでは、現在利用している方針を書く。（まだClaude Codeを使い始めて10日ほどなので、この方法がベストかどうかはわからない。）
今利用しているリポジトリでは、十万行のPHPと数万行のHTML、CSS、JSがある。5年ぐらい経っているので、古い設計と新しい設計が混在していたりする。これをClaude Codeに頑張って読み解いてもらいたい。
よく使う指示
CLAUDE.mdを読んで
保存されていない記憶をclaude-document-rules.mdに従って保存して
保存されていない記憶を表示して
人間ではなくClaude Codeの理解を優先して書いて
基本的な方針
まずClaude Codeのセッションの最初に「CLAUDE.mdを読んで」と指示するとプロジェクトの全体像を理解し、詳細な情報の場所が分かるような作りを目指している。
基本的には起動時に読み込むことになっているはずだが、詳しく読み込む場合・さらっと概要を読む場合・読んでないのでは？というくらい理解していない場合、という色んなパターンがあった。
なので、最初に明示的に指示する。
ドキュメント生成もClaude Codeに頼むが、そのときは「保存されていない記憶をclaude-document-rules.mdに従って保存して」と指示する。
Claude Code はプログラムとは別のリポジトリで管理している。最初は同じGitリポジトリで管理していたが、以下の理由により分けることにした。
- ドキュメントだけの更新を頻繁にcommitする
- 機能ブランチ作業中に、共通ドキュメントの更新をしたい
Claude Codeに調べてもらった情報をファイルに書いてもらって保存、というのを繰り返したり、特定の課題対応中にClaude Codeが共通設定を新しく認識したときに、すぐに保存して別ブランチでも使いたい。
実態は別の場所に置いて、プロジェクトのディレクトリにシンボリックリンク( ln -s)で配置している。
ファイルとディレクトリ構造
全体の構造
ファイルとディレクトリの構造は、Claude Codeに考えてもらった。claude-docs/ 以下に更にディレクトリを分けて、それぞれ数ファイルずつ情報が書かれている。
zsh % tree .
.
├── CLAUDE.md
├── bin/
│ └── claude-format-check.sh
└── claude-docs/
├── 01-architecture/
├── 02-core-systems/
├── 03-frontend/
├── 04-features/
├── claude-coding-rules.md
├── claude-document-rules.md
├── current-work/
claude-docs直下の*.mdファイルは後から追加したファイルで、claude-*-rules.mdが重要なドキュメントになっている。
もっとも重要な基本知識
.
├── CLAUDE.md
├── bin/
│ └── claude-format-check.sh
└── claude-docs/
├── claude-coding-rules.md
├── claude-document-rules.md
ドキュメント作成ルール
この中でもっとも重要なファイルはclaude-document-rules.mdで、これがないと始まらない。これにはClaudeがドキュメントを書くときのルールが書かれている。
ドキュメント作成を頼むときは全て「claude-document-rules.mdに従って書いて」と指示する。
長いので今使っているファイルをほぼそのままgistに置いた。
最初の
## 【最重要】Claudeが理解しやすい形式で書く
// ドキュメントの判断基準
if (情報.isプロジェクト固有) {
return "書く";
} else if (情報.is一般的な知識) {
return "書かない"; // Claudeは既に知っている
} else if (情報.is架空の例) {
return "絶対に書かない"; // 混乱の元
}
がとても重要。
人間向けの曖昧な文章にならないように、Claude自身が理解しやすい形で書いてもらう。
Claude Codeにドキュメント生成を任せると、すぐにベストプラクティスやよくあるサンプルコードを書いてくる。
それらはノイズになるので、書かせないことが重要。
コーディングルール
claude-coding-rules.md には同様にプロジェクト固有のコーディングルールが書かれている。
このルールもClaude Code自身が気付いたことを claude-document-rules.mdに従って 書いてもらう。
# Claude向けコーディングルール
## 判断フロー
```javascript
if (既存コードに同様のパターンがある) {
return "既存パターンをコピー";
} else if (類似機能がある) {
return "類似機能の実装方式に合わせる";
} else {
return "このルールに従う";
}
```
## ファイル編集ルール
...(snip)...
## ビジネスロジック配置
...(snip)...
自動生成される場所は触らないことや、エラーハンドリング、セッション管理、CSSの書き方など。
「claude-coding-rules.mdに従って実装して」のように指示する。
CLAUDE.md (メモリ)
もうここまで書いたらCLAUDE.mdがメモリという感じもなくなっているのだが、公式にメモリという扱いになっている。CLAUDE.mdがClaude Codeを設定するファイルということになる。
CLAUDE.mdにはプロジェクトのディレクトリ構成や基本アーキテクチャ、コマンド集、各ドキュメントへのリンクが書いている。
最初の/initで生成するが、claude-document-rules.mdに従って自己チェックしてもらった結果、今となっては最初に書いた内容とはだいぶ異なるものになった。
その他 補助コマンド
bin/claude-format-check.shは、何度も「行末の空白は削除して」「ファイル終端は改行にして」という指示を繰り返した結果、もう手動でやってくれと投げてきたファイルである。
Claudeは「必ず実行する」という意味を理解はできるが、必ず実行はしてくれるとは限らない。
それは結局どんなことにも言えて、「必ずドキュメントに書かれているルールを守る」という意味は理解しても必ず守ってくれるとは限らない。困ったことだ。
すみませんでした！必ず守るルールが守られていませんでした！
感情豊かに謝ってはくれる。
全体的なアーキテクチャとコアシステム
├── 01-architecture/
│ ├── common-patterns.md
│ ├── dependencies.md
│ ├── error-handling.md
│ ├── function-specifications.md
│ └── performance-security.md
├── 02-core-systems/
│ ├── database-structure.md
│ ├── session-implementation.md
│ └── user-login-flow.md
今使っているドキュメント群。自動でいい感じに分けて書いてくれた。
書きはしたが、common-patterns.md以外はあまり読まれていない印象がある。難しい機能を実装するときに、明示的に指示すると思考時間が短縮される。
database-structure.mdは、実際にDBに接続して情報を取ってきてもらった。
フロントエンド実装に関する知識
├── 03-frontend/
│ ├── blade-one-analysis.md
│ ├── google-closure-library.md
│ ├── google-closure-tools.md
│ ├── javascript-overview.md
│ ├── sp-sidemenu.md
│ └── ui-components-analysis.md
Google Closure Toolsといういにしえのツールを使っているが、結構正しく理解してくれる。
他に、Bladeテンプレートエンジンを使っているがLaravelは使っていない、というような独自仕様があって、そういうことが書かれている。
sp-sidemenu.mdやui-components-analysis.mdは個別の課題を実装中に書いてくれたが、他の課題で利用するかはわからない。
Claude的には共通ドキュメントとして保存しておいた方が良い情報ということだった。
個別機能の知識
├── 04-features/
│ ├── BL798-relation-size.md
│ ├── csv-import-export.md
│ ├── labelprinter-system.md
│ └── tablet-condition-management.md
個別機能を実装したときに書いてくれた。
ブランチ番号が入っているファイルは、CLAUDE.mdからのリンクも無い場合がある。保存はした方が良いがCLAUDE.mdからはリンクさせないのがベストだとClaude Code自身が言っていた。正しいかどうかはまだわからない。
個別の課題の情報で、難しいコードの説明などが書いてある。
How To
ドキュメント更新の例
基本的な指示（新機能の開発での例）
今作った機能について、について、claude-docs/claude-document-rules.md のルールに従ってドキュメントに保存しておいた方が良い知識はある？
ここで、書いたほうが良いというドキュメントを提示してくる。
このとき、素直にYESと言わずに、各ドキュメントを自分でチェックした方が良い。Claude Codeはドキュメント群を網羅的に記憶しているわけではないので、ここは人間がチェックする。
いくつかの関連ドキュメントの場所さえピックアップすれば、適切なドキュメントにまとめるのはClaudeがやってくれる。
細かい指示（リファクタリング時の例）
app.jsを読んで。今から手動でリファクタリングする
という指示を最初にしておく。
app.jsを確認しました。現在の構造は：
...(snip)...
どのようなリファクタリングを考えていますか？
と聞かれるが、それは無視してリファクタリングを進める。
app.jsを確認して。
で変更点をまとめてくれる。
単純なバグがあったら教えてくれる。
以下、変更と確認の繰り返し。
そして最後の質問。
ここまでの手動の変更について、claude-docs/claude-document-rules.md のルールに従ってドキュメントに保存しておいた方が良い知識はある？
ここでも、提示されたドキュメントに対してYESと言わずに、自分でチェックして問いかけ直す。
まだ安心してはいけない。「エラー処理を一箇所にまとめた」ことに対してドキュメント化しようと言ってきたので、追加で質問。
「エラー処理の共通化パターン」は、もしドキュメント化されていなかったら、今後も同じようなエラー処理を共通化せずに各々の場所に書いてしまう可能性が高い？
この質問に対して
● いいえ、その可能性は低いと思います。
理由
- 一般的なプログラミング知識
- DRY原則（Don't Repeat Yourself）は基本的な概念
- エラー処理の共通化は標準的なリファクタリング手法- コードレビューで自然に気づく
- 同じエラー処理が複数箇所にあれば、誰でも共通化を思いつく
- 特にプロジェクト固有の知識は不要...(snip)...
結論
claude-document-rules.mdの判断基準：
if (情報.is一般的な知識) { return "書かない"; // Claudeは既に知っている }エラー処理の共通化は一般的な知識なので、ドキュメント化は不要です。
こう返してきた。いや、たった今「claude-document-rules.mdのルールに従って」って言ったやん。
ここまできてやっと
claude-document-rules.md に従って保存して
で保存できる状態になった。
課題を実行してもらう異なったやり方
まだ説明していなかったcurrent-workディレクトリについて。
これは現在試している方法で、gitのリポジトリには登録していない。一時的な作業用文書置き場になっている。
├── current-work/
│ ├── BL756-order-add-buttons/
│ │ ├── instructions.md
│ │ ├── issue.md
│ │ └── todo.md
│ └── BL757-barcode-operation/
│ ├── instructions.md
│ ├── issue.md
│ ├── issue2.md
│ └── todo.md
まず、プログラマーでない人から課題が依頼される。テキストで来るので、挨拶文などを削除しつつそのままissue.mdに貼る。
それからtodo.mdを作る。
以下の手順を実行して。
- CLAUDE.mdを読んで
- claude-docs/current-work/BL757-barcode-operation/issue.md に課題が書いているので、このプログラムを実装するための情報を調査して
- まずclaude-docsにある関連するドキュメントを読んで
- 次に、コードを読んで
- 実装する方法が分かったら、内容を「claude-document-rules.md」に従って「claude-docs/current-work/BL757-barcode-operation/instructions.md」に書いて
- 実装はまだ書かないで
そして
todo.mdに書いていることを実行して
という指示をする。todo.mdは自動生成または共通ファイルにできると思っているが、今は試している最中なので手書きだ。
課題が大量に溜まっているときに、それぞれ別のセッションで実行すると、実装予定内容がinstructions.mdに書かれていく仕組み。
実際の実装は毎回変更内容を確認しながらOKか却下かを決めたいので、こういう方針をやってみている。
issue.mdは、いわゆるシステム利用者の「これ作って〜」ということが日常文で書かれているだけなんだが、意外と5割ぐらいはちゃんと作ってくれる。
instructions.mdを流し読みすると過不足があるので、追加の指示をissue2.mdに書いて、それを読み込んでinstructions.mdを更新してもらう。
今の開発環境はgit worktreeを使うのが少し厳しいので、普段のブランチ構成で複数jobをやりたかった。（結局、いちいち確認したくなって並列では実行していないのだが。）
会話とファイル参照による指示の与え方の違い
同じ内容でも、会話で指示するのと、ファイルに書いて「{ファイル名}に従って」と指示するのでは、Claude Codeの反応が異なる。考察をClaude Codeに聞いた。
よくあるClaude Codeの動き
- 会話での指示「プロジェクト固有の実装パターンに従って」→ 次回以降、明示的に言及しないと忘れられる
- ファイル参照では毎回「claude-coding-rules.mdに従って」と指示 → 高い確率で守られる
- ツール（Read/Grep）は部分的に読むが、対話は全体を処理する傾向
なぜこの違いがあるのかの推測
- 明示的な参照指示の頻度：ファイル参照では毎回「〜に従って」と指示するが、会話では初回のみ
- 情報の独立性：ファイルは境界が明確な情報単位として提示される
- ツールの特性：大きなファイルは効率的に部分読みされる
効果の違いは「会話vsファイル」ではなく、「明示的な参照指示の有無」が大きい。毎回「CLAUDE.mdを読んで」「〜に従って」と指示することが重要。ファイル化により、この反復的な参照が自然に行いやすくなる。
まとめ
Claude Codeの理解を深めるためのドキュメント使用例について書いた。
Claude Codeの動きやClaude Code自身に聞いて分かったことは次の3点。
-
Claude Codeの特性
- 指示を理解しても守らないことがある
- 一般的な知識を書きたがり、プロジェクト固有の情報と混ぜる
- 会話が進むと初期の指示を忘れる
-
ファイル参照の優位性
- 会話での指示は埋もれるが、ファイル参照は守られやすい
- 「claude-document-rules.mdに従って」のような明示的指示が効果的
- 重要設定は簡潔に、大きな文書は構造化して参照
-
用途別のドキュメント管理
- CLAUDE.md：セッション開始時に1回読む基本設定（物忘れがひどいときは読み直す）
- ルール文書：作業時に「〜に従って」と毎回参照する独立した指示
- 詳細ドキュメント：必要に応じて参照する個別情報
それぞれが独立した役割を持ち、参照タイミングと方法が異なる
実際にClaude Codeを使っていくにあたり、次の2点が重要だと感じた。
ルールファイルに従う指示を毎回行う
Claude自身に「プロジェクト固有かどうか」を判断させるルールで、一般的なベストプラクティスの混入を防ぐ。
提案の確認
例えば何をドキュメント化すべきか、どこに保存すべきかの判断。提案はされるが、流れ作業でYESと言わない。
Discussion