出社。帰宅。そしてビーフン。頑張って仕事した。成果がそれなりに出て安心する。
- 実装を詳細に説明した完全な仕様書を作るのは、メンテナンスのことを考えると誤った選択だ。実際は、基本的な概要と API 定義（自動生成したもの）、あとは基本的なシナリオのフローチャートとかシステム間の相互作用図ぐらいが書いてあればいいのではないか。それらはプレーンテキストでコードと併置されていることが望ましい（理由は言うまでもない）。もちろんビジネス的な事情がある場合、ある機能に関しては Wiki 的なものに実装のスナップショットを書かなきゃいけないこともあるだろうが、それは可能な限り最小限に留めておきたい。
- 「完全な仕様書」と比較すると、例えば ADR のような、なぜこう実装したのかという意思決定の背景を残すのは良い選択だ。仕様書はメンテナンスの必要があるが、「ある瞬間の意思決定の背景」についてはメンテナンスの必要がないからだ。それでいて、必要なときに参照することで実質的な仕様書として機能することができる。よほど体力のあるチームでない限り、メンテナンスするべき対象は少ないほど望ましい。コードや仕様書は書かれた瞬間から腐っていくし、ひとはいつか必ず退職する。そう、あなた自身も…
- いや、AI に「完全な仕様書」を書かせて PR のマージ前とかにジョブで修正させればもうええか。ワシが間違ってた、死のう（おわり）
- Docs as Code って言葉を知った。これをやりたいがなぁ