🐸

もっと気軽にDocDD(SpecDD)でAI駆動開発したい

に公開
AI
Cursor
Agent
Claude Code
tech

はじめに

CursorやClaude Codeを使っているエンジニアの皆さん、こんな悩みを抱えたことありませんか？

  • AIアシスタントに適切なコンテキストを渡すのが難しい
  • 開発ワークフローが属人化して、チームで統一されない
  • MCP（Model Context Protocol）の使い方がよくわからない
  • コード品質を保ちながら効率的に開発したい

このような課題を解決するために、DocDDというプロジェクトを作成しました。

この記事では、DocDDを使ってMCPをうまく活用し、効率的な開発ワークフローを構築する方法を紹介します。

DocDDとは

DocDD（Document-Driven Development）は、Document Driven Developmentの略称で、YUMEMIが確立した生成AIの利用とドキュメンテーションを中心とする開発手法です。

一般的なSpecDDに近い考え方で、仕様書などのドキュメントを生成し、開発で必要な全てのドキュメントをAIエコシステムで構築するプロジェクトです。

このワークフローが対象とするドキュメント

このワークフローでは、以下のような開発ドキュメントを扱います：

  • アーキテクチャ設計、API仕様、機能仕様などの技術ドキュメント
  • 技術的な意思決定の記録と管理を行うアーキテクチャ決定記録（ADR）
  • UI/UXデザイン、デザインシステム、デザインガイドラインなどのデザインドキュメント
  • 開発プロセス、ベストプラクティス、ガイドラインなどの開発ワークフロー
  • プロジェクトオンボーディング資料、ドメイン知識の記録など

開発に関わるドキュメントを幅広くカバーしているので、プロジェクトの規模が大きくなっても対応できます。

このワークフローの特徴

このワークフローには以下のような特徴があります：

  • 11フェーズの標準化された開発プロセスにより、調査から実装、テスト、デプロイまで一貫した流れ
  • Kiri、Serena、Next.js Runtime、Chrome DevToolsなど、各MCPの特性を活かした活用方法
  • テスト、UIデザイン、アーキテクチャ設計、ADR管理など、各領域の専門家エージェントが7種類用意
  • curlコマンド1つで既存プロジェクトに設定を移行可能
  • コードだけでなく、開発に関わる全てのドキュメントをAIで管理

プロジェクト構成

このプロジェクトは以下のファイル構成で、プロジェクトに標準化された開発環境を提供します：

プロジェクトルート/
├── CLAUDE.md              # 開発ワークフロー定義（Phase 1-11）
├── MCP_REFERENCE.md       # MCPコマンドの詳細リファレンス
├── .cursorrules           # Cursorの設定ルール
├── .mcp.json              # MCP設定
├── .claude/
│   ├── agents/            # Claudeエージェント定義（7種類）
│   └── settings.json      # Claude設定
└── .cursor/
    ├── commands/          # Cursorコマンド定義（7種類）
    ├── mcp.json          # Cursor MCP設定
    └── settings.json      # Cursor設定

GitHubリポジトリ

DocDDのソースコードとドキュメントは、以下のGitHubリポジトリで公開されています。
MITで公開しているので、好きにカスタマイズしてください。

https://github.com/imaimai17468/docdd

導入方法

DocDDを既存プロジェクトに導入するのは簡単です。
コマンド一つで設定ファイルを移行できるので、すぐに使い始められます。

基本的な導入方法

# カレントディレクトリに移行
curl -fsSL https://raw.githubusercontent.com/imaimai17468/docdd/main/migrate.sh | bash -s -- .

# 特定のプロジェクトに移行
curl -fsSL https://raw.githubusercontent.com/imaimai17468/docdd/main/migrate.sh | bash -s -- /path/to/target-project

既存ファイルがある場合は、上書き確認が行われます
導入後、プロジェクトに合わせて以下の設定を調整してください

MCP（Model Context Protocol）の活用

MCPは、AIアシスタントが外部ツールやサービスと連携するためのプロトコルです。DocDDでは、以下のMCPをうまく使い分けることで、開発効率を大きく上げています。

使用するMCP一覧

MCP 用途 主な機能
Kiri MCP コードベース検索・調査 セマンティック検索、コンテキスト自動抽出、依存関係分析
Serena MCP コード編集・実装 シンボルベース編集、リネーム、参照検索
Next.js Runtime MCP ランタイム確認 エラー確認、ルート確認、ログ取得
Chrome DevTools MCP ブラウザ検証 ページ構造確認、インタラクションテスト、パフォーマンス測定
Context7 MCP ライブラリドキュメント 最新のライブラリドキュメント取得

