コードの代わりに日本語仕様をコミットしています — 仕様3枚でPWAアプリ+サーバー

AIにコーディングさせる中で、ずっと引っかかっていたことが一つあります。成果物のコードは残るのに、そのコードを生んだ対話や意図は消えてしまいます。3か月後に「このコード、なぜこうなっているんだ？」と尋ねる相手がいません。

そこで発想を逆転してみました。意図を込めた仕様をgitにコミットし、コードはビルド成果物として扱うのです。検証も兼ねて、小さなアプリを一つ最後まで作って公開しました。

Rimlog というPWAで、読書・学習記録にAIが過去のメモをつなぎ合わせてくれます。サーバーなし、登録なし、データはブラウザ内だけにあります。

アプリ自体は普通です。共有したいのは作り方です。

方式

リポジトリのeux/フォルダに日本語仕様が3枚あります。アプリ全体の骨格が40行、AIカードウィジェットが25行、インサイトサーバーが1枚です。こんな文でできています。

saveCapture : キャプチャフォーム（ソース名・引用・自分の考え・タグ）を保存 — capturesの先頭に挿入 + ローカルストレージに反映 + 「保存しました」トースト + 記録タブへ切り替え。

このファイルをEstreUXというツールに入れるとコードが出てきます（brewと呼んでいます）。生成されたコードには仕様のハッシュが埋め込まれ、仕様だけを直したりコードだけを直したりするとpre-commitでコミットが止まります。仕様が古くなった瞬間に嘘になる問題を、ゲートで防ぐわけです。

数値も測ってみました。フレームワークに元からあった152行の数字キーパッドを28行の仕様に戻す形で実測したところ、人が保守する行数は60〜82%減りました。生成コード自体は元より長くなることもあります。減るのは、人が読んで直す側です。測定記録はリポジトリにあります。

サーバーも仕様1枚です

Pagesデモはサーバーレスなので、AIはタグ重複のフォールバックだけで動きます。きちんと動かすためにセルフホストサーバーを追加しましたが、これも仕様1枚からbrewした依存性0のNode単一ファイルです。バックエンドは選んで使います。

• nvidia（デフォルト）: build.nvidia.comの無料APIです。カード登録なしでキーが発行され、OpenAI互換で毎分40回前後なので、個人日誌には十分です
• claude-cli / codex-cli: リクエストごとにclaude -p / codex execを子プロセスとして呼びます。すでに払っているClaude/ChatGPTのサブスクリプションを、APIキーなしで再利用する経路です
• openai / google: 単純なキープロキシ

キーと認証はサーバー側にだけあり、ブラウザには出ません。

まだ確信が持てていないこと

仕様↔コードの整合性判定を、静的diffに加えてpropertyベースの動的検査へ拡張中ですが、重みのキャリブレーションがまだです。また、headless DOM環境でのフレームワークレンダリングが実ブラウザと違って動く偽陽性クラスを見つけたので、検証環境を実ブラウザへ昇格するのも課題です。コミット履歴を最初から見れば、スキャフォールド→仕様→生成→仕上げの過程が順番に残っています。

• ライブ: https://soliestre.github.io/Rimlog/
• リポジトリ: https://github.com/SoliEstre/Rimlog
• ビルド記録（詳細）: https://estreui.tistory.com/5

二つ気になっています。仕様をSSoTとして置く方式の落とし穴は何だと思いますか。特に、仕様の表現力がコードに追いつかない地点にどこで出会ったかが気になります。そして、claude -pをアプリのバックエンドとして使うサブスク再利用経路は、実運用で引っかかりそうな点はあるでしょうか（レート・規約・レイテンシの観点で）。