🔊

Amplifierによるメタ認知AI開発入門

に公開
1件
DDD
SDD
Claude Code
Vibe Coding
amplifier
tech

DDD と AI 開発

「ドキュメントが仕様であり、コードは実装である」——この原則を徹底すると、AI 協働開発はどう変わるのでしょうか？

Amplifier は、Microsoft が開発する実験的なメタ認知 AI 開発システムです。従来の AI 支援ツールと決定的に異なるのは、Document-Driven Development (DDD) という思想を体系化している点です。ドキュメントを先に書き、そこからコードを生成する——このシンプルな原則が、Context Poisoning（古い情報による誤実装）を防ぎ、常にドキュメントとコードが同期した状態を保証します。

本記事では、サンプルプロジェクト「ポモドーロタイマーアプリ」の実装を通して、DDD ワークフローの 5 つのフェーズ（計画 → ドキュメント → コード計画 → 実装 → 完了）を体験します。

Amplifier とは

Amplifier は、Microsoft が開発している実験的な「メタ認知 AI 開発システム」です。
単にコードを自動生成するだけでなく、「どのように考えるか（思考プロセス）」を記述することで、複雑な開発ワークフロー全体を自動化・支援することを目指しています。

なぜ Amplifier を使うのか？

  1. ドキュメント駆動開発 (DDD) の強制:
    いきなりコードを書くのではなく、「設計書（ドキュメント）」を先に書くワークフローが組み込まれています。これにより、AI との認識のズレを最小限に抑え、手戻りの少ない高品質な開発が可能になります

  2. 専門エージェントのチーム:
    Amplifier には、単なるコーダーだけでなく、「デザイナー」「アーキテクト」「セキュリティ担当」など、各分野に特化した専門エージェントが含まれています。これらのエージェントがそれぞれの視点からプロジェクトを支援します

  3. 自然言語によるツール作成:
    「このタスクをどう処理するか」という手順を自然言語で書くだけで、それを実行可能なツール（レシピ）として保存・再利用できます

Amplifier の導入

まだ Amplifier をセットアップしていない場合は、以下の手順でインストールします。

前提条件

  • OS: Linux, macOS, または Windows (WSL2 推奨)

  • Claude Code:

    curl -fsSL https://claude.ai/install.sh | bash

    詳細は 公式サイト を参照してください。

  • その他の必須ツール:

    • Python 3.11 以上
    • Node.js & pnpm
    • Git
    • uv (Python パッケージマネージャー)

Amplifier ディレクトリについて

Amplifier はホームディレクトリにクローンすることを推奨します。

# 推奨されるクローン場所
~/amplifier

これは、.claude/settings.json の additionalDirectories 設定が ~/amplifier を前提としているためです。

別の場所にクローンする場合は、.claude/settings.json を修正する必要があります（後述のトラブルシューティングを参照）。

インストール手順

  1. リポジトリのクローン:

    推奨: ホームディレクトリにクローン

    cd ~
git clone https://github.com/microsoft/amplifier.git amplifier
cd amplifier

    別の場所にクローンする場合:

    cd /path/to/your/directory
git clone https://github.com/microsoft/amplifier.git amplifier
cd amplifier

    この場合、後で .claude/settings.json の修正が必要です（トラブルシューティングセクションを参照）。

  2. 依存関係のインストール:

    make install
    Makefile の旧 Claude Code インストール手順について（補足情報）

    注意:
    2025-11-23 時点で、Makefile には古い Claude Code インストール手順（pnpm add -g @anthropic-ai/claude-code@latest）が含まれています。

    このチュートリアルでは、前提条件で案内した新しい公式インストール方法（curl -fsSL https://claude.ai/install.sh | bash）を使用してください。

    Makefile の修正方法:

    Makefile の 156-162 行目をコメントアウトします

    Makefile
    # 修正前
@pnpm add -g @anthropic-ai/claude-code@latest || { \
    echo "❌ Failed to install global packages."; \
    echo "   This may be a permissions issue. Try:"; \
    echo "   1. Run: pnpm setup && source ~/.bashrc (or ~/.zshrc)"; \
    echo "   2. Then run: make install"; \
    exit 1; \
}

# 修正後（行頭に # を追加）
# @pnpm add -g @anthropic-ai/claude-code@latest || { \
# 	echo "❌ Failed to install global packages."; \
# 	echo "   This may be a permissions issue. Try:"; \
# 	echo "   1. Run: pnpm setup && source ~/.bashrc (or ~/.zshrc)"; \
# 	echo "   2. Then run: make install"; \
# 	exit 1; \
# }

  3. 仮想環境の有効化:

    source .venv/bin/activate

  4. Claude Code の起動:

    claude

これで Amplifier を使う準備が整いました。

Step 0: プロジェクトアイデアの選定 (/ultrathink-task)

Amplifier の特徴の一つは、アイデア出しから実装まで一貫してサポートすることです。
まずは /ultrathink-task を使って、どんなプロジェクトを作るかブレインストーミングします。

実際のプロンプト例

Claude Code を起動したら、以下のように入力します。

/ultrathink-task Amplifierを初めて使う人向けの、学習プロジェクトのアイデアを3つ提案してください

条件:
- 1-2時間で完成できる
- Pythonで実装（UIはStreamlitやHTML/CSS/JSなど別言語可）
- Amplifierの機能（設計支援、AI による実装、デザイン改善）を体験できる
- 以下のコマンドを一通り体験できる：
  - /ddd:1-plan（計画立案）
  - /ddd:2-docs（設計ドキュメント作成）
  - /ddd:3-code-plan（実装計画）
  - /ddd:4-code（コード生成）
  - /designer（デザイン改善）
  - /ddd:5-finish（完了）

アイデアだけ出してください、まだ実装しないでください

筆者の環境では次のような提案がされました。

出力例

📝 アイデア 1: パーソナル日記アプリ

概要: シンプルな日記アプリで、Amplifier の基本ワークフローを体験

主な機能:

  • 日記エントリの作成・編集・削除
  • 日付ベースの表示と検索
  • 感情タグ付け（😊 Happy、😔 Sad、😤 Stressed など）
  • カレンダービューでの一覧表示

技術スタック:

  • バックエンド: Python（データ保存は JSON または SQLite）
  • UI: Streamlit（シンプル＆高速開発）または HTML/CSS/JS

Amplifier ワークフローでの学習ポイント:

  • /ddd:1-plan: データモデル（Entry、Tag）と機能の計画
  • /ddd:2-docs: モジュール設計（storage、models、ui）のドキュメント化
  • /ddd:3-code-plan: 実装順序（models → storage → ui）の計画
  • /ddd:4-code: AI によるコード生成
  • /designer: 感情タグの色使い、レイアウト、読みやすさの改善
  • /ddd:5-finish: クリーンアップとドキュメント完成

デザイン改善の見どころ:

  • エントリカードのレイアウト
  • 感情タグの視覚的な表現（色・アイコン）
  • カレンダービューの見やすさ
  • モバイルフレンドリーなレスポンシブデザイン

⏱️ アイデア 2: ポモドーロタイマー with 統計機能

概要: 生産性向上のための 25 分作業 + 5 分休憩のタイマーアプリ

主な機能:

  • タイマー（作業時間 25 分、短休憩 5 分、長休憩 15 分）
  • タイマー完了時の通知（音・ビジュアル）
  • 完了セッションの記録
  • 日別・週別の統計表示（完了回数、集中時間）
  • セッション履歴の表示