Kiri MCP：調査フェーズの強力な武器

Kiri MCPは、コードベースの調査に特化したMCPです。Serenaよりも高度な検索機能を提供します。

https://github.com/oraios/kiri

コンテキスト自動取得

Kiri MCPの一番便利な機能が、このコンテキスト自動取得です。

「ユーザー認証機能を実装したい」と伝えるだけで、認証関連のコードを自動で探して、関連性の高い順にランク付けしてくれます。手動でファイルを探す必要がなくなるので、時間の節約になります。

使い方のコツは以下の通りです：

  • 「ユーザー認証、ログインフロー、JWT検証」のように具体的なキーワードを指定すると、より正確な結果が返ってきます。「理解する」のような抽象的な動詞は避けた方がいいです
  • 効率的に調査するなら、まず関連ファイルのリストだけを取得して、必要なファイルの詳細は後で確認するのがおすすめです
  • 一度に取得するファイル数を制限すれば、トークン消費も抑えられます

特徴は以下の通りです：

  • 複合語を認識（page-agent、user_profileなど）
  • ファイルパスを考慮した関連性の判断
  • インポート関係を考慮した依存関係の分析
  • コードの構造的類似性を考慮したランク付け

これらの機能により、コードベースの理解が深まり、実装の精度を向上させることができます。

依存関係の調査

リファクタリングするとき、その変更がどのファイルに影響するか調べられるのも便利です。

特定のファイルを変更する場合、そのファイルを使っている他のファイルや、そのファイルが依存しているファイルを自動で見つけてくれます。これにより、リファクタリング時の影響範囲を事前に把握できるので、予期しないバグを防げます。

使い分けのコツは以下の通りです：

  • 影響範囲の確認：このファイルを使っている他のファイルを探すときに使用
  • 依存チェーンの確認：このファイルが依存しているファイルを探すときに使用
  • 深さを指定して階層を制御可能

Serena MCP：実装フェーズの正確な編集

Serena MCPを使うと、関数やクラス単位で正確にコードを編集できます。

https://github.com/oraios/serena

手動で書き換えるより、AIが適切な位置を特定して編集してくれるので、ミスが減ります。

主な機能は以下の通りです：

  • 既存の関数やメソッドの実装を新しい実装に置き換え：関数名とファイルパスを指定するだけで正確な位置を特定してくれます
  • 既存のクラスにメソッドを追加：クラス名や関数名を指定すれば適切な位置に挿入してくれます
  • プロジェクト全体で関数名や変数名を一括変更：すべての参照が自動的に更新されるため、手動で検索・置換する必要がありません

リネーム機能は便利で、プロジェクト全体の変数名を一括変更するときに重宝します。

Next.js Runtime MCP：動作確認の自動化

Next.js Runtime MCPを使うと、Next.js開発サーバーが起動している状態で、エラーやルート構造を自動的に確認できるのが便利です。

https://github.com/vercel/next-devtools

ブラウザを開かなくても、開発サーバーの状態を確認できるので、開発の効率が上がります。

主な機能は以下の通りです：

  • 実行中のNext.js開発サーバーを自動で検出
  • ビルドエラーやランタイムエラーを自動で取得
  • アプリケーション内のすべてのルート（App Router）を一覧表示

これにより、ビルドエラーやランタイムエラーを自動的に検出でき、すべてのルートが正しく認識されているかも確認できます。

Chrome DevTools MCP：詳細なブラウザ検証

Chrome DevTools MCPを使うと、ブラウザでの動作確認を自動化できるのも便利です。

https://github.com/modelcontextprotocol/servers/tree/main/src/chrome-devtools

パフォーマンス測定やレスポンシブデザインの確認にも使えます。

主な機能は以下の通りです：

  • ページの構造をテキスト形式で取得（各要素に一意のIDを付与）
  • クリック、フォーム入力、ホバーなどの操作を自動化
  • Core Web Vitals（LCP, FID, CLS）などの指標を自動測定

パフォーマンス測定は自動化できるので、定期的に確認できます。

専門エージェントの活用

DocDDには、7種類の専門エージェントが含まれています。各エージェントは特定の領域に特化していて、開発効率を大きく向上させます。

エージェントのカスタマイズについて

