事例3:DB定義・用語集を元にAPI設計から実装まで進める¶
課題:AIとの設計議論がチャット履歴に消え、設計書は実装と乖離する¶
設計書を先に書いても、実装が設計書通りに進むとは限らず、初期の設計書と最終的な実装コードは乖離しがちです。AIに設計を相談しても、その設計内容はAIとのチャット履歴の彼方に消えて、後からチームの誰も参照できない──。
TRACERY MCPを使うと、AIが作ったAPI設計をTRACERYのページとして保存できます。レビュー・修正を経て、その設計書を根拠に実装まで一貫して進められます。
結果:設計・ドキュメント・実装が乖離しない¶
従来 |
MCP活用 |
|
|---|---|---|
進め方 |
設計・実装・ドキュメント作成を個別に実施。設計変更のたびに手戻り |
人間は指示とレビューのみ。AIが参照・設計・修正・実装を一連で実施 |
設計書の鮮度 |
実装が進むと放置されがち |
レビュー修正のたびにAIがTRACERY上の設計書を更新 |
AIが作った設計 |
AIとのチャットに埋もれ、後から参照できない |
TRACERYのページとしてチームの設計資産に |
AIが作成したAPI設計書は、TRACERYの「API設計」カテゴリーにページとして保存されます。
やっていること¶
AIエージェントがTRACERY上のDB定義・用語集をコンテキストとして参照し、API設計を作成してTRACERYに保存します。レビューを経て承認された設計書に従って、そのまま実装します。
%%{init: {"theme": "neutral"}}%%
flowchart LR
MCP[TRACERY MCP<br>DB定義・用語集・要件] -->|参照| Agent[AIエージェント]
Agent -->|設計書を保存| MCP
Agent -->|実装| Code[実装コード]
User((利用者)) -->|要件・レビュー| Agent
実際の手順¶
1. API設計を作らせる¶
プロンプト例
「書籍お気に入り機能」の要件ページ・DB定義・用語集を読んで、必要なAPI設計を作成してください。
- 設計は「API設計」カテゴリーに保存してください。
- エンドポイント、リクエスト/レスポンスの型、エラーケースを含めてください。
- 用語集に登録されている用語を使用してください。
用語集を参照させることで、APIのフィールド名やエラーメッセージの用語がチームの定義と揃います。
2. 設計をレビューして修正させる¶
保存された設計をTRACERY上で確認し、修正コメントをAIに伝えます。承認できるまでこのサイクルを繰り返します。
プロンプト例
保存したAPI設計を確認してください。
以下の点を修正してください。
- お気に入り登録の上限数チェックを追加してください。
- エラーレスポンスの形式を他のAPIと統一してください。
修正後、設計ページを更新してください。
AI応答例(イメージ)
設計を修正しました。
POST /api/books/{book_id}/favorite/に上限数チェック(1ユーザー100件)のエラーケースFAVORITE_LIMIT_EXCEEDEDを追加エラーレスポンスを共通形式
{"code": ..., "message": ...}に統一
#update_page で「書籍お気に入り機能 - API設計」ページを更新しました。
3. 承認した設計書に従って実装させる¶
プロンプト例
保存した「書籍お気に入り機能」のAPI設計に従って、実装してください。
- DB定義に合わせたモデル操作を行ってください。
- 設計書に記載したエラーケースを漏れなく実装してください。
設計書が明確なため、AIが意図と異なる実装をするリスクを減らせます。実装後は通常通りコードレビューしてください。
コツと注意点¶
設計は必ずページに保存させる。チャット上の回答で満足すると、設計の意図や試行錯誤の経緯が残りません。
要件の解釈は人間が確認する。DB定義・用語集を参照するため一貫性は高いですが、要件の読み違いは設計レビューで拾う前提です。
前提として、TRACERY上にDB定義・用語集と、対象機能の要件をまとめたページ(ページ機能で作成)が整備されている必要があります。→ 事例2:DB定義書の最新化、事例1:用語集の整備
開発サイクルでの位置づけ¶
%%{init: {"theme": "neutral"}}%%
flowchart LR
A[事例1:用語集の整備] --> C[事例3:API設計・実装]:::current
B[事例2:DB定義書の最新化] --> C
C --> D[事例4:運用手順書の整備]
D -.->|知見の還流| A
D -.-> B
classDef current fill:#4a6fa5,color:#fff,stroke:#4a6fa5
項目 |
内容 |
|---|---|
受け取るもの |
事例1の用語集(チームの語彙)と事例2のDB定義(データ構造・制約を付けた理由)。AIはこれらをMCP経由で参照して設計する |
この事例で作る資産 |
TRACERY上のAPI設計書(エンドポイント・型・エラーケース)と、それに従った実装コード |
次の事例への効き方 |
設計書がTRACERYに蓄積されるため、事例4(運用手順書)やその後の機能追加でAIが「既存APIの設計方針」を参照できる。新メンバーやビジネスオーナーも同じ設計書を見られる |
前段の整備度がそのまま設計品質に響く事例です。用語集・DB定義が整っているほど、指示が短くても一貫した設計が出てきます。
次のページへ → 事例4:過去Issueから運用手順書を作る
詳細情報¶
使用MCPツール・処理フロー・実測環境
使用したTRACERY MCPツール
#get_page: 要件・DB定義・用語集などのページを参照。設計時のコンテキストとして利用#get_databases: DB定義を取得。設計時のコンテキストとして参照#get_terms: 用語集の一覧を取得。設計時に用語を統一するために参照#create_page/#update_page: API設計書の作成・更新
処理フロー
%%{init: {"theme": "neutral"}}%%
sequenceDiagram
Actor User as 利用者
participant Agent as AIエージェント
participant MCP as TRACERY MCP
participant Docs as TRACERYの資産<br>(DB定義・用語集・設計書)
Note over User,Docs: 設計
User->>Agent: 要件・指示(プロンプト)
Agent->>MCP: 既存情報の取得(参照)
MCP->>Docs: DB定義・用語集を取得
Docs-->>MCP: 既存定義
MCP-->>Agent: 既存定義
Agent->>MCP: 設計内容の保存(保存)
MCP->>Docs: 設計書を保存
Docs-->>MCP: 保存完了
MCP-->>Agent: 保存完了
Agent-->>User: 設計完了の報告
Note over User,Docs: レビュー
loop 設計レビュー
User->>Agent: レビュー・修正コメント
Agent->>MCP: 設計内容の修正(保存)
MCP->>Docs: 設計書を更新
Docs-->>MCP: 更新完了
MCP-->>Agent: 更新完了
Agent-->>User: 修正完了の報告
end
Note over User,Docs: 実装
User->>Agent: 実装指示(プロンプト)
Agent->>Agent: 設計を元に実装
Agent-->>User: 実装コード
User->>Agent: レビュー結果・修正指示
Agent-->>User: 修正済みの実装コード
実測環境
利用シーン: 新規プロジェクトの立ち上げ期(API設計・実装を一連で実施)
VSCode 1.109 / GitHub Copilot Agent / Claude Sonnet 4.6
TRACERY MCP