Claude Code 向けのドキュメントは3つに分ける（CLAUDE.md はルール、README はセットアップ、PROGRESS.md は次にやること）
- Claude Code
- ドキュメント
- 個人開発
Claude Code で開発していると、リポジトリに Markdown がどんどん増えます。CLAUDE.md（Claude が毎回読む指示書）、README.md、それから作業の続きを残すための PROGRESS.md です。
最初はどれも Claude に書いてもらっていました。すると、3つのファイルに同じ説明が少しずつ違う形で入る ようになります。API の説明が CLAUDE.md にも README.md にもあり、片方だけ更新されて食い違う、ということが起きました。
そこで、コード進行生成アプリ（Chord Eureka）のリポジトリで、役割を分け直しました。そのときの分け方をまとめます。
環境：Claude Code（Opus）/ Node.js の Web アプリ / 2026年9月
分け方
| ファイル | 書くこと | 読む人 |
|---|---|---|
CLAUDE.md | コマンド、ルールと落とし穴、デプロイの流れ、docs の一覧 | Claude（毎回） |
README.md | 機能の一覧、セットアップ（インストール・環境変数・起動）、デプロイ、ライセンス | 人（初めて触るとき） |
PROGRESS.md | 未完了のタスク と、今後の判断に効く 決定事項 だけ | Claude と自分（次の作業を始めるとき） |
docs/ | 調査・提案など、長い資料 | 必要なときだけ |
| git 履歴 | 完了したタスクの経緯 | 必要なときだけ |
それぞれのファイルの冒頭に、ほかのファイルの役割を1行で書いておきます。
CLAUDE.mdの冒頭：セットアップと環境変数はREADME.md、未完了タスクとオーナー判断はPROGRESS.md。
PROGRESS.mdの冒頭：コード上のルールはCLAUDE.md、完了タスクの経緯は git 履歴を参照。ここには未完了のタスクと、今後の判断に効く決定事項だけを記載する。
こう書いておくと、Claude が新しい情報を足すときに、どこに書くかを迷わなくなります。
整理の結果
3回のコミットに分けて整理しました。
| ファイル | 前 | 後 |
|---|---|---|
CLAUDE.md | 117行 | 50行 |
README.md | 172行 | 35行 |
PROGRESS.md | 227行 | 79行 |
ソースのコメントも、ドキュメントと重複しているものや、コードを読めば分かるものを削りました。最後のコミットだけで、9ファイル・318行を削っています。
CLAUDE.md は「ルールと落とし穴」だけ
一番減ったのは、コードの説明 です。整理する前の CLAUDE.md は、/init で作った英語の雛形に、Claude が説明を足し続けたものでした。
- 「Express のサーバーで、
public/から静的ファイルを配信する」 - 「
POST /generate-textはキーワードと小節数を受け取り、Claude でコード進行を作り……」 - 各モジュールが何をするかの説明が、1段落ずつ
どれも、コードを読めば分かることです。Claude は作業のたびにコードを読むので、ここに書いても役に立ちません。それどころか、コードを変えたのに説明が古いまま残ると、間違った前提を毎回読ませる ことになります。
残したのは、コードを読んでも分からないことです。
- やってはいけないこと：「トークン分割は
splitChordTokens()だけを使う。ほかで空白で分割すると、MIDI とラベルがずれる」 - 消してはいけない理由：「
/checkから/への 301 は、SNS に残る古い共有リンクのため。消さない」 - ハマったこと：「公開パスを
zで終わらせない（/healthzなどは Google Frontend が予約していて 404 になる）」 - とり忘れる手順：「OGP 画像に出る文字を増やしたら、フォントのサブセットを作り直す。ないと空白で描画される」
- オーナー（自分）の判断：「既定のボイシングは、既存の利用者の音を保つために固定。了承なしに変えない（2026-09-29 オーナー判断）」
最後の「オーナー判断」には日付を付けています。Claude が「直したほうがいい」と提案してきたときに、それがいつ・なぜ決めたことかを示せるからです。
README はセットアップだけ
README も、CLAUDE.md と同じ API の説明を持っていました。これを消して、人が最初に必要なことだけにしました。
- 何ができるアプリか（機能の一覧）
- インストール、環境変数、起動のコマンド
- デプロイの方法
- ライセンス
環境変数の一覧は、以前は CLAUDE.md にもありました。README だけに置いて、CLAUDE.md からは「セットアップは README」と指すだけにしています。
PROGRESS.md は「次にやること」だけ
PROGRESS.md は、セッションをまたいで作業を続けるためのファイルです。Claude Code は会話が終わると内容を忘れるので、「どこまでやったか」をここに残させていました。
ところが、残させているうちに 完了したタスクの記録 が溜まっていきました。「〜を実装した。理由は〜。テストは〜」という段落が、終わったタスクの数だけ並びます。整理したら227行が79行になったので、3分の2ほどがそれでした。
完了した記録は、git のコミットメッセージに同じことが書いてあります。そこで、PROGRESS.md には次の2つだけを残すことにしました。
- 未完了のタスク：大きさ（中・大）、アイデア（未着手・要設計判断）、保留・凍結（オーナー判断）に分ける
- 覚えておく決定事項：「テンションを足さない」のように、また同じ議論をしないための結論
終わったタスクは消します。経緯を知りたくなったら git log で探せます。
長い資料は docs/ に出す
調査や提案のように長い資料は、docs/ に分けました。CLAUDE.md の最後に一覧と1行の説明だけを書いておきます。
## Docs
- `docs/competitive-analysis.md` — 競合調査（プロダクト方針の根拠）
- `docs/ux-redesign-proposal.md` — UX 提案。PROGRESS.md の「施策N」はこの番号CLAUDE.md は毎回まるごと読まれるので、長い資料を入れるとそのぶん毎回コンテキストを使います。一覧だけにしておけば、Claude は必要なときにだけ開きます。
役目を終えたものは消す（か、凍結する）
ほかのリポジトリでも、同じ整理をしています。
- Windows アプリ：全機能が完成して公開したあと、
PROGRESS.mdそのものを消しました。「開発中の実装ログとしての役割を終えた」ためです - 画像生成サービス：完了した調査レポートや、対応の終わった不具合リストなど、約900行を消しました
- 別の Web アプリ：古い改善案のファイルは、消さずに先頭に
[ARCHIVED]と書いて凍結しました。頼んだのは「分割」で「削除」ではなかったので、Claude が消さずに残した形です。git 履歴を見なくても、凍結済みだと分かります
Claude に頼むときの言い方
整理は Claude に頼みました。そのとき効いたのは、ファイルごとに「書くこと」を先に決めて伝える ことです。
CLAUDE.md はルールと落とし穴だけ、README はセットアップだけにして。重複と、コードを読めば分かる説明は消して。
「整理して」とだけ頼むと、Claude は見出しを並べ替えたり、説明を書き足したりしがちです。何を残すかの基準を渡すと、消すほうに動いてくれます。
ふだんの作業では、Claude は変更のたびにドキュメントへ説明を足していきます。放っておくと増える一方なので、ときどき上の頼み方で削ってもらっています。
まとめ
CLAUDE.md・README.md・PROGRESS.mdを Claude に書かせていると、同じ説明が重複して食い違うCLAUDE.mdはルールと落とし穴、README はセットアップ、PROGRESS.mdは未完了のタスクと決定事項だけにする- コードを読めば分かる説明は書かない。古くなると間違った前提を毎回読ませることになる
- 完了したタスクの記録は git 履歴に任せて、
PROGRESS.mdから消す - 整理を頼むときは、ファイルごとに「書くこと」の基準を渡す
参考文献
この記事をシェア