「なぜこう実装したか」に答えられるリポジトリを作る ── コーディングエージェントと仕様書を同居させるPythonプロジェクト設計
「この仕様、なぜこうなっているんですか？」──地方自治体を顧客とする私たちのシステムでは、こうした問い合わせが後から届くことが珍しくありません。以前は、答えるためにコードを読み直し、それでも「なぜ」の部分は担当者の記憶に頼るしかありませんでした。
根本的な問題は、設計の判断がコードにもドキュメントにも残らず、Gitリポジトリの外に散らばっていたことです。コーディングエージェントが実装の実務を担うようになってもこの構造は変わらず、エージェントへの指示はチャットで流れ、判断の根拠は他の開発者にもエージェントの別セッションにも引き継がれません。「なんとなく動いているが、なぜそうなっているかわからないコード」が増え続けました。
そこで導入したのが「ドキュメントベース開発」です。要求仕様書（何をしたいか・なぜ必要か）から仕様を抽出し、システム仕様書（最新の実装仕様）として整理します。エージェントへの指示を両仕様書に統一し、一過性と恒久の二層をバージョン管理します。PRマージまでの協業ワークフローを定義し、役割分担と文書追加の判断基準を明示しています。
結果として、エージェントとの実装段階のやり取りが減り、問い合わせへの回答が担当者の記憶に依存しなくなりました。
本発表では、医療データ分析というドメイン特性からPythonを採用した3プロダクト（予防医療向けシステム）とTerraform/TerragruntによるIaCに、このアプローチを横断展開した実践例を紹介します。要求仕様書の書き方、システム仕様書への整理方法、コーディングエージェントとの協業ワークフロー設計まで、具体的なドキュメント構造とともに解説します。「設計の根拠が残らない」課題を感じているチームに、明日から自分のリポジトリに持ち込める仕組みを持ち帰っていただける内容を目指します。
このトピックに関するあなた自身の経験を教えてください
SRE／テックリードとして、Pythonによる医療データ分析システムの開発・運用を担当しています。顧客はほぼすべて地方自治体であり、各自治体からシステムのカスタマイズ可否や仕様に関する問い合わせが多数届くほか、コーディングエージェントを使う際も実装判断の経緯が残らないという課題がありました。そこで要求仕様書とシステム仕様書をGitリポジトリで管理するドキュメントベース開発の仕組みを自ら設計・構築しました。
2026年3月より体系化し、現在は開発者6名のチームでPythonアプリ3プロダクトとIaCリポジトリで活用されています。仕組みの設計から、ドキュメントの粒度判断、チームへの定着まで、一連の試行錯誤を実践者として話せます。SREとしてPythonアプリとTerraformインフラの両方を担当しているため、異なる技術スタックをまたいだドキュメント基盤の横断展開という観点からも語れます。
この発表を通じて、参加者とどんな議論が可能ですか？
- 「コーディングエージェントに適した仕様書とはどのようなものか」 ──どう書けばエージェントが迷わず実装できるか
- 「変化し続ける仕様とドキュメント管理の両立」 ──要件が頻繁に変わる環境で、どの文書を更新し、どれは更新しなくていいかをどう判断するか
- 「ドキュメントの粒度問題」 ──細かすぎると維持コストが上がり、粗すぎるとエージェントが迷う。発表では「書きすぎた失敗例」も交えながら、その境界線を考えるヒントを提供できればと思っています
- 「外部顧客からの問い合わせとドキュメント管理の接点」 ──自治体のような外部顧客から仕様について繰り返し届く問い合わせに、担当者の記憶に頼らず答えるにはどうするか。受託・規制業界・マルチテナントSaaSなど、似た環境でのやり方
- 「PythonアプリとIaCで同じドキュメント基盤を共有する際の壁」 ──言語・ツールが違うと仕様書の粒度や書き方も変わります。SREとして両方を担当する立場から共通化できた部分・できなかった部分を発表で共有するので、同様の経験を持つ方のフィードバックがあると嬉しいです
株式会社キャンサースキャンでSRE / テックリードとして、医療データ分析システムの開発・運用を担当しています。
Webアプリケーションの開発でインフラを中心に自社プロダクトの開発経験を積んできました。
インフラとアプリケーションの橋渡しを行うことで開発生産性を向上させる技術を得意としています。
- X: @ara_shell
- GitHub: @arapower