技術スタック:

  • バックエンド: Python（セッションデータは JSON 保存）
  • UI: HTML/CSS/JS（リッチなタイマーアニメーション）または Streamlit

Amplifier ワークフローでの学習ポイント:

  • /ddd:1-plan: タイマーの状態管理、データ永続化の設計
  • /ddd:2-docs: Timer、Session、Statistics モジュールの仕様
  • /ddd:3-code-plan: 状態管理 → タイマーロジック → UI → 統計の実装順序
  • /ddd:4-code: 複雑な状態遷移のコード生成
  • /designer: タイマーの視覚表現、プログレスバー、統計グラフのデザイン改善
  • /ddd:5-finish: パフォーマンスチェックと最終調整

デザイン改善の見どころ:

  • タイマーの円形プログレスバー
  • 残り時間の視覚的な表現
  • 作業/休憩モードの色の切り替え
  • 統計グラフ（棒グラフ、折れ線グラフ）のスタイリング
  • 通知のアニメーション効果

🔗 アイデア 3: シンプル URL 短縮サービス

概要: 長い URL を短い URL に変換し、アクセス統計も表示するツール

主な機能:

  • 長い URL を短縮 URL に変換
  • 短縮 URL から元の URL へのリダイレクト
  • 各 URL のクリック数統計
  • 短縮 URL 一覧の表示
  • オプション: カスタムエイリアス機能

技術スタック:

  • バックエンド: Python（Flask/FastAPI）、データ保存は JSON/SQLite
  • UI: HTML/CSS/JS（モダンなフォームデザイン）

Amplifier ワークフローでの学習ポイント:

  • /ddd:1-plan: URL 生成アルゴリズム、ストレージ設計、API 設計
  • /ddd:2-docs: URLShortener、Storage、Analytics モジュールの明確な責任分離
  • /ddd:3-code-plan: コア機能 → API → UI → 統計の順序
  • /ddd:4-code: ルーティング、URL 生成ロジック、統計集計のコード生成
  • /designer: 入力フォーム、結果表示、ダッシュボードの UI/UX 改善
  • /ddd:5-finish: セキュリティチェック（悪意のある URL 対策）と完了

デザイン改善の見どころ:

  • クリーンな入力フォーム（大きな入力欄、明確な CTA）
  • 結果表示のコピーボタン付きカード
  • 統計ダッシュボード（トップ URL、最近のクリック）
  • レスポンシブレイアウト
  • マイクロインタラクション（コピー成功時のフィードバック）

推奨する学習順序

  1. アイデア 1（日記アプリ）: 最もシンプル、基本的な CRUD 操作を学ぶ
  2. アイデア 2（ポモドーロ）: 状態管理とリアルタイム UI を学ぶ
  3. アイデア 3（URL 短縮）: API 設計とルーティングを学ぶ

いずれのプロジェクトも:

  • 1-2 時間で完成可能
  • DDD ワークフローを完全に体験
  • デザイン改善の重要性を実感
  • 実用的で理解しやすい

● どのアイデアに興味がありますか？選択していただければ、そのプロジェクトの実装を/ddd:1-plan から始めることができます！

今回は次の理由からポモドーロタイマーを選びました。

  • /designer コマンドを確認できる
  • 完成後すぐに使える
  • 実際の生産性向上に役立つ
  • 外部依存なし
    • API キー不要
    • ローカルで動作
    • ネットワークエラーの心配なし

Step 1: プロジェクトのセットアップ (Workspace Pattern)

現実のプロジェクト開発では、Amplifier 自体を「作業台」とし、そこに自分のプロジェクトを git submodule として追加する Workspace Pattern が推奨されます。
これにより、Amplifier の更新とプロジェクトの履歴をきれいに分離できます。

なぜ git submodule を使うのか？

Amplifier の機能（DDD ワークフロー、専門家エージェント）を使うには、Amplifier ディレクトリから claude コマンドを起動する必要があります。

しかし、プロジェクトを Amplifier ディレクトリ内に直接置くことで次の問題が発生します。

  • プロジェクトの変更と Amplifier の変更が同じ git 履歴に混ざる
  • Amplifier を更新するとプロジェクトに影響が出る可能性がある
  • チームでプロジェクトを共有しにくい

git submodule を使えば、これらの問題を解決できます。

git submodule とは？

git submodule は「git リポジトリの中に別の git リポジトリを含める仕組み」です。

このプロジェクトにおいては次のような位置づけになります。

  • Amplifier = 「作業台」（ツールが揃っている）
  • pomodoro-timer = 「作業中の部品」（プロジェクト）

作業台（Amplifier）の上で部品（プロジェクト）を加工しますが、部品自体は独立したリポジトリとして管理されます。

1. プロジェクトリポジトリの作成

まず、Amplifier の「外」にプロジェクトディレクトリを作成します。

# プロジェクト用のディレクトリを作成（Amplifierの外）
# 例: ホームディレクトリの projects フォルダに作成
mkdir -p ~/projects/pomodoro-timer
cd ~/projects/pomodoro-timer

# Gitリポジトリとして初期化
git init
git branch -M main

# 重要：最初のコミットを作成（これがないとsubmodule追加に失敗）
echo "# Pomodoro Timer" > README.md
git add README.md
git commit -m "Initial commit"

2. Amplifier に submodule として追加

次に、Amplifier ディレクトリに戻り、プロジェクトを submodule として追加します。

# Amplifierディレクトリへ移動
cd ~/amplifier

# ローカルファイルパスを許可（Amplifierリポジトリのみ）
git config --local protocol.file.allow always

# submoduleとして追加
# 注: /path/to/pomodoro-timer は実際のパスに置き換えてください
GIT_PROTOCOL_FROM_USER=1 git -c protocol.file.allow=always \
  submodule add file:///home/username/projects/pomodoro-timer pomodoro-timer

# 成功確認
ls pomodoro-timer/  # README.md が見えるはず

3. AGENTS.md の作成

プロジェクトディレクトリ内に AGENTS.md を作成します。これが AI との「契約書」になります。
Amplifier のルートディレクトリで claude を起動し、プロンプトで生成させます。

# Amplifierディレクトリで Claude Code を起動
cd ~/amplifier
claude

Claude が起動したら、以下のようにプロンプトを入力します。

ポモドーロタイマープロジェクトの AGENTS.md を作成してください。

プロジェクト概要

- ポモドーロテクニック（25分作業 + 5分休憩）を実践するタイマーアプリ
- セッションの記録と統計機能
- 生産性向上をサポート

主な機能

1. タイマー管理（作業25分、短休憩5分、長休憩15分）
2. タイマー完了時の通知
3. セッション記録と履歴表示
4. 日別・週別の統計表示

技術スタック（/ddd:1-plan で決定予定）

- Backend: Python
- Frontend: Streamlit または HTML/CSS/JavaScript
- Data Storage: JSON (ローカルファイル)

ファイルは @pomodoro-timer/AGENTS.md に保存してください。

入力すると、Amplifier が AGENTS.md を生成します。内容を確認して問題なければ、プロジェクトディレクトリでコミットします。

# Amplifierディレクトリ (~/amplifier) から submodule へ移動
cd pomodoro-timer
git add AGENTS.md
git commit -m "Add AGENTS.md"
生成された AGENTS.md の例（クリックして展開）

