Uncategorized

AIエージェント分業ワークフロー【spec.md駆動開発】

YK
YK ・ Frontend

こんにちは、新卒フロントエンドのYKです。

趣味はテスラでのドライブとサウナです。
テスラの最新アプデでGrokがセンターディスプレイに搭載されて、「今日どこ行く？」と話しかけるとナビに入れてくれます。ランダムな行き先に向かうのが楽しすぎて、気づいたら知らないゴルフ場の駐車場で充電していました。
FSD（完全自動運転）のアプデを今か今かと待っています。♪

気づくと、移動も開発も「任せる相手」が増えていました。Cursor、Claude Code、Codex 次に来る何か。銘柄はころころ変わる。だから先に決めた方がいいのは、どのAIが一番強いか、ではなく、誰に何を任せるかだと思っています。

この記事に出てくるCursorやClaude Codeは、あくまで一例です。後半では、その一例をそのままコピペして手元に置ける形で渡します。
先に結論だけ言うと —— 道具より、役割とバトンの方が残ります。

「これかよ」から始まった

MCPも繋いだ。Figmaも読ませた。待つ時間も、トークンも、ちゃんと使った。
なのに出てきた実装は、仕様と違う挙動をする。
見た目はそれっぽい。動くと言えば動く。でも「痒いところに手が届かない」。押したときの反応、空のときの顔、エラーの抜け方——仕様書の行間にあったはずのものが、ごっそり抜けている。

頭の中のセリフは、たぶんこれでした。
「トークン使って、長いこと待たされたのに、実装結果はこれかよ。」
指示が悪かったのも事実です。プロンプトを磨けばマシにはなる。でも、そこで気づきました。自分が本当に欲しかったのは「うまいプロンプト」じゃなくて、意図と違う挙動が生まれる前に、疑いを挟む仕組みだった、と。

その仕組みの中身は、この記事の後半に全部置いてあります。先に「なぜそれが必要か」だけ、付き合ってください。

熱い道具を追うと、だいたい同じ場所に戻る

AIのトレンドは速すぎます。モデルも、IDEも、MCPも、先週の正解が今週の前提になります。
だから最初の自分は、こう考えていました。

  • いいプロンプトを書けばうまくいく
  • いちばん強いモデルに全部やらせればいい
  • AI同士を繋げば自動化できる
  • 人間は指示を渡すだけでいい

全部、一理ある。全部、罠でもある。
特に厄介なのが「今いちばん熱い道具を追えば解ける」です。道具を足すたびに期待は上がるのに、仕様と違う挙動は減らない。足しているのは機能であって、判断の構造ではないからです。

じゃあどうするか。僕が出した答えはシンプルでした。
AIを脳死で使わない。独自のワークフローを決める。正直、何のAIでもいい。

そもそも、なぜ組み合わせたかったのか

コードベース・デザイン・APIを参照しながら実装できる環境は整ってきました。ただ「なんとなく実装できた」状態になりがちで、細かい差異を後から修正することが多かった。

根本的な問題は2つです。

① 仕様の曖昧さを人間が見落とす 「実装してみて初めて気づく疑問」というのが必ず出てきます。ページネーションの挙動、0件時のUI、エラー時のフォールバック……。これらを実装前に洗い出せれば手戻りがなくなるはずです。

② AIへの指示に自分の解釈が混入する 仕様をAIに伝えるとき、自分の理解や記憶を通すので、デザインやドキュメントに書いてあることと自分が伝えたことが微妙にずれることがある。

この2つを解決するために考えたのが「AIに仕様を調べさせ、別のAIに疑問を洗い出させる」という分業体制でした。
「CursorとClaude Codeを会話させたい」——そんなアイデアから始まりました。それぞれ得意なことが違うなら、うまく組み合わせれば仕様を固めて実装まで走れるんじゃないか、と。

最初に試みたこと、そして失敗

「Claude CodeとCursorを直接繋げられないか」と最初に考えました。

claude-code-mcp というツールがあり、これを使えばCursorからMCP経由でClaude Codeを呼び出せると読んだのです。「CursorがClaude Codeに質問を投げて、Claude Codeが答えを返す」という自動化ができるのでは、と期待しました。

実際に設定して試してみました。結果は、動きませんでした。

何が起きたか

Cursorから claude_code ツールを呼び出すプロンプトを書いても、Claude Code側では何も起きませんでした。ターミナルのClaude Codeセッションは静かなままです。

