AIのお世話が辛いのでUsecase Design Docを書く¶
チェック¶
- [ ] 本文を確認した
- [ ] 概要を確認した
- [ ] タグを確認した
- [ ]
inbox/直下へ移行した
概要¶
CADDi Quoteチームで、AIエージェントに実装を委譲するためのUsecase Design Docを整備した話。 都度プロンプトを書く負担、エージェント完了までの面倒見、複数並列実行の認知負荷を、設計ドキュメントとタスク分割で軽減している。 結果としてPR作成・レビューの流れが整理され、マージできるPR数が増えた一方で、設計書の誤り増幅や設計レビューのボトルネック化も課題として残っている。
本文¶
この記事の背景は、CADDi Quoteチームでは全員がAIエージェントを使って実装からPR作成まで行うようになり、個人の実装アウトプットが増えた一方で、AIを動かすための「お世話」が増えたこと。筆者自身を含め、まったく自分でコードを書かなくなったメンバーもいる。Usecase Design Docと関連施策によって、このお世話負荷を下げ、1日にマージできるPR数が2倍になった。
辛かったことは大きく3つ。
- 毎回詳細なプロンプトを書くのが辛い
- AIエージェントのタスク完了まで面倒を見るのが辛い
- 複数のAI実装を並列で走らせるのが辛い
曖昧に「これを実装して」と伝えるだけでは、期待するPRにならない。そのため、1PRを作るたびに背景、仕様、制約、実装方針、テスト観点を細かく説明する必要があった。AIしか読まない長い指示文を書くこと自体に虚無感があり、スキルやツールで多少軽減しても、その都度正確な指示を出す負担は残る。
Claude CodeのようなAIエージェントはかなり賢くなっているが、プラン確認、ツール利用許可、PR作成後の修正、セッションのクリアなど、人間の介入が必要な場面がある。直列で1件ずつ扱っているうちは大きな問題ではないが、1人で5つ以上のタスクをAIエージェントと並列実装するようになると認知負荷が跳ね上がる。Git Worktree、開発サーバーのポート競合、mainブランチの取り込み忘れによるコンフリクトなども発生する。
解決方針は、プロンプトを毎回書くのではなく、実装に必要な情報をUsecase Design Docとして先に作り込むこと。AIが読む前提で、ユースケース単位の設計、影響範囲、I/O、実装方針、テスト観点、既存コードとの接続を明示する。
運用イメージは次のような流れ。
1. 人間が要求や背景を整理する
2. Usecase Design Docを作る
3. そのDocをもとにタスクを分割する
4. 分割したタスクをAIエージェントへ渡す
5. AIが実装・テスト・PR作成を進める
6. 人間は設計判断とレビューに集中する
Usecase Design Docは、単なる仕様書ではなく、AIが実装を進めるための入力として機能する。人間がその場で口頭補足していた暗黙知を、あらかじめ構造化することで、エージェントごとの差分や実行中の手戻りを減らす。
Usecase Design Docには、ユースケースシナリオに閉じた設計を書く。含める項目は次の通り。
- サマリー: アクター、操作対象、操作内容
- 関連テーブルのCRUD表
- シーケンス図: トランザクション境界を含める
- 主要なドメインエンティティのインターフェース: 型定義、ファクトリメソッド
- 関連するAPIインターフェース: API仕様書から必要箇所を抜粋
- 既存コードへの変更箇所: レイヤーごと
- 実装状況チェックリスト: 集約単位、レイヤー単位
架空ユースケースの粒度は次のようなもの。
# EX-a1: ユーザーはお気に入り商品をブックマークする
## サマリー
- ログインユーザーが商品に対して、ブックマーク（お気に入り登録）を行う
## 関連のテーブル
| テーブル | 操作 | 操作内容 |
| :--- | :---: | :--- |
| Product | R | ブックマーク対象の商品が存在することを確認する |
| Bookmark | CR | ブックマークの存在確認（R）、新規作成（C） |
| BookmarkCount | U | 商品のブックマーク数を +1 更新する |
シーケンス図では、正常系だけでなくエラーとトランザクション境界を明示する。
sequenceDiagram
autonumber
actor User as ログインユーザー
participant API as Product API<br/>[REST]
participant DB as App DB<br/>[PostgreSQL]
User->>API: POST /products/{productId}/bookmarks
API->>DB: 商品の存在確認
alt 商品が存在しない
API-->>User: 404 Not Found
else 商品が存在する
API->>DB: 既存ブックマークの確認
alt 既にブックマーク済み
API-->>User: 409 Conflict
else 未ブックマーク
rect rgba(100, 150, 255, 0.15)
Note over API,DB: トランザクション
API->>DB: Bookmarkを保存
API->>DB: BookmarkCountを+1更新
end
API-->>User: 201 Created
end
end
ドメインエンティティのインターフェースには、実際の設計では型定義やファクトリメソッドを書く。例としては、BookmarkId、UserId、ProductId を持つ Bookmark 型、Bookmark.create(...) のような生成関数を明示する。APIインターフェースでは、パスパラメータ、リクエストボディ、レスポンスをテーブル形式で書く。既存コード変更では、Domain、Usecase/Application、Infrastructure、Presentationのようなレイヤーごとに、変更対象ファイルと変更内容を列挙する。
実装状況はチェックリストで管理する。
タスク分割では、AIエージェントが実装できる粒度まで落とす。大きな要求をそのまま渡すのではなく、独立して実装・検証できる単位に切る。これにより、複数エージェントを並列で走らせても、人間が追跡しやすくなる。
分割軸は次の3つ。
- レイヤー単位: Presentation / Domain / Application
- DDDの集約単位
- 同期・非同期の処理単位
各PRは200〜300行の変更に収まることを目安にする。変更範囲が限定されるため、レビュアーが把握すべき知識もレイヤーや集約の境界内に収まる。
AIエージェントへの委譲は次の流れ。
1. Usecase Design Docの実装状況欄から、未実装項目の一番上を実施タスクにする
2. Devin Searchで関連コード・ドキュメントを収集する
3. Devinにタスク定義と関連コードを渡してPR作成まで実行させる
4. CI上のDevin Reviewで自動レビューする
設計ドキュメントが十分に詳細なら、この流れは人間の逐次介入なしで進む。昼前にタスクを投入し、午後にできたPRをレビューする、という非同期サイクルが成立する。
成果として、開発速度が向上し、PRレビューの認知負荷も軽くなった。レビュー時に「何を作るべきか」から確認するのではなく、Usecase Design Docに対して実装が合っているかを確認できるため、レビューの軸が安定する。
開発速度の向上は、AIエージェントが人間待ちせず進められるようになったこと、アウトプットの質が上がり手戻りが減ったこと、エージェントへの直接的なマネジメントから、セッション横断で効く環境整備へ時間を使えるようになったことによる。並列数も固定上限ではなく、その日のPRレビューに割ける時間から逆算して決めるようになった。
一方で課題もある。設計書に細かい誤りがあると、AIがその誤りを増幅して実装してしまう。また、実装のボトルネックが減るほど、設計とPRレビューが新しいボトルネックになる。つまりAI実装の速度を上げるほど、人間側の設計品質とレビュー能力がより重要になる。
設計書の細かい誤りは、インターフェース設計の小さなズレとして入ると、実装フェーズで大きなズレに増幅される。開発者が伴走していれば途中で気づけた誤りも、PR作成後に初めて表面化する。そのため、設計ドキュメント自体のレビュー精度を上げるか、実装途中でフィードバックを得る仕組みが必要になる。
結論として、実装時にAIエージェントへ指示内容を考えるより、設計時点で詳細な実装までイメージできるドキュメントを作る方が効率がよい。AI活用の成熟によりツール側の課題は軽くなる可能性があるが、設計はまだ人間が考えるべき領域が大きい。チームで試すなら、最小構成としてUsecase Design Docの整備から始めるのがよい。
要点¶
- AI実装の負荷は「コードを書く負荷」から「AIに正確に渡す負荷」へ移る。
- Usecase Design Docは、AIに渡すための構造化された実装入力になる。
- 大きな要求は、AIが独立して実装できる粒度へ分割する。
- レビューは、設計Docと実装の差分確認に寄せると認知負荷が下がる。
- 設計書の誤りはAIによって増幅されるため、設計レビューが重要になる。
- AIで実装速度を上げるほど、人間の設計・判断・レビューがボトルネック化する。