筆者の環境では次のようなガイダンスが生成されました。

  • プロジェクト概要と学習目標 - DDD ワークフローの完全体験
  • 親プロジェクト（Amplifier）の設計哲学の継承 - Ruthless Simplicity、Modular Design
  • 技術スタック選択のガイダンス - Streamlit vs HTML/CSS/JavaScript の比較
  • 詳細な設計原則
    • タイマー状態管理（State Enum パターンの具体例）
    • データ永続化（Incremental Processing Pattern）
    • 通知設計（ユーザーコントロール重視）
    • 統計の明確性（意味のあるデータのみ）
    • UI/UX 優先順位（視覚階層、モーション設計、アクセシビリティ）
  • DDD ワークフロー各フェーズでの期待事項 - ddd:1〜6 までの具体的ガイダンス
  • テスト戦略 - 60% unit, 30% integration, 10% manual
  • よくある落とし穴と解決策 - Timer Drift、Blocking UI、Data Loss（コード例付き）
  • アクセシビリティ要件 - 視覚、運動、聴覚、認知の各側面をカバー
  • パフォーマンス目標 - 具体的な数値（タイマー更新 10Hz、起動 1 秒以内など）

これで、プロジェクトのセットアップは完了です。

トラブルシューティング

エラー 1: fatal: transport 'file' not allowed

原因: git 2.38 以降、セキュリティのため file プロトコルがデフォルトで制限されています。

解決策:

# Amplifierディレクトリで実行
git config --local protocol.file.allow always

--local を使うことで、設定は Amplifier リポジトリのみに適用され、セキュリティリスクが限定的になります。

エラー 2: fatal: You are on a branch yet to be born

原因: プロジェクトリポジトリに最初のコミットがありません。

解決策:

# プロジェクトディレクトリに移動（実際のパスに置き換えてください）
cd ~/projects/pomodoro-timer
echo "# Pomodoro Timer" > README.md
git add README.md
git commit -m "Initial commit"

エラー 3: fatal: 'pomodoro-timer' does not have a commit checked out

原因: 以前の失敗した submodule 追加の残骸が残っています。

解決策:

# Amplifierディレクトリで実行
git submodule deinit -f pomodoro-timer 2>/dev/null || true
rm -rf pomodoro-timer .git/modules/pomodoro-timer
git rm -f pomodoro-timer 2>/dev/null || true
git config -f .gitmodules --remove-section submodule.pomodoro-timer 2>/dev/null || true

# その後、再度submodule追加を実行

DDD の原則と重要コンセプト

ここでは、DDD ワークフローを実践する前に理解しておくべき重要な原則とコンセプトを補足します。

DDD の原則: 「ドキュメントが仕様である」

DDD ワークフローの最も重要な原則は、「ドキュメントが常に真実の源（Single Source of Truth）」です。

従来の開発手法の問題点

  • コードが先に書かれ、ドキュメントは後から追加される（または追加されない）
  • 時間が経つにつれて、ドキュメントとコードが乖離する
  • AI がコードを生成する際、古いドキュメントを参照して誤った実装を生成する

DDD のアプローチ

  1. 最初にドキュメントを書く: 何を作るか、どう動くべきかを明確に記述
  2. ドキュメントからコードを生成: AI がドキュメントを読み、それに従ってコードを生成
  3. ドキュメントが変更されたら、コードを再生成: 常にドキュメントとコードが同期

この原則により、プロジェクトの意図が常に明確で、AI が正確な実装を生成できます。

なぜ DDD が機能するのか: 4 つの理由

1. コンテキストポイズニングの防止

コンテキストポイズニング（Context Poisoning）とは？

AI がコード生成時に、意図しない情報（古いコード、無関係なファイル、システムプロンプト等）を参照してしまい、誤った出力を生成する現象です。

例:

  • 古い README に「この機能は未実装」と書かれていると、AI が新しいコードを生成せず「未実装」と返す
  • 異なるバージョンのドキュメントが混在し、AI がどちらを信頼すべきか判断できない
  • システムプロンプトに含まれる内部情報を AI が出力に含めてしまう

DDD による解決:

  • ddd:2 でドキュメントを先に更新し、コンテキストをクリーンにする
  • ddd:4 でドキュメントに基づいてコードを生成するため、古い情報に引っ張られない

2. 明確な契約を最初に（Contract First）

ドキュメント（特に README、API 仕様等）は、コードとユーザーの間の「契約」です。

  • 先にドキュメントを書くことで、実装前に設計の問題を発見できる
  • AI がドキュメントを読んで実装するため、契約違反が起きにくい
  • レビュアーがドキュメントを見れば、実装の意図が明確に分かる

3. AI 最適化

LLM は長いコードよりも明確なドキュメントを読む方が得意です。

  • ドキュメントを優先することで、AI が正確な実装を生成しやすくなる
  • コード生成時に必要な情報だけを AI に渡すため、精度が向上
  • ドキュメントは人間にとっても読みやすいため、レビューが容易

4. ドキュメントとコードが決して乖離しない

従来の手法では、コードが更新されてもドキュメントが更新されないことが頻繁にあります。

  • ドキュメントが変更されない限り、コードも変更されない
  • ドキュメントを更新すれば、コードも自動的に再生成される
  • 常にドキュメントが最新の仕様を反映

DDD で知っておくべき重要コンセプト

Context Poisoning（コンテキストポイズニング）

定義: AI が意図しない情報（古いコード、システムプロンプト、無関係なファイル等）を参照して誤った出力を生成する現象。

  • 古いドキュメントと新しいドキュメントが混在すると、AI がどちらを信頼すべきか判断できない
  • 削除したはずの機能がコードに復活する
  • 一貫性のない実装が生成される

DDD での対策として、 ddd:2 でドキュメントを先に更新し、古い情報を削除することでこれを防ぎます。

Retcon Writing（レトコンライティング）

定義: 「Retroactive Continuity（遡及的連続性）」の略。実装後に「実はこうだった」と後付けでドキュメントを書くこと。

  • ドキュメントが実装の「言い訳」になる
  • 設計上の問題が隠蔽される
  • 将来の変更が困難になる

DDD での原則として、これは絶対に避けるべき行為です。常にドキュメント → コードの順序を守ります。

File Crawling（ファイルクロール）

定義: AI がプロジェクト内の複数ファイルを体系的に読み込んで情報を収集すること。

  • 大規模プロジェクトでは、100 以上のファイルを更新する必要がある
  • AI のコンテキストウィンドウには限界がある（一度に 100 ファイルは保持できない）

DDD ではこのように対応します。

  • ddd:2 で外部チェックリストを使用し、順次処理する
  • 各ファイルを処理したらチェックマークを付け、進捗を追跡
  • トークン効率が 99.5%向上し、再開も可能

Maximum DRY（Don't Repeat Yourself）

定義: 情報の重複を最小限にする原則。

DDD での実践

  • ドキュメントが唯一の真実の源（Single Source of Truth）
  • コードはドキュメントから生成されるため、情報が重複しない
  • 変更は常にドキュメントから始まり、コードに反映される

具体例

  • API エンドポイントの仕様は DESIGN.md に一度だけ記述
  • テストケースもドキュメントから生成
  • README の使用例もドキュメントと一貫

Step 1.5: DDD ワークフローの理解とナビゲーション

DDD ワークフローを開始する前に、全体像を把握し、進捗を確認するための便利なコマンドを知っておきましょう。

/ddd:0-help - ワークフロー全体ガイド

DDD ワークフローのヘルプを表示します。初めて DDD を使う場合や、全体の流れを再確認したいときに便利です。

/ddd:0-help

このコマンドで確認できる内容:

  • DDD の原則（ドキュメントが仕様、コードは実装）
  • 5 つのフェーズの詳細説明
  • ユーティリティコマンドの一覧
  • ステート管理とアーティファクト
  • 実際の使用例
  • トラブルシューティング

