1. リード
ファイルが増える日は、進んでいる気分になる。増えない日は、止まっている気分になる。私は長い間、後者を嫌っていた。だが Version 1.0 に近づくほど、止まって見えた時間——レビュー、文書化、用語統一——の価値が反転した。実装よりレビューの方が、プロジェクトを前に進めていたと、今なら言える。
これは「コードを書かないから仕方なく」という話ではない。書ける人ほど、レビューを軽くしがちだ。軽くしたレビューは、速い負債を生む。非エンジニアのプロジェクトでは、負債の利息が、そのまま朝の負担になる。
2. 背景
Connector が増え、Dashboard が増え、Human Approval の話が出る。増えたものは、それぞれ正しい理由を持っていた。だが全体として説明できるかは別問題だった。説明できない状態で Version を上げると、Version はラベルになる。ラベルは、安心の代用品にしかならない。
Vol.04 で仕様のオーナーは人間、と書いた。オーナーシップは、文書に落ちなければ消える。消えた仕様は、実装の速さで上書きされる。上書きは、気づいたときに巻き戻す。巻き戻しは、新機能の二倍の時間を食う。
だから「もう一段、実装を止めて整理する」週が来た。コードを増やさない Architecture Review。地味な Step だが、後の RC には直結する。
3. 今回のテーマ
テーマは、Documentation First と Architecture Review が、実装速度より効いた理由だ。
Documentation First は、きれいな文章を先に書くことではない。決めたこと、決めていないこと、変えた理由を、実装と同じタイミングで残すことだ。ADR（Architecture Decision Record）は、その短い形式。CHANGELOG は、外から見える履歴。architecture review は、散らばった設計を一枚の地図に戻す作業だ。
4. 実際の出来事
Step34.6 の Architecture Review は、Python も SQLite も Streamlit も触らなかった。触らないと、進んでいないように感じる。感じるが、成果物は多かった。glossary.md で用語を揃えた。Kagoshimaniax OS、Connector、SQLite Connector、Interactive MCP Connector、Human Approval——同じ言葉で話せるようになると、AI との会話が短くなる。
development-history.md で Phase を整理した。Step1 の MCP 統合構想は、方向転換ではなく成熟として記録した。成熟として書けると、過去の自分を責めなくてよい。責めないと、次の判断が速い。
ADR-0001 から ADR-0006 まで。SQLite、Connector、MCP、Interactive MCP、Human Approval、Local First。一つひとつは短い。短いから読める。読めるから、レビューで「これは既に決まっている」と言える。言えると、同じ議論の再演が減る。
constitution.md と philosophy.md も置いた。North Star は「毎朝 10 分以内に運営方針を決定」。派手な機能より、地味な指標の方が、プロジェクトを縛ってくれた。縛りは、自由の敵ではなく、迷いの敵だ。
失敗談: 私は何度も「文書はあとでいい」と言った。あとで書くと、書けない。実装の細部は忘れる。忘れた細部は、推測で埋められる。推測は、バグより怖い。バグは直せる。推測は、方針になる。
もう一つの失敗は、レビューを責め合いにすることだ。レビューは正しさの裁判ではない。説明可能性の点検だ。点検で「分からない」が出たら、勝ち負けではなく、文書化のタスクになる。タスクに落ちると、前に進める。
三つめは、CHANGELOG を更新し忘れることだ。更新し忘れると、過去の自分が他人になる。他人の判断を信頼できないと、また同じ所で止まる。止まるたびに、実装は進んでいるのに心が疲れる。
Documentation First が効いた場面は、Human Approval の議論だった。操作の棚卸し表は、実装前に読んだ。読んでから Green を選んだ。選んだあと実装した。順番が逆だと、作ったあとに「これは危ない」と気づく。気づきは遅い。
プロジェクトレビュー（Step39）では、Must と Nice、Known Limitations の話も整理した。整理しないまま RC に行くと、RC は「とりあえず出した版」になる。RC は、凍結の宣言であるべきだ。凍結を宣言するには、何を含み、何を含まないかが文書で説明できる必要がある。
Analytics のページが増えた時期も、実装は速かった。GA4、Search Console、Clarity、Metricool——グラフや表が並ぶと達成感がある。だがページだけ増えても、用語が揃っていなければ「どの数字を信じるか」が分からない。レビュー週に glossary.md を読み返したとき、自分が作ったはずの画面の説明が、他人の文章に見えた。他人の文章になるのは、決定の履歴が自分の頭にないからだ。履歴を外に出すと、頭が軽くなる。
README.md の書き直しも、実装ゼロの日に行った。表やリンクを整えるだけに見える。だが README は、プロジェクトの顔だ。顔が二枚あると、どちらも嘘っぽくなる。Architecture Review でブランド（Kagoshimaniax OS）と汎用アーキテクチャ（AI Local Business Platform）を分けたのも、同じ理由だった。分けると、何をこのサイトのためで、何を将来の型として残すかが話せる。
CHANGELOG に Step を追記する習慣は、最初は面倒だった。面倒な作業ほど、後から効く。効くのは、Qiita の原稿を書く今この瞬間だ。当時の感情を、ログと CHANGELOG が思い出させてくれる。思い出せるから、体験談として書ける。書けるから、技術解説ではない連載の価値が出る。
5. 考えたこと
レビューは、遅延ではなく圧縮だと思う。一回の整理で、何週間もの同じ議論を省略できる。省略は、時間の節約ではなく、注意の節約だ。注意は、非エンジニアの一番乏しい資源だ。
また、レビューは完璧を目指さない。用語が 100% 揃うまで待つと、永遠に出せない。揃えたところまでを Version で切る。切る勇気も、レビューの成果だ。Version 1.0.0-rc1 は、その切り方の一つになる。
AI はレビューに向いていた。反対意見、抜け漏れ、用語の揺れ——質問すれば返してくれる。返してくれるが、採択は人間だ。採択したものを ADR に残す。残すと、次の AI セッションも同じ地図から始められる。
レビュー週は、チームにとっての「休み」ではなかった。呼吸を整える週だ。散らばった判断を一度吸い上げ、吐き出す。吐き出したものが文書になる。文書は、次の実装の燃料になる。燃料がない実装は、短距離走には見えるが、マラソンには向かない。地域メディアの運営 OS は、マラソンだ。
非エンジニアがレビューを主戦場にできたのは、コード差分を読まなくても、決定と理由の文章なら査読できるからだ。査読できる領域を広げると、プロジェクトの主導権が自然と戻る。戻った主導権は、Human Approval の思想ともつながる。
Step ログを読み返す習慣は、レビュー週のあとも続けた。続けると、当時の「進んでいる感」が再現される。再現されると、同じ罠に気づける。罠は、成功体験のすぐそばにある。あるから、記録は祝杯の直後に書く。後だと美化される。美化は、体験談の敵だ。
6. 学び
- ファイルが増える日と、説明できる日は同じではない
- Documentation First は、決定と理由を実装と同時に残すこと
- ADR と CHANGELOG は、同じ議論の再演を減らす
- Architecture Review はコードを増やさなくても前に進める
- 用語統一は、AI との会話コストを下げる
- レビューは裁判ではなく、説明可能性の点検
7. 次回予告
次は、整理の先に置いた区切り——Version 1.0.0-rc1 までの道のり——を書く。足さない決断と、141 テストの話だ。
シリーズ情報
| 項目 | 内容 |
|---|---|
| Season | 1 |
| Vol | 08 |
| 現在の開発 Version | 1.0.0-rc1 |
| GitHub | https://github.com/boraemon2000/kagoshimaniax-os/tree/main/docs/qiita |
次回予告
Vol.09「Version1.0RCまでの道のり」
Step48 の凍結、Must チェックリスト、Known Limitations——RC の意味を書きます。