調べると、根本的な設計の問題でした。Claude CodeとCursorは完全に別プロセスで動いており、お互いのセッションにリアルタイムでアクセスする手段が存在しないのです。
「AIエージェント同士がリアルタイムに会話する」は現時点では実現できない。これが最初の壁でした。

発想の転換

リアルタイムに会話できないなら、共有ファイルを介して非同期に会話させればいい。

人間同士でも、リアルタイムで話せないときはドキュメントをやりとりします。「この資料を確認して意見をください」「回答を追記しました」というやりとりです。AIエージェント同士でも同じことができるはずです。
そこで思いついたのが「共有mdファイルをバトンにする」アイデアでした。ファイル名は何でも構いません。今回はたまたま spec.md にしていますが、task.md でも brief.md でも同じです。

ワークフローの全体像

① Cursorがコードベース・デザイン・ドキュメント・APIを調査してspec.mdを生成
         ↓
② Claude Codeがspec.mdを読んで疑問をまとめて質問・停止
         ↓
③ Cursorがspec.mdの質問に回答・更新
         ↓
④ ②〜③を疑問がなくなるまで繰り返す
         ↓
⑤ Claude Codeが実装開始

それぞれの役割はこうです。

  • Cursor：コードベース・デザイン・ドキュメント・APIを調査してspec.mdを生成、Claude Codeの質問に回答
  • Claude Code：spec.mdを読んで疑問を洗い出し、解消されたら実装
  • 共有mdファイル：両者の共通言語・意思決定の記録

大事なのは固有名詞ではありません。今回の配役はこうだった、という話です。

  • 調べて書く役
  • 疑って止める役
  • 二者の共通言語になるバトン

道具が変わっても、この三つが残れば同じことができます。

spec.mdが持つ3つの役割

① 両エージェントの共通言語 CursorもClaude Codeも同じファイルを読み書きすることで、「前のやりとりでこう決まった」という文脈が共有されます。

② セッションをまたいだ文脈の保持 どちらのセッションがリセットされても、spec.mdを読めば文脈が復元できます。

③ 意思決定の記録 実装が終わった後も、Q&Aセクションには「なぜこういう実装になったか」の意思決定が残ります。

やってみてわかったこと

あえて「完全自動化しない」ことが価値になる

人間がプロンプトを渡すステップが残っていることを最初は弱点だと思っていました。でも実際に使っていると、これは人間がレビューポイントを持てるという強みでした。
Claude Codeが質問を出すたびに「確かにそれは確認が必要だな」と判断できます。Cursorの回答が返ってきたときも「この回答で本当に合ってるか」を確認できます。
完全自動化すると「AIが勝手に判断した仕様で実装が完了してしまう」リスクがあります。あえて人間が間に入るステップを残すことで、意思決定に関与し続けられる。これは設計上の利点です。

「仕様が固まる過程」が記録として残る

実装が終わった後も、spec.mdのQ&AセクションにはAIとのやりとりを通じた意思決定の記録が残ります。

Q1: 未実装のAPIフィールドはどう扱いますか？
A1: モックで先行実装する。
    API側が対応したら接続部分だけ差し替えられるようにしておく。
    根拠: 既存の類似実装（src/features/users/）が同じ方針を採っている。

Q2: フィルターの選択肢が定数ファイルに未定義です。どう定義しますか？
A2: constants/options.tsに新規追加。既存の命名規則に合わせる。
    根拠: 同ファイル内の既存定数を参照。

後から「なんでこのコードこうなってるんだっけ」という疑問が湧いたとき、spec.mdを見れば答えがわかる。

副産物として気づいたのは、Claude Codeに「疑問があれば止まって質問せよ、回答が揃うまで実装するな」と役割を与えたことで、AI自身が曖昧な仕様のまま自己判断で進まなくなったことです。
仕様と違う挙動は、才能不足の証明というより、疑い役が不在だった合図なのかもしれません。

ここで閉じると、たぶん明日また「これかよ」になる

構造の話は、ここまでです。
でも正直に言うと、ここまでで「なるほど」と思って閉じると、翌日の実装でまた同じ場所に戻ります。頭の中の納得と、手元の / メニューは別物だからです。

前半で出てきた「調べる役」「疑う役」「バトン」——それを、今から自分の環境にインストールします。
所要は短いです。一度置けば、あとはスラッシュを打つだけ。
コピペでいい。理解は後から追いつきます。ここから下が、この記事の本番です。

手元で動かす —— 明日から「疑い役」を常備する

読み終わったあとに「なるほどね」で終わるのが、いちばんもったいない終わり方です。