いつ使うか:

  • DDD を初めて使う前に全体像を理解したい
  • 各フェーズの詳細な説明が必要
  • ワークフローの原則や哲学を確認したい
  • よくあるトラブルシューティングを参照したい

/ddd:status - 進捗確認と次のステップ

現在の DDD ワークフローの進捗状況を確認し、次に実行すべきコマンドが確認できます。

/ddd:status

このコマンドで確認できる内容:

  • 現在のフェーズ: どのフェーズにいるかを自動検出
  • 作成済みアーティファクト: plan.md, docs_status.md などの有無
  • Git 状態: 未コミット変更、未プッシュコミット
  • 次の推奨コマンド: 現在の状態に基づいた次のステップ

表示される情報の例:

Phase Detection:
Plan created
Docs updated
Code planned
Code not implemented

Status: Phase 3 complete (Code planned)
Next: Implement code with /ddd:4-code

いつ使うか:

  • 作業を中断して、どこまで進んでいるか忘れた
  • 新しいセッションを開始して、続きから再開したい
  • 次に何をすべきか確認したい
  • Git 状態を確認したい

実践例：DDD ワークフローのナビゲーション

シナリオ 1: 初めて DDD を使う

# 1. まずヘルプで全体像を理解
/ddd:0-help

# 2. 計画から開始
/ddd:1-plan ポモドーロタイマーを実装したい

# 3. 進捗確認（オプション）
/ddd:status

シナリオ 2: 作業を中断して再開

# 昨日の続きから再開したいが、どこまで進んだか忘れた
/ddd:status

# 出力例:
# Status: Phase 2 in progress or awaiting commit
# Next: Review and commit docs, then /ddd:3-code-plan

# 推奨に従って続行
git add README.md DESIGN.md
git commit -m "docs: Update documentation"
/ddd:3-code-plan

補足: 会話履歴も復元したい場合

# Conversation Transcripts 機能を使う
/transcripts

# 過去の会話全体が復元される
# DDD ワークフローには必須ではないが、詳細な議論の文脈を確認したい場合に便利

ポイント:

  • /transcripts で過去の会話全体を復元できる
  • セッションコンパクション時に .data/transcripts/ に自動保存される
  • ファイルベースのワークフローで十分な場合は不要

シナリオ 3: ワークフローの途中で迷った

# 現在地を確認
/ddd:status

# もっと詳しい情報が必要なら
/ddd:0-help

これらのコマンドを活用することで、DDD ワークフローをスムーズに進められます。

よくあるワークフローシナリオ

DDD ワークフローは新機能開発だけでなく、様々な開発タスクに適用できます。ここでは代表的なシナリオを紹介します。

シナリオ 1: 新機能開発（本チュートリアルの例）

状況: 新しいポモドーロタイマーコンポーネントを追加したい

ワークフロー:

# Phase 1: 計画
/ddd:1-plan ポモドーロタイマーを実装したい

# Phase 2: ドキュメント
/ddd:2-docs
# → README.md, DESIGN.md などを更新
# → Git コミット

# Phase 3: コード計画
/ddd:3-code-plan

# Phase 4: コード実装
/ddd:4-code
# → 実装とテスト
# → Git コミット

# Phase 5: 完了
/ddd:5-finish

特徴: 全フェーズを順番に実行する標準的なワークフロー

シナリオ 2: バグ修正

状況: タイマーが 0 秒になっても停止しない不具合を修正したい

ワークフロー:

# Phase 1: 問題分析と修正計画
/ddd:1-plan タイマーが0秒で停止しない問題を修正する

# Phase 2: ドキュメント更新（バグ修正は最小限）
/ddd:2-docs
# → README.md のトラブルシューティングに追記（オプション）
# → DESIGN.md の仕様を明確化（必要な場合のみ）
# → Git コミット

# Phase 3: コード計画（修正範囲の特定）
/ddd:3-code-plan

# Phase 4: コード修正とテスト
/ddd:4-code 既存のテストを確認し、バグを修正してください
# → バグ修正
# → 回帰テスト追加
# → Git コミット

# Phase 5: 完了
/ddd:5-finish

特徴: ddd:2 のドキュメント更新は最小限。修正内容の記録に重点を置く

シナリオ 3: ドキュメントのみ更新

状況: ポモドーロタイマーの使い方ガイドを拡充したい（コード変更なし）

ワークフロー:

# Phase 1: ドキュメント改善計画
/ddd:1-plan README.mdに初心者向けのステップバイステップガイドを追加する

# Phase 2: ドキュメント更新
/ddd:2-docs
# → README.md を大幅に拡充
# → サンプルスクリーンショット追加
# → Git コミット

# Phase 3 & 4 はスキップ（コード変更なし）

# Phase 5: 完了
/ddd:5-finish

特徴: ddd:3-4 をスキップして ddd:2 から直接 ddd:5 へ。/ddd:status で次のステップを確認します。

シナリオ 4: リファクタリング

状況: タイマーロジックを別モジュールに分離してテストしやすくしたい

ワークフロー:

# Phase 1: リファクタリング計画
/ddd:1-plan タイマーロジックをカスタムフックに分離する

# Phase 2: ドキュメント更新
/ddd:2-docs
# → DESIGN.md にアーキテクチャ変更を記載
# → README.md に新しい内部構造を記載
# → Git コミット

# Phase 3: コード計画（影響範囲の特定）
/ddd:3-code-plan

# Phase 4: リファクタリング実行
/ddd:4-code テストを維持しながら、タイマーロジックを抽出してください
# → 段階的にコード移動
# → 各ステップでテスト実行
# → Git コミット

# Phase 5: 完了
/ddd:5-finish

特徴: ddd:2 で「外部仕様は変わらないが、内部構造が変わる」ことを明確に記載。ddd:4 で慎重に進める

シナリオ 5: 既存機能の改善

状況: ポモドーロタイマーに通知音を追加したい（既存機能の拡張）

ワークフロー:

# Phase 1: 拡張計画
/ddd:1-plan タイマー完了時に通知音を再生する機能を追加

# Phase 2: ドキュメント更新
/ddd:2-docs
# → README.md に新機能の使い方を追記
# → DESIGN.md に音声ファイル管理方針を追記
# → Git コミット

# Phase 3: コード計画
/ddd:3-code-plan

# Phase 4: 機能追加
/ddd:4-code
# → 音声ファイル追加
# → 通知音再生ロジック実装
# → 新機能のテスト追加
# → Git コミット

# Phase 5: 完了
/ddd:5-finish

特徴: 既存機能を壊さずに新機能を追加。ddd:2 で新旧機能の境界を明確にする

シナリオ選択のヒント

シナリオ ddd:2 の重点 ddd:3-4 の重点 Git コミット戦略
新機能開発 仕様定義 実装とテスト 機能単位で分割
バグ修正 問題の記録 原因特定と修正 小さく頻繁に
ドキュメントのみ 全て スキップ ドキュメントのみ
リファクタリング 内部構造変更の記録 段階的移行 ステップごと
機能拡張 新旧機能の境界 互換性維持 機能追加のみ

共通のベストプラクティス:

  • /ddd:status で常に現在地を確認
  • ddd:2 で変更内容を明確に記録
  • 各フェーズ完了後に Git コミット
  • /ddd:5-finish で最終確認とクリーンアップ
DDD ワークフローのトラブルシューティング

DDD ワークフロー中によくある問題とその解決方法を紹介します。

問題: "どこにいるかわからない"

