ひとりで複数のアプリを作っていると、「自分が覚えておけばいい」はすぐに破綻します。数週間前に決めた理由も、審査で変えたルールも、次の実装では忘れます。ClearDropでは、仕様を頭の中からリポジトリへ移すことを開発の一部にしています。 3つのアプリを並行しても判断をぶらさないための、文書の分け方と更新ルールを紹介します。 AIに実装を任せる割合が増えてから、この分け方の効き方が変わりました。読ませる相手が増えると、書いていないことは実装されないからです。
コードだけでは「なぜそうしたか」が残らない
コードを読めば、何をしているかは分かります。しかし「なぜ5票なのか」「なぜ正確な位置を返さないのか」「なぜこの機能を削ったのか」は、実装だけからほとんど復元できません。定数や条件式は結果を示しても、判断の背景までは持てないからです。
とくに、一度却下された仕様や、事故のあとに作ったルールは、理由を失うと元へ戻りやすくなります。未来の自分が見たとき、現在の制約だけが不自然に見え、「もっと簡単にできる」と以前の案を復活させてしまいます。
数か月前の自分は、今の自分にとって別の開発者に近い存在です。覚えている前提で進めず、初めて読む人が判断を再現できる程度に理由を残すようにしました。
ひとつの巨大な仕様書にはしない。役割で分ける
すべてを1ファイルへ集めれば探す場所は減りますが、更新するたびに長くなり、現在のルールと過去の経緯が混ざります。何が必須で、何が参考情報なのか分からない文書は、結局読まれません。
そこで、文書を目的で分けています。実装時に毎回守るもの、体験を決めた理由、起きた問題の記録、次にする作業は、読むタイミングが違います。ファイル数を減らすことより、必要な場面で必要な情報だけを読めることを優先しました。
- CLAUDE.md：現在守る仕様とルール
- product spec / design：なぜその体験にしたか
- implementation log：何が起き、どう直したか
- NEXT / release log：次に何をするか、今どこにいるか
役割を分けても、同じ文章を複製はしません。詳細はひとつの正本に置き、ほかの文書からは参照します。分けるのは読む目的であり、事実の出どころを増やすためではありません。
CLAUDE.mdには「今、守るべきこと」だけを置く
開発ではCursorをエディターとして使い、TerminalからClaude Codeを起動しています。Claude Codeが作業開始時に読む場所として、各アプリのCLAUDE.mdに現在の仕様と開発ルールを置いています。
ここには、変更してはいけないデータの扱い、採用している構成、確認コマンド、実装時の禁止事項などを置きます。過去に何が起きたかを長く説明するより、今の変更で守るべき境界を短く明確にします。
DOCHIでは一時、CLAUDE.mdの大半が過去の実装記録になりました。情報は多いのに、今の実装で何を優先するかが埋もれます。そこで経緯を実装ログへ移し、現在の指示だけが前に出る形へ戻しました。
仕様・実装記録・次の作業を、別の場所に分ける
product specには、ユーザーができること、画面の流れ、権限、例外を置きます。designには、なぜその選択をしたか、代案をなぜ採用しなかったかを残します。現在の仕様と意思決定を近くに置きつつ、同じ役割にはしません。
implementation logには、本番障害、審査の指摘、調査で分かった原因、修正結果など、時系列で起きたことを書きます。現在の仕様へ反映した内容は正本側も更新し、ログだけを読まなくても今の状態が分かるようにします。
NEXTには未完了の作業だけを置き、終わった作業を履歴として溜め込みません。完了の事実を残す必要がある場合はrelease logへ移します。「現在」「理由」「履歴」「次」を混ぜないことが、複数プロジェクトを切り替えるときに効きました。
同じ情報を、2か所で手入力しないようにする
仕様を文書へ移しても、正本が増えすぎると別の問題が起きます。価格、アプリの状態、規約、サポート内容などを複数箇所へ書くと、いつか片方だけ古くなります。記憶を外へ出したはずが、どれを信じるかという新しい負担を作ります。
そのため、機械が読める情報はできるだけ1か所へ寄せ、ページや構造化データはそこから生成します。文章でも、同じ回答を記事へコピーせず、正本への参照にします。変わりやすい数値や状態ほど、手で同期する場所を減らします。
正本を1つにする考え方は、同じ規約を2か所に置いたら、片方だけ古くなった。正本の決め方でも書きました。個人開発ではレビューする人が増えないぶん、同期する場所を減らすほうが効きます。
AIに実装を任せるほど、判断を文章にする必要がある
Claude Codeはコードを書く速度を大きく上げてくれます。ただ、速く書けることと、何を作るべきかが自動で決まることは別です。背景がなければ、AIは目の前のコードと一般的な慣習から自然に見える案を選びます。
「この画面はなぜ存在するのか」「この制約はUXではなく安全要件なのか」「変更してはいけない数字はどれか」が文章になっていないと、過去に退けた案が再び提案されます。実装が速いぶん、間違った方向へ進む距離も長くなります。
だから、AIへ長い指示を毎回書くのではなく、判断済みのことをリポジトリ側に残し、次のセッションでも同じ前提から始められるようにするほうを重視しています。依頼文は作業の差分に集中させ、変わらない前提はプロジェクト側が持ちます。
仕様書の作り方をこれから整える場合は、アプリの仕様書は何を書けばいい？個人開発で使う九つの項目で、目的、対象外、画面、データ、完了条件を分ける基本形も紹介しています。
文書を増やす前に、更新のタイミングを決める
文書は作っただけでは古くなります。そこで、いつ更新するかを作業の流れへ入れています。仕様を変えたらproduct spec、運用上のルールが増えたらCLAUDE.md、障害や審査対応が終わったらimplementation logを確認します。
コードと文書の変更を同じ単位で扱えば、あとでまとめて思い出す必要がありません。とくに、画面では分からない制約や、将来消したくなる一見不自然な処理には、変更した時点で理由を残します。
- 仕様変更：現在の正本と完了条件を更新する
- 障害対応：原因、影響、復旧、再発防止を記録する
- 審査対応：指摘と変更理由を残す
- リリース：実際に公開した状態へ記録を合わせる
- 作業終了：NEXTから完了項目を外す
更新のきっかけが決まっていれば、定期的に全ファイルを読み直す負担を減らせます。文書の量ではなく、変更と一緒に正しく更新される仕組みを作ることが重要です。
古くなった文書を見つけたときは、新しい注意書きを上へ足すだけにしません。現在の正本を直し、不要になった説明は履歴へ移すか削ります。「以前はこうだった」が現在の指示と同じ強さで残ると、読む側はどちらを選ぶべきか判断できません。履歴を残すことと、現行仕様を曖昧にしないことを両立させます。
仕様を残すと、失敗も次のアプリの資産になる
本番障害、App Storeの却下、審査後に見つかった表示の食い違い。失敗はその場で直せば終わります。しかし、原因と判断を残しておけば、次のアプリで同じ確認項目として使えます。
記録するときは、反省文にせず再利用できる形へ変えます。何が起きたか、なぜ事前に見つからなかったか、次はどの段階で何を確認するかまで書きます。個人開発で失敗を記録する六項目。却下と障害から残した形式では、その残し方をさらに具体化しています。
ClearDropのJournalも、その延長にあります。完成したものだけではなく、途中で何を間違え、なぜ作り直したかを書くのは、外向けの発信であると同時に、自分たちの判断をもう一度言葉にする作業です。
頭の中にある仕様は、自分が忘れた瞬間に消えます。リポジトリにある仕様は、次の実装の入力になります。 複数のアプリを並行して作るようになって、一番変わった開発習慣です。
文書化に時間を使いすぎないことも意識しています。すべての会話や試行錯誤を残すのではなく、次の変更で判断を変える情報を選びます。誰が読んでも同じ結論になる必要はありませんが、少なくとも当時の制約と選択肢が分かれば、状況が変わったときに意図的に見直せます。それが、ただのメモと開発の入力になる仕様書の違いだと考えています。
