初心者が数ヶ月Claude Codeで個人開発を続けていたら、コードは動いているのに「もう何が残っているのか分からない」状態になりました。
原因を追ったらコードではなくドキュメントの構造が壊れていて、そこで決めた記録ルールを残しておきます。
つまづき1：TODOリストが嘘をつき始めた
開発記録の末尾に「今後の拡張候補（未着手）」を置いていました。ある日ちゃんと読んだら、そこに並んでいる項目のうち3つは、同じファイルの別の場所に「実装済み」と書いてありました。
しかも設計書のほうにも別の未着手リストがあって、そこにも同じ3つが残っていた。「### 次のステップ」という見出しが、ファイル内に2つ並んでいたりもしました。
実態は「ほぼ終わり、残りわずか」なのに、リストは「まだ山ほどある」と言ってくる。この乖離がしんどさの正体でした。
Claude Codeは追記は上手いのですが、完了しても行を消しません。言わないと ~~完了~~ で残したりもします。放っておくと単調増加します。
こう直した
TODOの置き場を1ファイルに固定して、ルールをこう書きました。
- 未着手タスクの唯一の置き場は TODO.md
- 他のファイルに「今後の課題」「次のステップ」「未着手」の見出しを作らない
- 実装が終わったら、そのセッションのうちに TODO.md の行を削除し、
実装記録側に [実装済み] として書く
- TODO側に「完了」と書き残さない（二重管理になってまた腐る）
- 「次にやる」は常に2件以内に保つ
効いたのは最後から2番目の「完了と書き残さない」でした。これを書かないと親切心で残されます。
つまづき2：「なぜ」と「どう」が混ざっていた
最初の分け方自体は悪くなかったんです。
- 設計書 … なぜそうするのか
- 開発記録 … 実際どう動くか、どこでハマったか
ちゃんと役割を決めていた。なのに数ヶ月後、設計書のほうに関数名・データ構造・環境変数名・テスト方針・コミット計画まで流れ込んでいました。結果、設計書が875行。
「なぜこうしたんだっけ」を確認したいだけなのに、実装詳細を延々読まされる。
こう直した
設計書に書いてはいけないものを列挙しました。禁止リストのほうが守られます。
設計書に書かない: 関数名 / ファイル名 / 環境変数名 / コミット計画 / テスト手順
既に混ざっていた分は、「目的・決定事項」だけ設計書に残して、データモデル以降は実装記録に移しました。この境界で機械的に切れます。
つまづき3：確定と未確定が同じ見出しの下に同居していた
これが一番厄介でした。
## 10. 拡張候補（未着手） ← 見出しは「未着手」
- A機能 — 未着手
- B機能 — 設計確定（2026-09-09）→ 10.4 ← 実装まで終わっている
## 10.1 C機能（設計確定） ← 確定設計が「未着手」章の入れ子
### 目的
### データモデル
### コミット計画
見出しがラベルとして機能しなくなっています。
人間なら「まあ中身読めば分かるし」で済みますが、Claude Codeは見出しを信じます。実装済みの機能を再実装しようとするか、逆に未着手を「もうある」と誤認するか、どちらかが起きます。
こう直した
使えるラベルを4つに固定して、機能見出しに必ず付けることにしました。
| ラベル | 意味 |
|---|---|
[実装済み] |
動いていて、実地で確認した |
[実装済み・未検証] |
コードは入ったが本番で試していない |
[設計確定・未実装] |
何を作るか決まった。あとは書くだけ |
[検討中] |
まだ決まっていない |
## ◯◯機能 [実装済み]（2026-09-09）
そのうえで、自分が実際にやらかした形をそのまま禁止事項に書きました。
### 禁止パターン
- ❌「拡張候補（未着手）」という見出しの下に、確定した設計を書く
- ❌ 確定事項の文中に「〜は今後検討」と混ぜる
- ❌ 同じファイルに「次のステップ」という見出しを2つ作る
抽象的な原則より、こっちのほうが効きました。
つまづき4：本質じゃない記録が、本質の記録を埋めていた
開発記録を読み返して一番驚いたのがこれでした。記述量のかなりの割合が、作っているものの仕様とは無関係だったんです。
- LLMの無料枠に引っかかった対処
- 別プロバイダへのフォールバックと形式変換
- トークン上限超過の自動リトライ
- 特定の型をDBに往復させると壊れる件
- 開発環境が壊れて復旧した記録
どれも必要な記録ではあります。でもこれ、何を作っていても出てくる話なんですよね。それがドメインの仕様と時系列で混ざっていたので、仕様を確認したいだけのときに無関係な記録を大量に読まされていました。
AIは目の前のエラーを潰すのが上手いので、潰した記録がどんどん積もります。
こう直した
実装記録を2つに割りました。
-
DEVELOPMENT.md… ドメイン（このアプリ固有の仕様） -
PLATFORM.md… 基盤（LLM・クラウド・認証・デプロイ・制約回避）
迷ったときの判定はこれ一文で足りました。
この文章を、まったく別ジャンルのアプリを作っている人が読んで、そのまま役に立つか？
役に立つなら基盤。自分のアプリの話が必要ならドメイン。
ファイルが短くなること以上に、次のセッションで「今どっちの話をしているか」が読む前に決まるのが良かったです。
落ち着いた構成
CLAUDE.md 記録のルール（どこに何を書くか）。薄く保つ
設計.md なぜそうするか。目的・決定事項・制約・不採用案の理由
DEVELOPMENT.md ドメインがどう動くか
PLATFORM.md 基盤がどう動くか
TODO.md これからやること（唯一の置き場）
CLAUDE.md には「何を作るか」は書かず、どこに何を書くかだけ書いています。毎回読まれるので薄いほうがいい。
あと、ドキュメントを長くしすぎないほうがいいと途中で気づきました。読むこと自体がコンテキストを食うので、1000行超のファイルを毎回読ませると実装に使える余地が減ります。人間向けの「網羅的なほど良い」とは逆でした。
実際に効いたのは2つだけ
ルールを書いただけでは守られませんでした。実行可能な形にして初めて機能しました。
セッション終了時のチェックリスト
1. 触った機能の見出しに正しい状態ラベルが付いているか
2. 完了したタスクを TODO.md から消したか
3. 新しく分かった「やること」を TODO.md に足したか
4. 「なぜ」を設計書に、「どう」を実装記録に書き分けたか
5. 設計書に関数名・ファイル名・環境変数名を書いていないか
セッションの終わりに「終了時チェックを実行して」と一言添えるだけです。
「次にやる」を2件以内に保つ
3件目以降は別の見出しに落とす。これだけで、開くたびに圧倒される感じがなくなりました。
逆に言うと、この2つが回らないと他のルールは意味がないです。
以上です！