症状: 作業を中断して戻ってきたが、どのフェーズにいるか忘れてしまった

解決方法:

/ddd:status

このコマンドが現在のフェーズを自動検出し、次にすべきことを教えてくれます。

出力例:

Phase Detection:
Plan created
Docs updated
Code not planned

Status: Phase 2 complete (Docs committed)
Next: Create code plan with /ddd:3-code-plan

問題: "計画でミスをした"

症状: ddd:1 で作成した ai_working/ddd/plan.md の内容が間違っていた

解決方法 1: 計画ファイルを直接編集

# エディタで計画を修正
vim ai_working/ddd/plan.md

# または VS Code で開く
code ai_working/ddd/plan.md

解決方法 2: /ddd:1-plan を再実行

/ddd:1-plan タイマーに休憩時間の設定機能を追加（長期休憩と短期休憩）

新しい計画が plan.md を上書きします。既存のドキュメントやコードには影響しません。

ヒント: Phase 2 に進む前に plan.md を必ず確認しましょう。

問題: "ドキュメントが正しくない"

症状: /ddd:2-docs で生成されたドキュメントが期待と違う

解決方法: ddd:2 にとどまり、フィードバックを提供して反復

# Claude にフィードバック
「README.md の使い方セクションに、初心者向けの詳しい説明を追加してください」

# 満足するまで繰り返す
「DESIGN.md にタイマー停止時の状態遷移図を追加してください」

# 完璧になったら Git コミット
git add README.md DESIGN.md
git commit -m "docs: Add detailed user guide and state diagram"

# 次のフェーズへ
/ddd:3-code-plan

重要: Git コミットする前にドキュメントを完璧にしましょう。ddd:3-4 はこのドキュメントを元に実装されます。

問題: "コードが動作していない"

症状: /ddd:4-code で実装されたコードにバグがある、またはテストが失敗する

解決方法: ddd:4 にとどまり、フィードバックを提供して反復

# 具体的なフィードバックを提供
「タイマーが0秒になっても停止しません。useEffect の依存配列を確認してください」

# テスト結果を共有
「npm test の結果:
 FAIL  src/components/Timer.test.tsx
   ● Timer › stops at zero
     expect(received).toBe(expected)
     Expected: 0
     Received: -1」

# 修正を確認
「修正ありがとうございます。もう一度 npm test を実行します」

# すべてのテストが通ったら Git コミット
git add src/
git commit -m "feat: Implement pomodoro timer with tests"

# 次のフェーズへ
/ddd:5-finish

ヒント:

  • エラーメッセージやテスト結果を Claude と共有する
  • 一度に 1 つの問題を修正する
  • 各修正後にテストを実行する

問題: "最初からやり直したい"

症状: 計画も実装も全部間違っていた。完全にやり直したい

解決方法: DDD ワークフローの状態をリセット

# ai_working/ddd/ ディレクトリを削除
rm -rf ai_working/ddd/

# 最初から開始
/ddd:1-plan [新しい機能の説明]

注意:

  • この操作は ai_working/ddd/ 内のすべてのファイル（plan.md, code_plan.md, docs_status.md）を削除します
  • 実際のコードやドキュメント（README.md, DESIGN.md, src/ など）は削除されません
  • Git でコミット済みの変更は影響を受けません

より安全な方法:

# バックアップを作成
mv ai_working/ddd ai_working/ddd.backup.$(date +%Y%m%d_%H%M%S)

# 新しいワークフローを開始
/ddd:1-plan [新しい機能の説明]

問題: "Git コミットメッセージが分からない"

症状: 各フェーズで何をコミットすべきか、どんなメッセージにすべきか分からない

解決方法: フェーズごとの推奨コミット戦略

ddd:1 完了時 (計画のみ - コミット不要):

# ai_working/ddd/plan.md は通常コミットしない
# これは一時的な作業ファイル

ddd:2 完了時 (ドキュメント):

git add README.md DESIGN.md
git commit -m "docs: Add pomodoro timer specification and design"

ddd:3 完了時 (コード計画 - コミット不要):

# ai_working/ddd/code_plan.md も通常コミットしない

ddd:4 完了時 (実装):

git add src/components/PomodoroTimer.tsx src/hooks/useTimer.ts
git commit -m "feat: Implement pomodoro timer component

- Add PomodoroTimer component with start/pause/reset
- Add useTimer custom hook for timer logic
- Add tests for timer functionality"

ddd:5 完了時 (クリーンアップ):

# /ddd:5-finish が自動的に提案します

問題: "/ddd:status の出力が理解できない"

症状: /ddd:status の出力が何を意味するのか分からない

解決方法: 出力の読み方を理解する

Phase Detection:
Plan created              # ai_working/ddd/plan.md が存在
Docs updated             # docs_status.md が存在（Phase 2 完了）
Code planned             # code_plan.md が存在（Phase 3 完了）
Code not implemented     # Phase 4 未完了
                           # または Git に未コミット変更がある

Git Status:
• Uncommitted changes: 3 files  # git status で確認可能
• Unpushed commits: 2           # git push していないコミット

Status: Phase 3 complete (Code planned)
Next: Implement code with /ddd:4-code

各フェーズの判定基準:

  • ddd:1: ai_working/ddd/plan.md 存在
  • Phase 2: ai_working/ddd/docs_status.md 存在
  • ddd:3: ai_working/ddd/code_plan.md 存在
  • ddd:4: 上記すべて存在 + Git に未コミット変更がない

トラブルシューティングのベストプラクティス

  1. 問題が起きたら、まず /ddd:status を実行

    • 現在地を確認
    • 次のステップを確認

  2. 各フェーズで焦らない

    • ddd:2: ドキュメントが完璧になるまで反復
    • ddd:4: コードが動作するまで反復
    • 満足してから次のフェーズへ進む

  3. Git を活用

    • 各フェーズ完了後に必ずコミット
    • 問題があれば git reset --hard で戻れる
    • ブランチを使って実験する

  4. ai_working/ddd/ は一時ファイル

    • Git にコミットしない（.gitignore に追加済み）
    • 削除しても実際のコードやドキュメントは無事
    • やり直したければ安全に削除できる

  5. Claude にフィードバックを提供

    • エラーメッセージを共有
    • 期待と実際の違いを説明
    • 具体的な修正指示を出す

これらのトラブルシューティング方法を活用して、DDD ワークフローをスムーズに進めましょう。

Step 2: 計画と設計 (DDD ddd:1 & 2)

ここから Amplifier の DDD ワークフローを使用します。
Amplifier のルートディレクトリで claude コマンドを実行して、Claude Code を起動します。

claude

Claude が起動したら、まず作業対象のプロジェクトを伝えます。

I'm working on @pomodoro-timer/

1. 計画の立案 (/ddd:1-plan)

コンテキストが設定されたら、機能の実装計画を立てます。

/ddd:1-plan ポモドーロタイマーを実装したい。25分作業・5分休憩のタイマー機能、セッション記録、統計表示を含める。技術スタックの推奨も含めて計画してください。

Amplifier は pomodoro-timer/AGENTS.md を読み込み、以下を分析して ai_working/ddd/plan.md を生成します：

  • 必要な機能の洗い出し
  • 技術スタックの推奨（Streamlit vs HTML/JS）
  • モジュール構成の提案
  • 実装の優先順位
実際に生成されたプラン