進め方は三つだけ。

  1. 土台を置く（スキルとコマンド）
  2. 中身を置く（プロンプト）
  3. 一回まわす（開発フロー）

長いコードブロックが出てきます。全部暗記しなくて大丈夫です。代わりに、各所で「ここだけ見て」と印をつけます。そこが、前半の失敗談とつながる線です。

セットアップ

毎回プロンプトをコピペするのは手間なので、一度設定しておけばスラッシュコマンドで呼び出せます。ここを済ませると、物語の中に出てきた「調べる役」「疑う役」が、自分の環境の / メニューに現れます。

Claude Code側（グローバル設定・1回だけ）

mkdir -p ~/.claude/skills/spec-driven-impl

以下の構成でファイルを作成します（ディレクトリ名・ファイル名は任意）。

~/.claude/skills/spec-driven-impl/
├── SKILL.md            ← ワークフロー本体（Claude Codeが /spec-driven-impl で呼び出す）
├── cursor-survey.md    ← Cursorの「仕様調査」テンプレート
├── cursor-answer.md    ← Cursorの「質問回答・初回」テンプレート
└── cursor-followup.md  ← Cursorの「質問回答・追加」テンプレート

~/.claude/skills/ に置くことで全プロジェクトで使い回せます。Claude Codeのチャットで / を打つとスキル名が候補に出ます。ここが「疑い役」の本体です。

Cursor側（プロジェクトごと）

次は「調べて書く役」側。Cursorはグローバルなカスタムコマンドをサポートしていないためプロジェクトごとの設定になりますが、.zshrc にエイリアスを登録しておくと1コマンドで展開できます。

# ~/.zshrc に追記
alias setup-spec-skill='mkdir -p .cursor/commands && cp ~/.claude/skills/spec-driven-impl/cursor-*.md .cursor/commands/ && echo ".cursor/commands/cursor-*.md" >> .gitignore && echo "✅ セットアップ完了"'
source ~/.zshrc

以降は新プロジェクトのルートで以下を打つだけです。

cd ~/workspace/プロジェクト名
setup-spec-skill

.gitignore に追加済みなのでチームには共有されません。Cursorのチャット欄で / を打つと3つのコマンドが候補に出ます。

土台ができたら、次は中身です。ここから先のプロンプトが、「仕様と違う挙動」が出る前に疑いを挟むための脚本になります。

実際のプロンプト

プロンプト全文は長いですが、役割は三つだけです。

  • 調べて spec.md を書く
  • 読んで止まって質問する
  • 根拠つきで答える

「これかよ」のあとに欲しかったのは、気合ではなくこの往復でした。

Cursor「仕様調査」：spec.mdを生成する（/cursor-survey）

最初の一手です。ここで曖昧さを放置すると、あとで仕様と違う挙動として戻ってきます。
cursor-survey.md はグローバルに管理されているテンプレートです。毎回のタスク開始時にこのファイルを直接編集してからCursorのチャットで /cursor-survey と送信します。

# 役割
あなたは仕様調査エージェントです。
Claude Codeが実装を迷わず開始できるよう、
必要な情報をすべて調査してspec.mdに書き出してください。

# タスク
【ここにタスクの内容を書く】

# 調査してほしいこと
【必要なものだけ書く。不要な行は消す】
- デザインツール（Figma等）: 【URL】
- 既存の類似実装がどこにあるか
- 使うべき共通コンポーネントの場所
- APIのエンドポイントと型定義
- 仕様書・ドキュメント: 【URL or パス】
- その他: 【自由に追加】

# spec.mdに書き出す内容
調査した内容をすべてspec.mdにまとめてください。
最後に「## Q&A」セクションを空で作っておいてください。

完了したら「spec.mdを作成しました」とだけ報告してください。

不要な行は消すだけです。毎回このテンプレートをタスク内容に合わせて書き換えてから /cursor-survey を送信します。

Claude Code：実装（/spec-driven-impl）

ここが「疑い役」の本体です。実装を急がせず、先に疑問で止めさせる。この一文のために、前半の失敗談がありました。
毎回のタスク開始時はチャットでこう書くだけです。

/spec-driven-impl

SKILL.mdの中身（ワークフロー本体）は以下です。長いですが、最初に見るのは一番下の「禁止事項」だけで大丈夫です。あの「これかよ」を防ぐ線引きが、そこに三行で書いてあります。

# spec駆動実装ワークフロー

## 起動前チェック
spec.mdがプロジェクトルートに存在しない場合は以下を出力して停止する：
「spec.mdが見つかりません。Cursorでspec.mdを先に生成してください。」

## Phase 1：仕様確認

