理系学生日記

おまえはいつまで学生気分なのか

Claude Code GitHub Actionsから考える生成AI駆動開発とドキュメント管理の妄想

development process

はじめに

もし、すべての開発ドキュメントや成果物が「リポジトリ」という一つの場所に集約され、AIや自動化ツールがそれらを自在に読み書きできたら――。そんな“Single Source of Truth（SSoT）”な世界を想像しても、結局のところ要件定義や設計ドキュメントはOffice文書だったりGoogle Docsだったりして、AIがうまく扱いにくい。 全部リポジトリで管理できたとして、AIと自動化が前提となる時代のドキュメント依存関係管理はどうすれば良いんでしょうか。

この辺り、@qumaiuさんや@fadysan_rh投稿されているように、生成AIをリポジトリと統合すると何ができるようになるかという話と地続きです。

SSoTとしてのリポジトリ運用の思考実験

たとえばすべての開発成果物（要件定義書・設計書・コード・テスト仕様書など）をMarkdownみたいなドキュメントでリポジトリにまとめて「Single Source of Truth（SSoT）」にするとどうなるか？生成AI（Claude Codeなど）とGitHub Actionsを組み合わせて、Pull RequestやIssueコメントをきっかけにAIが成果物を自動で作ってくれる世界。

もちろん、AIが作ったドキュメントをそのまま使うのは怖いので、必ずPull Request経由で人間がレビュー・承認する運用が前提です。全部の履歴や議論、AIのアウトプットもリポジトリで一元管理できるので、トレーサビリティもバッチリ。……と、妄想は膨らみますが、現実はどうでしょう？

無限コンテキスト長前提での管理手法

現状はコンテキスト長が限られるし、Lost in the middleやNeedle in a Haystackみたいな課題もあります。でも、将来的には無限に近いコンテキスト長が実現するかもしれません。そうなったら、ドキュメントの依存関係をどう管理するのが理想的でしょうか？

ディレクトリ構造による階層管理

ドキュメントを論理的なディレクトリ階層で整理したら、AIも全体像をつかみやすいんじゃないか？依存関係もパスでなんとなく表現できるし、「/requirements/」→「/design/」→「/test/」みたいな流れが直感的に伝わる気がします。まぁもう少しサブディレクトリは分かれるんだろうけど。

そしたら、雑に言えば $(cat /requirements/*.md) から必要なI/F一覧を洗いだせ。結果は /design/if/ に OpenAPI.yaml として出力しろ みたいなのを Claude Codeに与えればいいんだよな。 ただ、情報整理の歴史を振り返ると、単純な階層型だけではうまくいかないことも多い。社会もシステムも、そんなに単純じゃないですし。

明示的なリンク・メタデータ管理

ZettelkastenやObsidianみたいに、[[リンク]]や#タグで依存や関連を明示したらどうだろう？依存関係グラフやトレーサビリティマトリクスをMarkdownで書いて、AIも人間も参照しやすくする。私もFoamで「#要件」「#設計」みたいなタグを付けて横断検索したら、意外なつながりや抜けに気づけたことがありました。

グラフDBとかそういうのを使うのもアリだけど、あまり複雑化させたくない。AIがMarkdownを読み取って、リンクやタグをたどって依存関係を把握できるようにするのが理想。

ディレクトリ＋リンクのハイブリッド運用

大まかな分類はディレクトリ、細かな依存や横断的な関係はリンクやタグで補う。AIが両方の情報をうまく解釈できたら、柔軟性と可読性のバランスが取れるかも。タグ書いておけば、GitHub Copilot agent modeでも勝手にgrepっぽいことやってくれるし。それを instruction で明示的に指示しておけば良さそう。

現実的な課題

  • いくらAIが全部読めるようになっても、「人間の可読性」や「レビュー・ナレッジ共有のしやすさ」はやっぱり大事。AIが賢くなっても、人が追えなきゃ意味がないですよね。
  • 上流ドキュメントが曖昧だったり非構造的だったりすると、AIによる生成精度にも限界がある。一方で、ドキュメントをAIの解釈容易性に全振りすると、人間の解釈容易性が損なわれる。そのバランス重要。たとえば、AI向けに細かく分割しすぎた結果、人間が全体像を把握しづらくなった…みたいなことも起きがちです。
  • AIが出した答えの根拠や説明責任をどう担保するか。レビュー時に「なぜこうなった？」をAIから引き出す仕組みがあればいいのかな。あとは承認する人間が責任を負え。ただ、依存関係が複雑になりすぎると、AIの出力根拠やトレーサビリティの説明が難しくなるリスクもあがる。

おわりに

今回は「もし生成AIと自動化が前提だったら？」という思考実験として、ドキュメント依存関係管理の未来を妄想してみました。技術の進化はワクワクしますし、一人だったらすぐに試せそうですね。最低限のツールはほぼ出揃っている。