主な内容:

  • 問題の定義: ポモドーロテクニックを実装し、集中力と生産性を向上させる
  • 提案するソリューション: Streamlit を使ったデスクトップアプリ
  • アーキテクチャ: モジュラー設計（ビジネスロジック、ストレージ、UI 層の分離）
  • データモデル: Session（UUID、タイムスタンプ、完了状態）と TimerConfig
  • 哲学との整合性:
    • Ruthless Simplicity（クラウド同期やタスク管理は含めない）
    • Modular Design（各モジュールは独立して動作）
    • Zero-BS Principle（プレースホルダーやスタブなし）
  • 実装ロードマップ: ddd:2（ドキュメント）→ ddd:3（コード計画）→ ddd:4（実装）→ ddd:5（完了）
  • テスト戦略: 60% ユニットテスト、30% 統合テスト、10% 手動テスト、80%+カバレッジ目標

内容を確認し、問題なければ承認します。

2. ドキュメントの作成 (/ddd:2-docs)

次に、計画に基づいて設計ドキュメントを作成します。

/ddd:2-docs

このコマンドを実行すると、Amplifier は以下のファイルを自動的に生成・更新します：

  • README.md: ユーザー向けドキュメント（機能、インストール、使い方）
  • DESIGN.md: アーキテクチャと設計決定
  • .gitignore: Git 管理から除外するファイル
  • pyproject.toml: プロジェクト設定
実際に生成されたファイル

生成されたファイル一覧 (ai_working/ddd/docs_index.txt)：

[x] pomodoro-timer/README.md
[x] pomodoro-timer/DESIGN.md
[x] pomodoro-timer/.gitignore
[x] pomodoro-timer/pyproject.toml

README.md

主な内容：

  • 特徴（25 分作業+5 分休憩、セッション記録、統計表示、OS 通知、キーボードショートカット）
  • インストール（Python 3.11+、uv）
  • 使い方（基本操作、キーボードショートカット、タイマーサイクル）
  • 設定（デフォルト値のカスタマイズ）
  • データ保存（sessions.json の構造）
  • 統計（今日の集中時間、完了ポモドーロ数、連続日数、週間概要）
  • トラブルシューティング
  • 開発（テスト実行、コード品質チェック、プロジェクト構造）
  • アクセシビリティ（高コントラスト、キーボードナビゲーション）

DESIGN.md

主な構成：

  • Architecture Overview: レイヤー化されたアーキテクチャ図（UI Layer → Business Logic Layer → Storage Layer → JSON）
  • Design Decisions:
    • Streamlit vs HTML/JS（開発速度と技術スタック統一のため Streamlit 採用）
    • JSON vs Database（シンプルさとプライバシーのため JSON 採用）
    • Timer 実装戦略（ドリフト対策としてターゲット時刻ベース）
  • Module Specifications: timer.py, storage.py, stats.py, notifications.py, app.py の責務と公開インターフェース
  • Data Flow: 状態管理とデータの流れ
  • State Machine: タイマーの状態遷移（IDLE → RUNNING → PAUSED → COMPLETED）
  • Implementation Patterns: Timer Drift 対策、Notification、Statistics 計算
  • Philosophy Alignment: Ruthless Simplicity、Modular Design、Zero-BS Principle

生成されたドキュメントを確認し、問題なければ Git にコミットします。

# Amplifierディレクトリ (~/amplifier) から submodule へ移動
cd pomodoro-timer
git status
git add README.md DESIGN.md .gitignore pyproject.toml
git commit -m "docs: Add project documentation (Phase 2)"

Step 3: 実装 (DDD ddd:3 & 4)

設計が固まったら、コードの実装に移ります。

3. コード変更の計画 (/ddd:3-code-plan)

実装する前に、どのファイルをどう変更するかを計画します。

/ddd:3-code-plan

Amplifier は「どのファイルを作成し、どの関数を実装するか」という詳細な計画を提示します。

実際に生成されたコード計画

主な内容：

ddd:3: 実装計画の概要

  • 6 つのコアモジュール + Streamlit UI + テストスイート
  • 増分コミット戦略（モジュールごとに実装・テスト・コミット）
  • 統合テストとマニュアルテスト

モジュール別実装計画：

  1. pomodoro/models.py: データモデル（Session, TimerConfig, TimerState, SessionType）
  2. pomodoro/timer.py: タイマーコアロジック（PomodoroTimer クラス）
  3. pomodoro/storage.py: データ永続化（SessionStorage クラス、JSON 読み書き）
  4. pomodoro/stats.py: 統計計算（SessionStatistics クラス、日次・週次集計）
  5. pomodoro/notifications.py: OS 通知（NotificationManager クラス）
  6. ui/app.py: Streamlit UI（タイマー表示、統計ダッシュボード）

テスト戦略：

  • 各モジュールに対応するユニットテスト（60%目標）
  • 統合テスト（30%目標）
  • マニュアルテスト（10%目標）
  • pytest + pytest-cov でカバレッジ 80%以上を目指す

実装順序：
models.py → storage.py → timer.py → stats.py → notifications.py → app.py → tests

計画を確認し、問題なければ次のフェーズに進みます。

4. コーディング (/ddd:4-code)

計画を承認したら、実際にコードを記述します。

/ddd:4-code

実装の進め方: チャンク単位の承認とコミット

/ddd:4-code は、実装を複数のチャンクに分割し、チャンクごとにユーザー承認とコミットを促します。

  • 段階的な進行: 基盤から段階的に構築され、各ステップで動作確認できる
  • 早期のフィードバック: 問題があればチャンク単位で修正可能
  • Git 履歴の明確化: 各チャンクの意図が明確なコミットメッセージで記録される
  • DDD の増分実装戦略: DESIGN.md で定義された戦略が実際に実行される

実装チャンクの構成

各チャンクは依存関係を考慮して順序付けられています：

Chunk 1: Data Foundation (models.py + tests)

  • データモデルの定義（Session, TimerConfig, TimerState, SessionType）
  • 基盤となる型定義とバリデーション
  • ユニットテスト

Chunk 2: Persistence Layer (storage.py + tests)

  • JSON 形式でのセッションデータ永続化
  • Incremental Processing Pattern（失敗時の部分保存）
  • ファイル I/O のエラーハンドリング
  • ユニットテスト

Chunk 3: Notifications (notifications.py)

  • OS 通知の統合（Linux/macOS/Windows 対応）
  • ユーザーコントロール（有効/無効切り替え）
  • フォールバック機構

Chunk 4: Timer Core Logic (timer.py + tests)

  • PomodoroTimer クラス（タイマー状態管理）
  • Timer Drift 対策（ターゲット時刻ベース）
  • 状態遷移（IDLE → RUNNING → PAUSED → COMPLETED）
  • ユニットテスト

Chunk 5: Statistics (stats.py + tests)

  • SessionStatistics クラス（日次・週次集計）
  • 完了セッション数、集中時間、連続日数の計算
  • ユニットテスト

Chunk 6: UI Components (timer_display.py, stats_display.py)

  • Streamlit コンポーネント（タイマー表示、統計ダッシュボード）
  • リアルタイム更新（st.empty()使用）
  • 視覚的フィードバック

Chunk 7: Main Application (app.py)

  • アプリケーションエントリーポイント
  • 全モジュールの統合
  • セッション状態管理

実際の実行フロー

  1. Amplifier がチャンクを提示 - 「Chunk 1: Data Foundation」の実装内容が表示される
  2. ユーザーが承認 - 内容を確認し、問題なければ承認
  3. コード生成 - Amplifier がファイルを作成・編集
  4. コミット承認 - Amplifier がコミット内容を提示し、ユーザーに承認を求める
  5. 次のチャンクへ - Chunk 2, 3, ... と順に進行

