こんにちは、ヤプリでサーバーサイドエンジニアをしている鬼木です。
弊社では MCP（Model Context Protocol）経由で社内ドキュメントや Database の情報にアクセス可能な環境が整っています。その中で、直近それらを使ってある新機能開発の技術仕様書を作成したので、今回はそのやり方について紹介したいと思います。
紹介する手法自体は決して画期的なものではありませんが、最初に簡単なプロンプトを書き始めるところから完成までのリアルな AI ツールの使い方について共有できればと思い、この記事を書きました。
技術仕様書作成の課題
弊社では新規開発が行われる度に技術仕様書を作成しています。フォーマットは決まっていませんが、その仕様やシステムについての知識がない人でも理解できるドキュメントを作ることを目的に、以下のような項目について書くことが多いです。
- 新規開発した機能のインフラ構成
- DB のテーブル定義
- 処理の流れがわかりやすいような説明や補足（UI 上に表示されているこのデータは XX テーブルのレコードにあたる、など）
従来、これらのドキュメント作成には相当な時間がかかっていました。手動での ER 図の作成、情報の整理、その後の書き起こしなど、エンジニアにとって重要ではあるものの時間のかかる作業でした。
MCP 活用によるアプローチ
今回の技術仕様書作成では、MCP 経由で以下のリソースにアクセス可能でした。
機能の仕様
仕様書: Confluence のリンクを Atlassian MCP で取得（弊社では社内ドキュメントを Confluence で管理しています）
UI 情報: ヤプリでは Figma を使って管理していますが、今回は 2 つの画像のみで良かったため、エクスポートしてローカルに配置し、Claude Code が参照できるようにしました（多くの情報が必要になる場合は Figma MCP の使用も有用だと思います）
DB 情報
Amazon Aurora MySQL MCP Serverで今回の開発に関わるDBのテーブル情報にアクセスできる状態でした。こちらはDatabaseのテーブルスキーマ、レコードにもアクセス可能なので技術仕様書作成だけでなく現状の挙動調査などの場面でも活用することができるため、各MCPの中でも特に便利だと感じています。詳しくは以前弊社の SRE チームのエンジニアが書いたこちらのテックブログを参照してください。
実際の進め方
機能の仕様と DB の構造を Claude Code にインプットしてから、以下のような流れで進めました。
初期プロンプトの作成
最初は思いつくままに以下のようなプロンプトを書きました、この記事では具体的な名称・詳細は伏せていますが、実際に書いたものにかなり近い内容になっています。特別なことはしていませんが、よく言われている事前知識無しでもやりたいことや前提を理解できる内容でプロンプトを書いています（このあたりのポイントをしっかり抑えておくとコーディングでも良いアウトプットが出る感触があります）。
# 概要
現在ある新機能開発を行なっている。この開発におけるデータベースを中心としたシステム概要についてのドキュメントを作りたい。
ドキュメントは Confluence 上に作るが、Atlassian MCP で Confluence に接続することができる。
### 仕様書
{社内 Confluence の仕様書ページ URL}（Atlassian MCP 経由でアクセス可能）
メインの UI は documents/image.md で参照可能。documents/image.md 内のタイムライン表示の詳細は documents/image_detail.md で参照可能
## データ
UI 上に表示されるデータは、以下のテーブル構造に基づいている：
- primary_events テーブル: メインイベントの履歴データ
- secondary_events テーブル: サブイベントの履歴。様々なアクション（作成、自動生成、復元、削除など）がタイムライン上に表示される。今回の新機能開発用に新しく追加したテーブル
- data_storage テーブル: 実際のデータを格納。上記のイベントテーブルと一対多の関係。メモ情報なども保持している。削除後もメモ表示が必要なため、ハードデリートからソフトデリートに変更
これらのテーブルは XXX DB にあり、XXX MCP 経由で参照可能。
## 進め方
まずは上記についての情報を取得し、理解してください。
その後、Confluence の{ページ URL}のページにドキュメントを作成してください（Atlassian MCP で接続可能）
### ドキュメントのポイント
- エンジニアが UI 上の表示が DB のどのレコードに紐づいてるかわかるようにすること
- 今回追加したテーブルやカラムの設計背景がわかるようにすること
- テーブルの関連性がわかるような ER 図があると良い。スキーマ定義もあればなお分かりやすい
まずは計画を立ててください。
プロンプトの改善
上記は思いつくまま雑多に書いたものだったので、以下のプロンプトで整形させました。このように頭の中で考えているポイントを雑に書き起こしてから AI に投げる前に AI 自身に整形させることをよく行なっています。
documents/description.mdはこれからClaude Codeに指示する内容を書いたものです。よりClaude Codeに伝わりやすいような書き方、フォーマットに修正してください
その結果、以下のような Markdown に修正されました。
# タスク: データベース中心システム概要ドキュメント作成
## 目的
新機能開発におけるデータベース中心のシステム概要ドキュメントを Confluence に作成する。
## 参考資料
### 仕様書
- メイン仕様: {社内 Confluence ページの URL}（Atlassian MCP 経由でアクセス）
- UI 参考: ローカルファイル
- 詳細 UI 情報: ローカルファイル
## データベース構造
### 対象データベース
- **データベース**: XXX DB
- **アクセス方法**: XXX MCP 接続
### 主要テーブル
#### 1. `primary_events`
- **用途**: メインイベント履歴
- **更新タイミング**: 主要操作実行時に INSERT
#### 2. `secondary_events` (新規追加)
- **用途**: サブイベント履歴
- **アクションの種類**:
- `create_manual`: 手動作成
- `create_auto`: 自動生成
- `restore`: 復元
- `delete`: 削除
- **更新タイミング**: 各種操作実行時にレコード追加
#### 3. `data_storage`
- **用途**: 実際のデータ格納
- **関係**: `secondary_events`と一対多
- **特記事項**:
- メモデータを保持
- ハードデリート → ソフトデリートに変更（削除後もメモ表示のため）
## 実行手順
### Step 1: データ調査・理解
1. 社内 MCP 接続でデータベースアクセス
2. 上記 3 テーブルのスキーマ確認
3. テーブル間の関係性把握
4. UI 参考資料確認
### Step 2: ドキュメント作成
- **作成先**: 指定された Confluence ページ
- **アクセス方法**: Atlassian MCP
### Step 3: ドキュメント要件
以下の要素を含むドキュメントを作成:
1. **UI-DB 対応表**
- UI 上の表示項目と DB レコードの対応関係を明記
2. **テーブル設計背景**
- 新規追加したテーブル・カラムの設計理由を説明
- ソフトデリート変更の背景
3. **ER 図・スキーマ定義**
- テーブル関係性の可視化
- 各テーブルのスキーマ定義
## 次のアクション
まず計画立案後、上記手順に従って実行してください。
実際の成果
上記の整形後のドキュメントに従って作業を実行してくださいという形で Claude Code に指示し、技術仕様書が Atlassian MCP 経由で Confluence 上に作成されました。 以下は最終的に作られたドキュメントの一部です、DB のテーブル定義や背景、データフローについても記載してくれています。
Claude Code によるアウトプット後、画像の追加や不要部分の削除といった細かい部分の手動での修正は必要でしたが、作業開始から 1 時間未満で今まで作っていたものと同等のクオリティの技術仕様書を書き終えることができました。
修正する箇所は少なくはないですが、アクセスする情報が間違ってなければ間違った情報をアウトプットすることは少ないため、不要項目の削除や言い回しの修正など体裁に関わる変更が中心で１から書くよりも工数はかなり削減されている印象です。
まとめ
Claude Code と MCP を利用したドキュメント作成についての共有でした。紹介した手法自体は決して画期的なものではありませんが、実際のプロンプト作成から完成までの具体的なプロセスを共有することで、同じようなことを行いたい方の参考になればと思い記事にしました。
また今回の技術仕様書作成を通して、AI エージェントが社内の様々な情報にアクセスできる環境が整っていることで使い方を理解している人はどんどんパフォーマンスを上げることができるため、組織での AI ツール・MCP 等の環境整備の重要性を改めて感じました（弊社でこのような環境を整備してくださっている SRE チームや IT チームの方々に感謝です！）
ヤプリでは、このような AI 等の技術を活用しながら開発を進めるエンジニアを募集しています。興味のある方はぜひご連絡ください！
