「なぜこう実装したか」に答えられるリポジトリを作る ── コーディングエージェントと仕様書を同居させるPythonプロジェクト設計

「この仕様、なぜこうなっているんですか？」──地方自治体を顧客とする私たちのシステムでは、こうした問い合わせが後から届くことが珍しくありません。以前は、答えるためにコードを読み直し、それでも「なぜ」の部分は担当者の記憶に頼るしかありませんでした。

根本的な問題は、設計の判断がコードにもドキュメントにも残らず、Gitリポジトリの外に散らばっていたことです。コーディングエージェントが実装の実務を担うようになってもこの構造は変わらず、エージェントへの指示はチャットで流れ、判断の根拠は他の開発者にもエージェントの別セッションにも引き継がれません。「なんとなく動いているが、なぜそうなっているかわからないコード」が増え続けました。

そこで導入したのが「ドキュメントベース開発」です。要求仕様書（何をしたいか・なぜ必要か）から仕様を抽出し、システム仕様書（最新の実装仕様）として整理します。エージェントへの指示を両仕様書に統一し、一過性と恒久の二層をバージョン管理します。PRマージまでの協業ワークフローを定義し、役割分担と文書追加の判断基準を明示しています。

結果として、エージェントとの実装段階のやり取りが減り、問い合わせへの回答が担当者の記憶に依存しなくなりました。

本発表では、医療データ分析というドメイン特性からPythonを採用した3プロダクト（予防医療向けシステム）とTerraform/TerragruntによるIaCに、このアプローチを横断展開した実践例を紹介します。要求仕様書の書き方、システム仕様書への整理方法、コーディングエージェントとの協業ワークフロー設計まで、具体的なドキュメント構造とともに解説します。「設計の根拠が残らない」課題を感じているチームに、明日から自分のリポジトリに持ち込める仕組みを持ち帰っていただける内容を目指します。