/ddd:4-code で生成されたドキュメント

筆者の環境では、Amplifier が自動的に以下のドキュメントを生成しました。

TEST_REPORT.md, README.md(更新)の生成例

TEST_REPORT.md - テスト実行結果レポート

README.md - プロジェクトの使い方とセットアップガイド

これらのドキュメントは /ddd:4-code の最終ステップで自動生成され、プロジェクトの完成度を高めます。

動作確認

全チャンクの実装とコミットが完了したら、動作確認します。

# Amplifierディレクトリ (~/amplifier) から submodule へ移動
cd pomodoro-timer
uv run streamlit run ui/app.py

ポモドーロタイマーアプリケーション（初期実装）
/ddd:4-code で生成された初期実装 - 基本機能は動作するが、デザインはシンプル

基本的な機能は動作していますが、デザインをさらに磨き込むために /designer を使います。

Step 4: デザインの磨き込み (/designer)

Amplifier にはデザイン専門の Designer Agent がいます。

/designer ポモドーロタイマーの各モード（作業時間、短休憩、長休憩）を視覚的に明確に区別できるデザインを提案してください

Designer Agent は UI 適切にアップデートします。

/designer の使い方

具体的な指示を出すほど、良い結果が得られます：

# 悪い例
/designer きれいにして

# 良い例（実際に使用した指示）
/designer ポモドーロタイマーの各モード（作業時間、短休憩、長休憩）を視覚的に明確に区別できるデザインを提案してください
実際の `/designer` 実行結果

component-designer エージェントが、各モードを視覚的に明確に区別できるデザインを提供してくれました。

📋 デザイン提案のサマリー

各モードの視覚的表現