各エージェントの定義ファイル（.claude/agents/*.md）には、プロジェクト固有のルールやベストプラクティスが書かれています。

DocDDを導入した後は、プロジェクトの要件に合わせて、これらのファイルを適宜書き換えてください。そうすれば、各エージェントがプロジェクトのコーディング規約や開発スタイルに最適化されます。

1. component-refactoring-specialist（コンポーネントリファクタリング専門家）

Reactコンポーネントの構造整理と保守性向上を担うエージェントです。

主な機能は以下の通りです：

  • UIとビジネスロジックの分離
  • プレゼンターパターンの適用
  • ディレクトリ構造の再編成

2. test-guideline-enforcer（テストガイドライン強制）

Vitest / React Testing Libraryを使用したテストコードの品質、構造、命名規約を強制するエージェントです。テストコードの品質を担保するためのルールを厳守させます。

主な機能は以下の通りです：

  • AAAパターン（Arrange-Act-Assert）の厳守
  • 日本語テストタイトルの強制
  • すべての条件分岐のカバー

3. storybook-story-creator（Storybookストーリー作成）

プロジェクトルールに準拠したStorybookストーリーの作成とメンテナンスを担うエージェントです。

主な機能は以下の通りです：

  • 条件分岐による表示切り替えのストーリー化
  • Meta設定の標準化
  • イベントハンドラーの実装

4. ui-design-advisor（UIデザインアドバイザー）

ダークテーマに焦点を当てたUI/UXデザイン専門家です。レイアウトのレビューと改善提案を担います。

主な機能は以下の通りです：

  • カラー戦略の提案
  • タイポグラフィとスペーシングの確認
  • アクセシビリティの確認

5. spec-document-creator（仕様書作成）

拡張可能な仕様書作成コマンドです。機能仕様、API仕様、アーキテクチャ仕様など複数のドキュメントタイプに対応しています。

主な機能は以下の通りです：

  • 機能仕様、API仕様、アーキテクチャ仕様の作成
  • 既存コードからのリバースエンジニアリング
  • テンプレートシステムによる標準化

6. adr-memory-manager（ADRメモリマネージャー）

AI用のADR（Architecture Decision Record）を自動記録・検索・管理するエージェントです。JSON形式で機械可読性を最優先に設計しています。

主な機能は以下の通りです：

  • アーキテクチャ決定の自動記録
  • 決定の検索と参照
  • 決定の関連付け

7. project-onboarding（プロジェクトオンボーディング）

プロジェクトの構造、ドメイン知識、技術スタック、アーキテクチャパターンを分析・記録するエージェントです。新規プロジェクトのオンボーディングに最適です。

主な機能は以下の通りです：

  • プロジェクト構造の分析
  • 技術スタックの記録
  • ドメイン知識の抽出

開発ワークフロー

このワークフローの核心は、11フェーズの標準化された開発プロセスです。

変更のタイプに応じて適切なフェーズを選ぶことで、効率的かつ高品質な開発ができます。

ワークフロー概要

変更タイプ 推奨フロー 所要時間目安
新機能追加 Phase 1-11 全て 60-120分
中規模バグ修正 1,4,5,6,8,9A,10,11 30-60分
UI/デザイン調整 1,3,4,5,8,9A,10,11 20-40分
小規模リファクタ 1,4,5,8,10,11 15-30分
タイポ修正 5,8,10,11 5分

各フェーズの詳細

Phase 1: Investigation & Research（調査フェーズ）

使用ツール: Kiri MCP, Context7 MCP

既存コードベースの調査とライブラリドキュメントの確認を行います。

このフェーズをしっかり行うことで、実装の精度を向上させることができます。

主な作業は以下の通りです：

  • Kiri MCPで関連コードを自動取得
  • Context7 MCPでライブラリドキュメントを確認
  • 既存パターンと依存関係を把握
  • ADR（Architecture Decision Record）を確認

Phase 2: Architecture Design（アーキテクチャ設計）

使用エージェント: component-refactoring-specialist, spec-document-creator, adr-memory-manager

新機能や大規模変更のときに実行します。既存パターンに完全に倣う場合や、1ファイル以内の小さな修正ならスキップできます。

主な作業は以下の通りです：

  • ファイル配置、ディレクトリ構造、状態管理、データフローを設計
  • コンポーネント分割、Propsインターフェース、再利用性と保守性を考慮
  • spec-document-creatorエージェントを使って、機能仕様、API仕様、アーキテクチャ仕様など必要に応じて作成
  • adr-memory-managerエージェントを使って、重要な決定をADRとして記録（コンテキスト、根拠、代替案を含む）
  • Next.js 16の機能活用、レンダリング戦略、画像最適化などを検討

Phase 3: UI/UX Design（デザイン設計）

使用エージェント: ui-design-advisor

UI変更があるときに実行します。UIに変更がない場合や、ロジックのみの変更ならスキップできます。

主な作業は以下の通りです：

  • ダークテーマ、カラー戦略、タイポグラフィ、スペーシング、レイアウト設計
  • セマンティックHTML、ARIA属性、キーボード操作対応
  • モバイル、タブレット、デスクトップでの表示確認、ブレークポイント設定

Phase 4: Planning（計画立案）

使用ツール: TodoWrite tool

実装計画を作成し、タスクを細分化します。

主な作業は以下の通りです：

  • タスクを細分化し、実装順序を決定
  • TodoWriteツールで作業項目をトラッキング
  • 各タスクの依存関係を明確化

Phase 5: Implementation（実装）

使用ツール: Serena MCP

Phase 1で調査した内容を基に、Serena MCPでシンボルベース編集を実施します。

シンボルベース編集により、手動で編集するより安全にコードを編集できます。

主な作業は以下の通りです：

  • Serena MCPでシンボルベース編集を実施
  • TypeScript型定義を厳密に
  • 既存パターンに準拠
  • 日本語コメントで意図を説明

コーディング規約は以下の通りです：

  • バレルインポート禁止（@/ aliasを使用した個別インポート）
  • TypeScriptの型定義を厳密に
  • 日本語コメントで意図を明確に

これらの規約を守ることで、コードの品質が保たれます。

Phase 6: Testing & Stories（テスト・ストーリー作成）

使用エージェント: test-guideline-enforcer, storybook-story-creator

ロジック変更があるときに実行します。UI/表示のみの変更でロジック変更がない場合や、既存テストが十分にカバーしているならスキップできます。

主な作業は以下の通りです：

  • 条件分岐による表示切り替えがある場合のみStorybookストーリーを作成
  • Vitest / React Testing Libraryでテストコードを実装（AAAパターン厳守、日本語テストタイトル、全条件分岐をカバー）

Phase 7: Code Review（コードレビュー）

使用エージェント: component-refactoring-specialist

コードの品質に不安がある場合、リファクタリングが必要な場合、複雑なロジックを実装したときに実行します。

主な作業は以下の通りです：

  • コードの品質、可読性、保守性、ベストプラクティスへの準拠、パフォーマンス、責任分離を確認
  • コード改善、重複削除、命名改善、コンポーネントの分割・統合の提案
  • リファクタリングによる変更の反映、実装とADRの一致確認、新パターンの追記

Phase 8: Quality Checks（品質チェック）

使用ツール: Bash tool

静的解析とテストを実行します。

# 型チェック
bun run type-check

# Lint
bun run lint

# テスト実行
bun run test

# ビルド確認
bun run build

Phase 9A: Runtime Verification（ランタイム確認）

使用ツール: Next.js Runtime MCP

Next.js開発サーバーのランタイムエラーを確認します。

主な確認項目は以下の通りです：

  • ビルド・ランタイムエラーがゼロ
  • 全ルートが正しく動作
  • コンソールエラー・警告がゼロ

Phase 9B: Browser Verification（ブラウザ検証）

使用ツール: Chrome DevTools MCP

詳細な動作確認が必要なときに実行します。複雑なUIインタラクション、パフォーマンス測定、ネットワークリクエストの確認、レスポンシブデザインの詳細確認が必要なときに使います。

主な確認項目は以下の通りです：

  • ネットワークリクエストが正常（4xx/5xxエラーなし）
  • Core Web Vitals（LCP, FID, CLS）が良好
  • レスポンシブデザインが正常（375px〜1920px）
  • アクセシビリティツリーが適切

Phase 10: Git Commit

適切なコミットメッセージで変更をコミットします。

git add .
git commit -m "feat: add new feature description"

Phase 11: Push

リモートリポジトリにプッシュします。

git push origin <branch-name>

実践例：新機能追加のワークフロー

実際の開発シナリオで、このワークフローがどう機能するか見てみましょう。

シナリオ：ユーザー認証機能の追加

Phase 1: Investigation & Research

まず、Kiri MCPを使って既存の認証関連コードを調査します。

「ユーザー認証、ログインフロー、JWT検証」というキーワードを指定すると、関連するコードを自動で見つけて、関連性の高い順にランク付けしてくれます。効率的に調査するため、まずは関連ファイルのリストだけを取得し、必要なファイルの詳細は後で確認するのがおすすめです。

結果から必要なファイルを特定したら、そのファイルの詳細を取得します。例えば、src/auth/login.tsの詳細を確認する場合、ファイルパスを指定してコードスニペットを取得できます。

次に、Context7 MCPでNext.jsの認証関連ドキュメントを確認します。ライブラリ名を指定すると、最新のドキュメントを取得できます。認証トピックに関する情報を取得することで、最新のベストプラクティスを確認できます。

Phase 2: Architecture Design

認証機能は新機能なので、アーキテクチャ設計を行います。

component-refactoring-specialistエージェントを使って、認証機能のファイル配置とディレクトリ構造を設計します。src/auth/ディレクトリに認証関連のファイルを配置し、src/services/auth.tsに認証サービスを実装する方針を決定します。

spec-document-creatorエージェントを使って、認証機能のAPI仕様を作成します。ログイン、ログアウト、トークン検証などのエンドポイントとリクエスト/レスポンス形式を定義します。

adr-memory-managerエージェントを使って、JWTトークンを使用するという技術的決定をADRとして記録します。決定のコンテキスト、根拠、代替案（セッション管理など）を含めて記録します。

Phase 3: UI/UX Design

ログインフォームなどのUIコンポーネントが必要なので、UI/UX設計を行います。

ui-design-advisorエージェントを使って、ログインフォームのデザインを検討します。ダークテーマに合わせたカラー戦略、タイポグラフィ、スペーシングを決定します。

アクセシビリティも考慮し、セマンティックHTML、ARIA属性、キーボード操作対応を設計します。モバイル、タブレット、デスクトップでの表示も確認し、ブレークポイントを設定します。

Phase 4: Planning

TodoWriteツールで実装計画を立てます。

  • 認証APIエンドポイントの実装
  • ログインフォームコンポーネントの作成
  • JWTトークン検証ロジックの実装
  • 認証状態管理の実装
  • テストコードの作成

Phase 5: Implementation

Serena MCPを使って、シンボルベース編集を実施します。

AuthServiceクラスに新しいメソッドを追加する場合、クラス名とファイルパス（src/services/auth.ts）を指定するだけで、適切な位置に新しいメソッドが正確に挿入されます。

例えば、JWTトークンを検証するvalidateTokenメソッドを追加する場合、適切な型定義とコメントを含めた実装を指定します。これにより、手動でのコード編集よりも正確で安全な編集が可能です。

Phase 6: Testing & Stories

認証機能にはロジックが含まれるので、テストコードを作成します。

test-guideline-enforcerエージェントを使って、Vitest / React Testing Libraryでテストコードを実装します。AAAパターン（Arrange-Act-Assert）を厳守し、日本語のテストタイトルを使用します。

validateTokenメソッドのテストでは、有効なトークン、無効なトークン、期限切れトークンなど、すべての条件分岐をカバーします。

ログインフォームコンポーネントには条件分岐による表示切り替え（エラーメッセージの表示など）があるので、storybook-story-creatorエージェントを使ってStorybookストーリーを作成します。

Phase 8: Quality Checks

品質チェックを実行します。

bun run type-check  # ✅ パス
bun run lint        # ✅ パス
bun run test        # ✅ パス
bun run build       # ✅ パス

Phase 9A: Runtime Verification

Next.js Runtime MCPを使って、エラーを確認します。開発サーバー起動後、ビルドエラーやランタイムエラーを自動で取得できます。エラーがあれば、その内容を確認できます。

結果: エラーなし ✅

Phase 10 & 11: Git Commit & Push

変更をコミットしてプッシュします。

git add .
git commit -m "feat: add user authentication with JWT"
git push origin main

まとめ

DocDDプロジェクトを導入すると、以下のメリットがあります：

主なメリット

  • 標準化された開発ワークフローにより、開発の流れが明確になり、迷うことがなくなります
  • 各MCPの特性を活かした使い分けができます
  • ワークフローに従うことで、コードの品質が保たれます
  • 標準化されたワークフローにより、開発の効率を向上させることができます
  • コマンド一つで設定ファイルを移行できるので、すぐに使い始められます

今後の展望

DocDDは継続的に改善されており、以下のような機能追加が予定されています：

  • より多くのMCPサポート
  • 追加の専門エージェント
  • ワークフローのカスタマイズ機能強化
  • チーム向けのコラボレーション機能
  • 営業・マーケティング資料の生成（開発中）：プロダクト説明資料、プレゼンテーション資料の自動生成

今後も継続的に改善していく予定です。

参考リンク

Discussion