仕様書を残す

コードは「今どう動くか」を示しますが、「なぜそうしたか」「何が正しい姿か」は示しません。弊社では、リポジトリの.docsディレクトリに仕様書を残します。製品の目的、対象利用者、画面や機能の仕様、そして採用しなかった案とその理由です。

誰のための仕様書か

まず自分のため、次にこの製品を触るすべての人とAIのためです。Claudeは会話とコードから読み取れることしか知らないため、仕様書があると、会話をまたいでも同じ全体像を渡せます。部分ごとの開発で起きる全体のぶれ（開発の「部分で進めて、全体で整える」）を抑える土台にもなります。

最新に保ち、コードとの差分をなくす

仕様書は放置すると古くなり、コードと食い違い始めます。かつては差分を人手で追い続ける根気が続かず、古い仕様書は捨てられがちでした。今は、コード全体と仕様書を突き合わせて差分を洗い出す作業を、AIが何時間でも続けてくれます。定期的にお願いして、仕様書を正本に保ちます。

.docsの仕様書とコードを突き合わせて、食い違っているところを一覧にして
仕様書を今のコードに合わせて更新して。仕様の方が正しそうな箇所は逆に報告して

どちらが正か

食い違いが見つかった時、機械的にどちらかへ揃えるのではなく、どちらが正しいかを判断します。仕様が正しければコードを直し、コードが正しければ仕様を更新します。この判断は製品の目的に関わるため、人が行います。仕様書を正本とした運用の全体像は製品で扱います。