「コードが正、docs にはコードから分かることを書かない」で運用したら、自分が把握できなくなった — 鮮度を検査できる写しとして書き直すまで

ドキュメントは陳腐化する、という前提で始めた

ドキュメントとソースコードが乖離していく現場は、いくつも見てきた。書いた直後は正しくても、コードが変わるたびに誰かが直さないといけない。直さなければ、ドキュメントは静かに嘘をつき始める。

だから自分の個人開発では、最初から「コードが正」とした。docs に書くのは、なぜそうしたか (設計判断や ADR) と、守るべきルールだけ。API の一覧や処理の流れのように、コードを読めば分かることは残さない。

開発の主体は Claude Code だ。仕様のほとんどはコードにあり、知りたければ Claude に読ませればいい。この軸自体は、今でも間違っていないと思っている。

把握しきれなくなったのは、自分だった

困ったのは、規模が大きくなってからだ。docs は Markdown で 110 本、3 万 7 千行ほどになっていた。ほとんどが文章で、GitHub の上で読んで全体を把握するには大きすぎる。

正直、把握しきれていなかった。気になるたびに Claude にピンポイントで聞いて、その場で HTML にまとめてもらっていた。そのためのスキルまで作ったくらいだ。

最初は、読みにくさを何とかしたいと考えていた。Claude との壁打ちでも、最初に出てきたのは「サービスの一覧や依存関係の図を生成する」という案だった。でも、それは違った。どんなサービスがあって、どんな機能かは、ざっくり分かっている。全部自分が提案して作ってきたものだ。

知りたくなるのは、たとえばこういうことだ。

• AI と会話するサービスの「勉強バッチ」は、どういう条件で発火していたか
• 管理画面へのエラー通知は、どういう経路で飛んでいたか

Markdown を探せば済む話なのだろう。でも、手間というか、探す気になれない。実際に Claude に勉強バッチを調べさせたら、仕様は 769 行の設計資料の 4 つの節に散らばっていた。ADR を時系列に積み上げているので、「今どう動くか」は複数の判断を頭の中で合成しないと分からない。

話していて気づいた。足りないのは、仕様書だった。

仕様書が欲しい。でも、保守はしたくない

ここで自分の方針とぶつかる。仕様書を書けば、コードから分かることを docs に書くことになる。齟齬が出るたびにチェックして保守する運用は、あまりに面倒だ。それが嫌で、あの方針にしたはずだった。

落ち着かせ方を Claude と探して、仕様書を「コードを正としたときの、人が読める写し」と位置づけることにした。

• 1 枚に 1 テーマで、今のコードがどう動くかだけを書く (仕様カードと呼んでいる)
• カードの先頭 (frontmatter) に、元にしたソースファイルの一覧と、その中身の SHA-256 ハッシュを持たせる
• CI は、ソースのハッシュがカードの値と一致するかだけを見る。ずれていたら落とす
• ずれたカードは、コードを変えたその PR の中で、コードを読み直して作り直す

最初、Claude は「定期的に作り直す」案を出していた。でも、静的に判定できるなら、PR のたびに CI で見ればいい。そうすれば定期実行を考えなくて済む。CI で LLM を動かす必要もない。ハッシュの比較だけなら、速くて、決定的で、無料だ。

穴があるのは分かっている。CI が見ているのは「ソースが変わったか」だけで、本文が正しいかは見ていない。ハッシュだけ更新して通せば、カードは嘘をつく。だから、ルールとして「ハッシュだけを更新しない。本文が今のコードと合っているかを確かめてから作り直す」と書いた。それでも、この仕組みには意味がある。コードが変わったのにカードが手つかずのまま残る、という一番気づきにくい壊れ方は、CI が必ず止めるからだ。

ルールを捨てずに、言い直した

カードの仕組みを作っている途中で、もう一度引っかかった。カードの説明に「人の手で直さない」と書いていた。でも、結局 Claude に直させているなら、それに意味はあるのか。docs は特定のツールに依存した書き方をしない、というルールもあったはずだ。

最初は、カードを docs の外に出すことも考えた。そこで割り込んで、考え直した。外に出すのではない。「docs にコードから分かることを書かない」というルールそのものが、見直しのタイミングなのだと。

あのルールの本当の理由は、「手で書いた写しは、鮮度を保てない」ことだった。コードから分かることを書くのが悪いのではない。書いたものが、いつの間にか古くなるのが悪い。それなら、鮮度を機械で検査できる写しは、そもそもルールの対象外になる。

そこで、こう言い直した。

コードからわかることを、手で書いて保守しない。書くなら、鮮度を機械的に検査できる写しとして書く。

「誰が直すか」も消えた。大事なのは、カードの文面だけを単独で直さず、コードを変える PR の中で作り直すことだ。人が直しても、Claude が直しても同じことになる。docs を書くためのスキルも、カード専用に新しく作るのはやめて、既存のスキルに一本化した。docs の扱いが変わっただけで、docs を書きたいという点は何も変わらないからだ。

作りながら、ほかにもいくつか決め直した。

• 用語のカードを足した: 内部の用語は、作ったときは把握していたはずなのに忘れる。
• 廃止した用語は残さない: 一度は「古い ADR を読む助けに」と残した。でも、元にするソースが無いのでハッシュの検査が効かない。自分で決めたルールに反するので消した。
• 処理の説明は、箇条書きよりフロー図にする: mermaid で書いた。

3 日で 11 サービス、写してみたら

壁打ちから始めて、仕組み、公開、全サービスへの展開、既存の設計資料の整理まで、3 日かかった。11 サービスで 223 枚。公開は VitePress で作ったサイトを GitHub Pages に出している。

写す作業そのものが、思わぬ監査になった。コードを読んでカードに起こすたびに、コードと docs の食い違いが出てくる。1 つのサービスで 10 件以上出ることも珍しくなかった。ほとんどは docs の書き方の古さだった。ただ、中には本物のバグもあった。エラーを受け止めるはずの仕組みが、実際の AWS の設定では空になっていた。作り直しのときに丸ごと消えて、未実装に戻っていた機能も見つかった。

一番大きかったのは、狙っていなかった副産物だ。画面のカードには、スクリーンショットを載せることにした。カードに画面が載っていれば、画面仕様として見たくなる。都度画面を開くより、載っていたほうが嬉しい。エラーやダイアログも含めて、全部で 579 枚ある。

これが、変更のたびに画像の差分として PR に出てくる。コードの差分だけでなく、何が変わったのかが目で見て分かる。正直、これは大きすぎる副産物だった。

一方で、本来の目的だった「仕様を引く」機会は、まだ来ていない。勉強バッチの条件を知りたくなるような場面は、これからだ。期待しているところでもある。