🍅 作業時間（Work）

  • 色：深い緑 (#2E7D32)
  • 感情：エネルギッシュ、集中、「進んでいる」確信
  • コントラスト比：10.5:1（AAA 準拠）

☕ 短休憩（Short Break）

  • 色：明るい青 (#0288D1)
  • 感情：軽やか、リフレッシュ、「すぐ戻る」軽い解放感
  • コントラスト比：5.2:1（AA 準拠）

🌴 長休憩（Long Break）

  • 色：温かいオレンジ (#F57C00)
  • 感情：深いリラックス、完全休息、「しっかり休める」安心感
  • コントラスト比：4.8:1（AA 準拠）

⏸️ 一時停止（Paused）

  • 色：琥珀色 (#FFA726)
  • 感情：注意、待機状態、「中断している」明確な認識
  • コントラスト比：6.3:1（AA 準拠）

アクセシビリティの三重識別システム

  1. 色 - 緑、青、オレンジ、琥珀色
  2. 絵文字 - 🍅, ☕, 🌴, ⏸️
  3. テキストラベル - 「作業中」「短い休憩」「長い休憩」「一時停止中」

評価

  • 総合評価: 9.3/10
  • 視覚的明確さ: 10/10
  • 感情的適切さ: 9/10
  • アクセシビリティ: 10/10
  • 実装可能性: 9/10
  • 細部への配慮: 9/10

提案されたコードは、pomodoro/ui/timer_display.py にそのまま統合できる形で提供されました。

Step 5: 完了 (/ddd:5-finish)

機能が動作し、デザインも満足できたら、タスクを完了します。

/ddd:5-finish

/ddd:5-finish が実行する 7 つのステップ

このコマンドは、プロジェクトを本番環境にデプロイできる状態にするための仕上げ処理を行います。

Step 1: 一時ファイルのクリーンアップ

  • ai_working/ddd/ ディレクトリの削除
  • テストアーティファクト（__pycache__, .pytest_cache など）の削除
  • デバッグコードやコメントアウトされたコードの削除

Step 2: 最終検証

  • make check の実行（lint、format、type check）
  • git status の確認
  • コミット履歴の表示

Step 3: 残りの変更をコミット

未コミットの変更がある場合、Amplifier がコミットを提案します。

ユーザー承認が必要 - コミット内容を確認し、承認してください

Step 4: リモートへのプッシュ

ローカルコミットをリモートリポジトリにプッシュします。

ユーザー承認が必要 - プッシュ前に承認を求められます

Step 5: Pull Request 作成

GitHub 上で Pull Request を作成します。

ユーザー承認が必要 - PR 作成前に承認を求められます

PR 本文は `plan.md` の内容から自動生成されます：

- 問題の定義
- 提案するソリューション
- 実装の詳細
- テスト計画

Step 6: Post-Cleanup チェック

最終的なワークスペースの状態を検証します。

Step 7: 最終サマリー生成

プロジェクト全体の完了サマリーを生成します。

これで一連の DDD ワークフローは完了です。

まとめ

Amplifier を使った開発は、「アイデア出し」→「要件定義」→「設計」→「実装」→「デザイン改善」 というサイクルを回せます。

  1. /ultrathink-task でプロジェクトアイデアをブレインストーミング
  2. Workspace Pattern（git submodule）でプロジェクトをセットアップ
  3. /ddd:1-plan で計画立案と技術スタック決定
  4. /ddd:2-docs で設計ドキュメント作成
  5. /ddd:3-code-plan で実装計画
  6. /ddd:4-code でコード生成
  7. /designer で UI/UX の磨き込み
  8. /ddd:5-finish で完了処理

Amplifier の強み

  • ドキュメント駆動: AGENTS.md や ARCHITECTURE.md を先に書くことで、AI がコンテキストを理解し、高精度なコード生成が可能
  • 専門家エージェント: デザイナー、アーキテクトなど、各分野の専門家が協力
  • Iterative な改善: チャットで要望を伝えるだけで、何度でも改善可能

DDD ワークフロー

DDD ワークフローの原則を振り返ります。

ドキュメントが仕様である

従来の開発では、コードが先に書かれ、ドキュメントは後から追加されます。時間が経つにつれてドキュメントとコードが乖離し、AI が古いドキュメントを参照して誤った実装を生成してしまいます。

DDD では次のようにドキュメントとコードが決して乖離しません。

  1. 最初にドキュメントを書く（ddd:2）
  2. ドキュメントからコードを生成（ddd:4）
  3. ドキュメントが変更されたら、コードを再生成

なぜ DDD が機能するのか

  1. Context Poisoning の防止: 不整合なドキュメントの混在を防ぎ、単一の信頼できる情報源を維持
  2. Contract First: 実装の複雑さの前に設計を明確化し、レビュー可能な設計を実現
  3. AI 最適化: LLM はコードよりもドキュメントから学習しやすく、明確な仕様で推測の余地を排除
  4. 同期の保証: ドキュメントが先、コードがドキュメントに従う構造で、乖離が構造的に不可能

重要なコンセプト

Context Poisoning（コンテキストポイズニング）:

  • AI が古い情報や矛盾する情報を参照して誤った出力を生成する現象
  • DDD では最新のドキュメントを常に参照することで防止

Retcon Writing（レトコンライティング）の回避:

  • 実装後に後付けでドキュメントを書くことは避ける（DDD の原則）
  • 代わりに、ddd:2 で先に仕様をドキュメント化し、ddd:4 でコード生成

File Crawling（ファイルクロール）:

  • ddd:2 や ddd:4 で複数ファイルを体系的に処理
  • Claude が効率的に多数のファイルを更新

Maximum DRY（Don't Repeat Yourself）:

  • 情報の重複を徹底的に排除
  • ドキュメントが Single Source of Truth

5 つのフェーズの要約

コマンド 目的 出力 承認ゲート
/ddd:1-plan 計画立案 plan.md なし（AI のみ）
/ddd:2-docs ドキュメント更新 docs_status.md + 実ドキュメント ユーザーがレビュー & Git コミット
/ddd:3-code-plan コード計画 code_plan.md なし（AI のみ）
/ddd:4-code コード実装 実装ファイル ユーザーがテスト & Git コミット
/ddd:5-finish 完了処理 クリーンアップ ユーザーが最終確認

承認ゲートの重要性:

  • ddd:2 と ddd:4 にはユーザーの承認が必要
  • ドキュメント（ddd:2）が完璧になるまで反復
  • コード（ddd:4）が動作するまで反復
  • 満足してから次のフェーズへ進む

トラブルシューティング

ホームディレクトリ以外にクローンした場合

Amplifier を ~/amplifier 以外の場所にクローンした場合、.claude/settings.json を修正する必要があります。

問題の症状

  • Claude Code が Amplifier のコンテキストファイルを認識しない
  • /ddd などのスラッシュコマンドが利用できない
  • エージェントが設計哲学やガイドラインを参照できない

解決方法

  1. .claude/settings.json を開く:

    # Amplifier ディレクトリに移動
cd /your/actual/path/amplifier

# 設定ファイルを編集
code .claude/settings.json

  2. additionalDirectories を実際のパスに変更:

    {
  "additionalDirectories": ["/your/actual/path/amplifier"]
}

    注意:

    • 絶対パスを使用してください
    • ~ は使用できません（展開されないため）
    • 例: "/home/username/projects/amplifier" (Linux/Mac)
    • 例: "C:/Users/username/projects/amplifier" (Windows)

  3. Claude Code を再起動:

    • VSCode を再起動するか
    • Claude Code のセッションをリロード

確認方法

設定が正しく反映されているか確認するには:

# Amplifier ディレクトリで
cd ~/your/actual/path/amplifier

# Claude Code を開く
code .

# Claude Code のチャットで確認
# "@AGENTS.md" と入力して、ファイルが認識されるか確認
Submodule 追加時のエラー

fatal: transport 'file' not allowed

Git 2.38+ では、セキュリティ上の理由で file:// プロトコルがデフォルトで無効になっています。

解決方法:

GIT_PROTOCOL_FROM_USER=1 git -c protocol.file.allow=always \
  submodule add file:///absolute/path/to/your/project project-name

Submodule のパスが正しくない

症状: fatal: repository '/path/to/project' does not exist

原因: 相対パスまたは誤った絶対パスを使用している

解決方法:

# プロジェクトの絶対パスを確認
cd /path/to/your/project
pwd
# 出力例: /home/username/projects/pomodoro-timer

# この出力を file:// の後に追加
cd ~/amplifier
GIT_PROTOCOL_FROM_USER=1 git -c protocol.file.allow=always \
  submodule add file:///home/username/projects/pomodoro-timer pomodoro-timer
その他の問題

問題が解決しない場合は、以下を確認してください:

  1. Claude Code のバージョン: 最新版を使用していますか？
  2. Git のバージョン: git --version で 2.38 以上か確認
  3. パスの権限: ディレクトリへの読み書き権限があるか確認
  4. .gitignore の設定: 必要なファイルが除外されていないか確認

それでも解決しない場合は、Amplifier の GitHub Issues で報告してください。

よくあるシナリオへの応用

DDD ワークフローは新機能開発以外にも適用できます：

  • バグ修正: ddd:2 で問題を記録、ddd:4 で修正
  • ドキュメントのみ更新: ddd:2 のみ実行して ddd:5 へ
  • リファクタリング: ddd:2 で内部構造変更を記載、ddd:4 で慎重に実行
  • 既存機能の改善: ddd:2 で新旧機能の境界を明確化

Appendix: Spec Kit（仕様駆動開発ツール）との比較

Spec Kit とは

Spec Kit は GitHub が提供するオープンソースの仕様駆動開発ツールキットで、筆者は普段、これを使っています。
Amplifier と同様に「仕様を先に書き、それに基づいて実装する」というアプローチを採用していますが、いくつかの違いがあります。

Spec Kit の主な特徴:

  • 複数 AI ツール対応: Claude Code、GitHub Copilot、Gemini、Cursor など、様々な AI コーディングアシスタントに対応
  • Python CLI ベース: specify コマンドによるシンプルな CLI インターフェース
  • 段階的ワークフロー: constitution（原則）→ specify（仕様）→ plan（計画）→ tasks（タスク）→ implement（実装）の 5 段階

Amplifier と Spec Kit の比較

観点 Amplifier Spec Kit
提供元 Microsoft（実験的プロジェクト） GitHub（オープンソース）
コアアプローチ メタ認知 AI 開発システム 仕様駆動開発ツールキット
ワークフロー DDD 5 フェーズ（plan→docs→code-plan→code→finish） 5 段階（constitution→specify→plan→tasks→implement）
AI 統合 Claude Code 中心、専門エージェントチーム 複数 AI ツール対応（Claude/Copilot/Gemini/Cursor）
実装形態 Slash コマンド（/ddd:*） Python CLI（specify コマンド）
特徴 Document-Driven Development、専門家エージェント 汎用的、AI ツール非依存
学習曲線 やや急（DDD の原則と専門エージェントの理解） 比較的緩やか（標準的な CLI ツール）
プロジェクト管理 Workspace Pattern（git submodule） Git 統合、特徴管理

どちらを選ぶべきか

Amplifier が適している場合:

  • Claude Code を中心に開発したい
  • 専門エージェント（デザイナー、アーキテクトなど）の支援を受けたい
  • Document-Driven Development の哲学に共感する
  • メタ認知的なアプローチでプロジェクト全体を管理したい
  • 「ドキュメントが仕様である」という厳格なルールに従いたい

Spec Kit が適している場合:

  • 複数の AI ツール（Copilot、Gemini など）を併用したい
  • よりシンプルで汎用的な CLI ツールを好む
  • 既存プロジェクトに段階的に導入したい
  • AI ツールに依存しない仕様管理をしたい
  • より柔軟なワークフローが必要

両ツールの共通点

どちらのツールも、以下の重要な原則を共有しています：

  1. 仕様/ドキュメント駆動: コードを書く前に仕様を明確にする
  2. AI 統合前提: AI ツールとの連携を前提とした設計
  3. 段階的ワークフロー: 複数フェーズで構造化された開発プロセス
  4. コンテキスト管理: 古い情報による誤実装（Context Poisoning）を防ぐ仕組み

どちらを選ぶかは、使用する AI ツール、プロジェクトの性質、チームの開発スタイルによって異なります。Amplifier は Claude Code との統合が深く、より包括的な開発支援を提供します。一方、Spec Kit はツール非依存で、より汎用的なアプローチを取ります。

参考情報

脚注

  1. Git security vulnerabilities announced - The GitHub Blog, Git 2.38.1 Released For Two New Security Vulnerabilities ↩︎

Discussion

toshitoshi

有益な記事ありがとうございます。
12/20現在、amplifierリポジトリはmainブランチが大きく変更されセットアップ方法も変わっています。
旧バージョンの内容はamplifier-claudeブランチへ退避されています。
そのため旧amplifierをcloneする際は、

git clone -b amplifier-claude https://github.com/microsoft/amplifier.git amplifier

のようにブランチを指定する必要がありそうです（が、Makefileが少し変わっていそう・・・）
ちなみに新バージョンもREADMEに沿って試してみましたが、バグがあるようで、anthropicをproviderにすることができず一旦諦めました。。。