仕様書が陳腐化しない運用｜GitHub Issueを『最新仕様書』にする方法
本文
前の記事（ClaudeCodeとほぼ会話しなくなった話）への反応がいくつか来た。
変更履歴が消えていく人たち
Confluenceに仕様書いてる人、いるよな。
Notionでドキュメント管理してる人も。
「最新版ってどれですか？」「あ、こっちが古いです」「そっちはもう消して」——このやり取り、見覚えないか。
俺にはもうない。
イシューが変更履歴になる
このスタイルに変えてから気づいたことがある。
仕様変更の履歴が、イシューに全部残る。
意図して残してるわけじゃない。イシュー切って、打ち合わせして、議事録イシュー化して、PRで締めるだけ。それをやってたら、勝手に残った。
最新ドキュメントを「手に入れる」苦労がなくなった。正確に言うと、探す必要がなくなった。
ドキュメントの生成方法
やり方はシンプルだ。
- GitHubのイシューリストをダウンロード
- ぜんぶコンカチネート
- ClaudeCodeに「変更履歴くっきりのドキュメントにまとめて」と読ませる
以上。
変更経緯がくっきりしたドキュメントが出てくる。人間向けの最新仕様書も、同じ流れで問題なく生成できる。
「ドキュメント書く時間ない」と言ってた人、イシューちゃんと切ってたら、もうそれがドキュメントだった。
AIパワーを実感できるワークフローの一つだ。
質問来てた
「細かいUIの調整までいちいちイシュー切るの？」
気持ちはわかる。ボタンの色変えるたびにイシュー切るのか、と。面倒くさい感じがするのはわかる。
ただ俺なら切る。
UIの調整イシュー切って、コメントで「ここをこう変えた」「やっぱり戻した」「こっちの理由はこれ」と作業記録を積み上げながら進める。PRで締める。
なぜか。後で振り返るとき、圧倒的に楽だからだ。
「なんでこのボタンこの色なんだっけ」が、イシュー追えばわかる。あの迷走した30分の判断が、ちゃんとコンテキストとして残ってる。
それが開発者の本能だからだ。
「管理コスト」という幻想
「イシュー切るのがコストだ」という感覚、わかる。
でも考えてみてほしい。
イシュー切らないほうが、後でコストがかかる。「あのときなんでこうしたんだっけ」のために、過去のチャットを掘る。チームメンバーに聞く。最悪、コードを読んで推測する。
それが本当のコストだ。
イシューは先払いのコストじゃない。後払いコストの先送り拒否だ。
スタイルを整えるのに時間はかかった。
でも慣れたら戻れない。そういう感じになった。
#AI #バイブコーディング
Discussion