1. spec.mdを読む
2. 実装に着手する前に曖昧・未確定な点をすべて洗い出す
3. 質問を以下のルールでspec.mdの「Q&A」セクションに追記する
   - 独立した質問はまとめて追記する（Q1, Q2, Q3...と番号を振る）
   - 前の質問の回答に依存する質問は、回答を受け取ってから追記する
   - 各質問に「なぜ実装上の判断ができないか」を1行添える
4. 疑問がなければそのままPhase 2へ進む
   疑問があれば「spec.mdにQ1〜Qxの質問を追記しました。Cursorで回答してください。」と報告して停止する
5. 回答が返ってきたらspec.mdを読み直し、未解消の疑問があれば3〜4を繰り返す
6. すべて解消されたらPhase 2へ進む

## Phase 2：実装

7. spec.mdの確定仕様に従って実装する
8. 実装中に新たな不明点が出た場合はPhase 1の3〜5に戻る
9. 実装完了後、spec.mdに「## 実装メモ」セクションを追記する
   - 自己判断で決定した事項とその理由
   - 今後の改修時に注意すべき点

## 禁止事項
- 質問への回答が揃う前に実装を開始すること
- 「仮実装」「暫定」として理由なく自己判断で進めること
- spec.mdに記載のない仕様を無断で追加すること

ポイント： 独立した質問はまとめて出す、依存関係があるものだけ分割する。疑問がなければそのままPhase 2へ進む。

止まられたら、次は人間が間に入る番です。ここを自動化しないのが、このワークフローの味です。

Cursor「質問回答（初回）」：Q&Aに最初の回答を追記する（/cursor-answer）

疑い役が投げた球を、調べ役が打ち返す番です。見るのは「根拠：」の一行。感覚ではなく、ドキュメントやコードのどこにあったかを残させます。

spec.mdのQ&AにClaude Codeから質問が追記されています。

各質問に対して以下を参照しながら回答をspec.mdに追記してください：
- デザインツールやドキュメントを確認する
- コードベースで実装・型定義を確認する
- 判断できない場合は「要確認：【確認すべき情報源】」と明記する

回答の書き方：
- Ax: 【結論を1行で】
  根拠：【ドキュメントのどこ、またはコードのどこにあったかパスやURLで示す】

完了したら「spec.mdを更新しました（Q1〜Qxを回答）」と報告してください。

Cursor「質問回答（追加）」：ループ2周目以降の回答（/cursor-followup）

2周目以降も同じです。

spec.mdのQ&Aに新しい質問が追記されています。
cursor-answer.mdと同じ方針で回答を追記してください。
完了したら「spec.mdを更新しました（Qx〜Qxを回答）」と報告してください。

毎回の開発フロー

全部つなげると、こうなります。これが、明日のタスク用のチェックリストです。

いちばんおいしい瞬間は ③ です。/spec-driven-impl を打ったあと、実装が始まらずに質問で止まる——あの静けさが、前半で欲しかった「疑いを挟む仕組み」そのものです。

# ① cursor-survey.mdをタスク内容に合わせて編集する

# ② Cursorのチャットで /cursor-survey を送信 → spec.mdが生成される

# ③ Claude Codeで起動
/spec-driven-impl
→ 疑問があれば質問を追記して停止、なければ実装開始

# ④ Cursorで /cursor-answer を送信 → Q&Aに回答が追記される

# ⑤ Claude Codeで再び実行
/spec-driven-impl
→ 疑問が残れば /cursor-followup でループ、なければ実装開始

最後に

ここまで付き合ってくれてありがとうございます。前半の失敗談も、後半のコピペも、同じ話の表裏です。

このワークフローの本質は、AIエージェントに役割を与えて、共有ファイルで仕様を育てることです。

  • Cursor：仕様調査・質問への回答
  • Claude Code：疑問の洗い出し・実装
  • 共有mdファイル：両者の共通言語・意思決定の記録

重要なのは「CursorとClaude Codeの組み合わせ」ではなく「役割の分担」と「共通ドキュメント」という構造です。AIツールの性能は移り変わりが激しいので、この構造さえ維持すれば、各役割を担うツールは時代に合わせて入れ替えられます。

「AIを使う」から「AIに役割を与えて動かす」へ。

次に「これかよ」が頭をよぎったとき、プロンプトを責める前に、役割を見てみてください。そしてよければ、このまま /cursor-survey を一度打ってみてください。記事の続きは、あなたのターミナル側にあります。
道具は一例。残るのは役割とバトンです。

おすすめ記事

Recommend