SDDの運用にめげずに向き合った話

■ イベント
Sansan Tech Talk @関西 vol.6～AIエージェント実践～
https://sansan.connpass.com/event/404019/

■登壇概要
タイトル：SDDの運用にめげずに向き合った話
登壇者：技術本部 Data Intelligence Engineering Unit Data Intelligence Group 仲野 将馬

■ 技術本部 採用情報
https://media.sansan-engineering.com

Transcript

1. Sansan技術本部 SDDの運⽤にめげずに向き合った話 Sansan株式会社 技術本部 Data Intelligence Engineering Unit Data Intelligence Group 27卒 仲野 将⾺
2. 仲野 将⾺（Shoma Nakano） 技術本部 Data Intelligence Unit Data Intelligence Group ⽴命館⼤学情報理⼯学部4回⽣。 2025年8⽉よりSansan株式会社にインターンとして参画。 2027年4⽉に新卒社員として⼊社予定。 Sansan Data Intelligence の開発に携わっている。
3. Spec Driven Development 運⽤の背景 新規プロダクトということでAIを前提とした開発環境にしたい - Sansan Data Intelligence は新規プロダクトであり、去年の春頃から本格的な開発が始まっ た。 - その頃 Cline や Claude Code がで始めた時期であり、開発⽣産性を上げるためにAIを前提 とした開発環境の整備を⽬指した。 その中でDX Guild が AI を⽤いた DX を設計開発していて、その⼀員として向き合ってきた。 そして「仕様を書けば、AI がテスト済みの機能を作り上げる開発ワークフロー」を⽬指し、 Spec Driven Development (SDD)の運⽤を開始。 2
4. Spec Driven Development 以下の構成を1つのspec（仕様）単位とし、リポジトリ内で管理する specの構成（KiroやSpec Kit などのspec driven 開発ツールを参考） 1. requirements.md: 要求仕様 - 実装すべき機能や変更の「What (何を)」を明確にする 2. design.md: 設計ドキュメント - AI が実装‧レビューの際に参照する構造ドキュメントとして、requirements.md で定義した要求をど のように実装するか (How) を⽰す 3. tasks.md: タスクリスト - design.md で定義した設計を実装可能な PR 単位のタスクに分解する 3
5. 実際にチーム全体で運⽤してみた 以下のskillを作成し、共有。数ヶ⽉運⽤してみた - spec-requirements-designer: requirements.md を対話的に作成‧改訂 - spec-sdd-design-designer: requirements.md から design.md を対話的 に作成‧改訂 - spec-task-designer: design.md から tasks.md を設計‧作成する - spec-sdd-executor: specに従い、taskに基づいて実装を⾏う 4
6. 実際のspec design.md: 集約を⼀つ追加するdesignの例（集約の設計のみを抜粋） 5
7. 実際にチーム全体で運⽤してみた good アンケートを実施 more - 実装時にAIのブレは少なくなった - spec のレビュー負荷が⾼い - スコープが明確になった - 意思決定と実装詳細が⼊り混じっており、 - ある時点の設計意図が残るのは良い ⼈間にとっては読むコストが⾼い - AI 向けのドキュメントと⼈間向けのドキュ メントとしての2つの性質が混ざってし まっている - ⼈間のレビュー観点が曖昧で定まっていな い 6
8. 実際にチーム全体で運⽤してみた アンケートを実施 ※ 1から5の5段階評価（数字が⼤きいほど⾼評価） また、アンケートによってspecのレビューに1~2時間かかってしまっていることが分かった 7
9. specによる実装の精度よりも AIが出⼒する⽂章に問題があった
10. 改善をするために⽴てた⽅針 1. ⼈間が必要となるドキュメントと AI が必要となるドキュメントを分ける AI 向け: spec、⼈間向け: ADR / ユビキタス⾔語 - 分離することで各ドキュメントの責務が明確になり、レビューもやりやすくなる 2. 実装‧レビューに必要となる design doc 以外は GitHub 上に置かない運⽤とする Git 上に AI / ⼈間両⽅にとってのノイズをできる限り残さないようにする - 実装進捗などが該当する 9
11. 取り組んだこと spec の各ファイルについて 1. requirements.md → Githubから廃⽌。必要な場合はIssue化 - 実装時に AI も⼈間もほぼ参照せず、要件はNotionでPBIにまとめられているので参照可能 2. design.md → 継続‧ただし役割/構成を再定義 - 主に AI が「実装‧レビュー⽤途で使⽤するドキュメント」 として位置づけ - フロー図‧コマンド/クエリ⼀覧‧DB 設計など 構造的な情報のみに絞り、⽂章量を削減 - 設計意図‧トレードオフ‧意思決定は ADR に移管 3. tasks.md → GitHub から完全廃⽌ - GitHub との連携メリットが薄く、NotionやGithub Projectで管理できるため 10
12. 改善後のspec design.md: 集約を⼀つ追加するdesignの例（集約の設計のみを抜粋） 11
13. 改善後のspec ⽂字数で⽐べる （PBIごとにspecは作成するが、その粒度はバラバラで⽐較できないため、1集約あたりで算出） 改善前 改善後 1集約あたりの行数 119.2 行 77.9 行 1集約あたりの文字数 1,504 文字 1,306 文字 12
14. 取り組んだこと 他にも JA/EN の相互翻訳の対応 - 海外チームでも負荷なく作成できるように⽇本語での作成に限定せず、github actions でPR上で相互翻訳するように実装 AIが出⼒する⽂章を簡潔にさせる対応 - claude.mdに簡潔な表現をさせるような指⽰を追加 PR Description の改善 - ⽂章が冗⻑であったので”TL;DR”セクションを追加して読みやすく 13
15. 最近のアンケート結果 改善後、アンケートを実施（specのreviewのしやすさについて） ※ 1から5の5段階評価（数字が⼤きいほど⾼評価） [アンケートのコメント] - 冗⻑かつ、⼈間が読むべきところとAI が読むべきところが混在している - 実装の進⾏に合わせてドキュメントを有⽤な状態に保ち続けるのが困難 14
16. 最近のアンケート結果 改善後、アンケートを実施（実装の品質について） ※ 1から5の5段階評価（数字が⼤きいほど⾼評価） [アンケートのコメント] - 設計時の考慮漏れが発⽣した時のコストが⼤きい。 - 単体テストでは割と抜けているケースがありそう。 15
17. 最近のアンケート結果 その他コメント - オーナーですらdesing.mdに何が書いてあるのか把握し難い。 - 前例がある実装パターンの場合、design.md を頑張って書かなくても entity と data schema と既存実装をAIに渡したら、実装できるのでspec不要かもしれない。 - ⼈間が読み、合意し、後から意思決定を⾒返すためのものと、AIに対する指⽰⽂書を分 けて欲しい。 16
18. アンケート結果を受けて - AIで⽣成される⽂章の冗⻑さに関してはまだまだ改善の余地がある 現状のspecでは実際の実装PRよりも認知負荷が⾼いままになっている。 また、実装PRをほぼ No Look LGTM できていないのが現状で、review 時間が spec の作成を挟むこ とによって全体的に伸びてしまっており、効果を⼗分に発揮できていない。 - AIが出⼒する実装に関しては概ね問題はない ⼤きな問題を⽣んでいるわけではないが、⼈によるreviewを⼿放せていない。今後は動作確認が ネックになりそう。 17
19. まだまだ向き合わないといけないこと AIが読む⽤とされる⽂章をreviewしないでいいようにする - ⽂章が冗⻑になっており、⼈間が読むべき簡潔な⽂章とAIが実装時に読む⽂か混在して しまっているので改善したい。 SDDを取り⼊れたことでの開発スピードの実計測ができていない - 実際にSDDによってリードタイムが縮⼩されたのかを測れていないため、計測してどこ がボトルネックになっているのかを検証したい AIのtoken量を抑えた開発体験を⽬指す - コスト削減を考えられていなかったので無駄になってしまっている部分を削る 18