build

ビルド - ワークフローオーケストレーター

機能開発のために既存のスキルを連鎖させる、ワークフローオーケストレーターです。複数のスキルの実行を順番に調整し、スキル間で引き継ぎを行い、フェーズの境界で人間による確認のために一時停止します。

呼び出し

/build <mode> [options] [description]

質問フロー（引数なし）

ユーザーが引数なし、または不完全な引数で /build だけを入力した場合は、この質問フローに沿って適切な設定を推定できるよう案内します。各フェーズで AskUserQuestion を使用してください。

フェーズ 0：ワークフローの選択

question: "What would you like to do?"
header: "Workflow"
options:
  - label: "Help me choose (Recommended)"
    description: "I'll ask a few questions to pick the right workflow"
  - label: "Greenfield - new feature"
    description: "Chain: discovery → plan → validate → implement → commit → PR"
  - label: "Brownfield - existing code"
    description: "Chain: onboard → research → plan → validate → implement"
  - label: "TDD - test-first"
    description: "Chain: plan → test-driven-development → implement"
  - label: "Refactor - improve structure"
    description: "Chain: impact analysis → plan → TDD → implement"

対応付け：

• 「選択を手伝って」→ フェーズ 1～4 の質問に進みます
• 「グリーンフィールド」→ mode=greenfield に設定し、フェーズ 5（説明）に進みます
• 「ブラウンフィールド」→ mode=brownfield に設定し、フェーズ 5（説明）に進みます
• 「TDD」→ mode=tdd に設定し、フェーズ 5（説明）に進みます
• 「リファクタリング」→ mode=refactor に設定し、フェーズ 5（説明）に進みます

回答が不明確な場合（「その他」経由）：

question: "I want to understand your workflow needs. Did you mean..."
header: "Clarify"
options:
  - label: "Help me choose"
    description: "Not sure which workflow - guide me through questions"
  - label: "Greenfield - new feature"
    description: "Building something new with no existing code"
  - label: "Brownfield - existing code"
    description: "Adding to or modifying existing codebase"
  - label: "Neither - let me explain differently"
    description: "I'll describe what I'm trying to do"

フェーズ 1：プロジェクトのコンテキスト

question: "Is this a new feature or work in existing code?"
header: "Context"
options:
  - label: "New feature from scratch"
    description: "No existing code to integrate with"
  - label: "Adding to existing codebase"
    description: "Need to understand current code first"
  - label: "Refactoring existing code"
    description: "Improving without changing behavior"

対応付け：

• 「ゼロから新機能を作成」→ greenfield モード
• 「既存のコードベースに追加」→ brownfield モード
• 「既存コードをリファクタリング」→ refactor モード

回答が不明確な場合（「その他」経由）：

question: "I want to make sure I understand. Did you mean..."
header: "Clarify"
options:
  - label: "New feature from scratch"
    description: "Building something new with no existing code"
  - label: "Adding to existing codebase"
    description: "Integrating with code that already exists"
  - label: "Refactoring existing code"
    description: "Improving structure without changing behavior"
  - label: "Neither - let me explain differently"
    description: "I'll provide more details"

フェーズ 2：要件の明確さ

question: "How clear are your requirements?"
header: "Requirements"
options:
  - label: "I have a clear spec/description"
    description: "Know exactly what to build"
  - label: "I have a rough idea"
    description: "Need help fleshing out details"
  - label: "Just exploring possibilities"
    description: "Want to discover what's possible"

対応付け：

• 「仕様が明確」→ --skip-discovery
• 「大まかなアイデア」→ 最初に discovery-interview を実行します
• 「検討中」→ より広い範囲で discovery-interview を実行します

回答が不明確な場合（「その他」経由）：

question: "I want to make sure I understand your requirements state. Did you mean..."
header: "Clarify"
options:
  - label: "I have a clear spec/description"
    description: "Ready to implement - no discovery needed"
  - label: "I have a rough idea"
    description: "Need some help defining the details"
  - label: "Just exploring possibilities"
    description: "Don't know exactly what's possible yet"
  - label: "Neither - let me explain differently"
    description: "I'll describe my situation better"

フェーズ 3：開発アプローチ

question: "How should I approach development?"
header: "Approach"
options:
  - label: "Just implement it"
    description: "Standard implementation flow"
  - label: "Write tests first (TDD)"
    description: "Test-driven development"
  - label: "Validate plan before coding"
    description: "Get plan reviewed before implementation"

対応付け：

• 「そのまま実装」→ 標準のチェーン
• 「テストを先に作成」→ tdd モード（refactor でない場合、前の選択を上書きします）
• 「計画を検証」→ validate-agent をチェーンに残します

回答が不明確な場合（「その他」経由）：

question: "I want to make sure I understand your preferred approach. Did you mean..."
header: "Clarify"
options:
  - label: "Just implement it"
    description: "Standard development - implement then test"
  - label: "Write tests first (TDD)"
    description: "Test-driven - tests before implementation"
  - label: "Validate plan before coding"
    description: "Review plan with validate-agent first"
  - label: "Neither - let me explain differently"
    description: "I have a different workflow in mind"

フェーズ 4：実装後

question: "What should happen after implementation?"
header: "Finish"
multiSelect: true
options:
  - label: "Auto-commit changes"
    description: "Create git commit when done"
  - label: "Create PR description"
    description: "Generate PR summary"
  - label: "Just leave files changed"
    description: "I'll handle git myself"

対応付け：

• 「自動コミット」が選択されていない → --skip-commit
• 「PR を作成」が選択されていない → --skip-pr

回答が不明確な場合（「その他」経由）：

question: "I want to understand what you need after implementation. Which apply?"
header: "Clarify"
multiSelect: true
options:
  - label: "Auto-commit changes"
    description: "I'll create a git commit with your changes"
  - label: "Create PR description"
    description: "I'll generate a PR summary for you"
  - label: "Just leave files changed"
    description: "No git operations - you'll handle it"
  - label: "Neither - let me explain differently"
    description: "I have different post-implementation needs"

フェーズ 5：説明

最後に、機能の説明を尋ねます。

question: "Describe what you want to build (1-2 sentences):"
header: "Feature"
options: []  # Free text input via "Other"

実行前の概要

開始前に、実行する内容を表示します。

Based on your answers, I'll run:

**Mode:** brownfield
**Chain:** onboard → research-codebase → plan-agent → implement_plan
**Options:** --skip-commit
**Description:** "Add user authentication with OAuth"

Proceed? [Yes / Adjust settings]

これにより、エージェントを起動する前に、ユーザーが実行内容を正確に把握できます。

モード

モード	チェーン	用途
greenfield	discovery-interview -> plan-agent -> validate-agent -> implement_plan -> commit -> describe_pr	ゼロから新機能を作成
brownfield	onboard -> research-codebase -> plan-agent -> validate-agent -> implement_plan	既存のコードベースに機能を追加
tdd	plan-agent -> test-driven-development -> implement_plan	テストを先に作成する実装
refactor	tldr-code (impact) -> plan-agent -> test-driven-development -> implement_plan	影響分析を伴う安全なリファクタリング

オプション

オプション	効果
--skip-discovery	インタビューフェーズをスキップします（既存の仕様または説明を使用）
--skip-validate	検証フェーズをスキップします（計画をそのまま信頼）
--skip-commit	実装後に自動コミットしません
--skip-pr	PR の説明を作成しません
--parallel	独立した調査エージェントを並行して実行します

引き継ぎディレクトリ

すべての引き継ぎ先：thoughts/shared/handoffs/<session>/

セッション名は次のいずれかから取得します。

1. 既存の継続性台帳名、または
2. 機能の説明から生成：build-<date>-<kebab-description>

オーケストレーションプロセス

ステップ 0：引数の解析

ユーザー入力からモードとオプションを解析します。

/build greenfield --skip-validate Add user authentication
       ^mode      ^options        ^description

モードに基づいてスキルチェーンを構築します。

CHAINS = {
    "greenfield": ["discovery-interview", "plan-agent", "validate-agent", "implement_plan", "commit", "describe_pr"],
    "brownfield": ["onboard", "research-codebase", "plan-agent", "validate-agent", "implement_plan"],
    "tdd": ["plan-agent", "test-driven-development", "implement_plan"],
    "refactor": ["tldr-impact", "plan-agent", "test-driven-development", "implement_plan"]
}

オプションを適用してチェーンを変更します。

• --skip-discovery：「discovery-interview」をチェーンから削除します
• --skip-validate：「validate-agent」をチェーンから削除します
• --skip-commit：「commit」をチェーンから削除します
• --skip-pr：「describe_pr」をチェーンから削除します

ステップ 1：セットアップ

1. 引き継ぎディレクトリを作成します。

   SESSION="build-$(date +%Y%m%d)-<kebab-description>"
   mkdir -p "thoughts/shared/handoffs/$SESSION"
   

2. オーケストレーション状態ファイルを作成します。

   cat > "thoughts/shared/handoffs/$SESSION/orchestration.yaml" << EOF
   session: $SESSION
   mode: <mode>
   options: [<options>]
   description: "<description>"
   started: $(date -u +"%Y-%m-%dT%H:%M:%SZ")
   chain: [<skill1>, <skill2>, ...]
   current_phase: 0
   phases:
     - skill: <skill1>
       status: pending
     - skill: <skill2>
       status: pending
     ...
   EOF
   

ステップ 2：チェーンの実行

チェーン内の各スキルについて、次を行います。

フェーズ実行パターン

1. Read previous handoff (if exists)
2. Execute skill (spawn agent or invoke directly)
3. Capture skill output/handoff
4. Update orchestration state
5. Human checkpoint (if phase boundary)
6. Continue or handle error

スキルの実行詳細

discovery-interview:

Task(
  subagent_type="discovery-interview",
  prompt="""
  [Contents of discovery-interview SKILL.md]

  ---

  ## Context
  Feature request: <description>
  Handoff directory: thoughts/shared/handoffs/<session>/

  Conduct the interview and create spec.
  """
)

出力：thoughts/shared/specs/<name>-spec.md の仕様ファイル

onboard:

Task(
  subagent_type="onboard",
  prompt="""
  [Contents of onboard SKILL.md]

  ---

  Analyze this codebase and create continuity ledger.
  Handoff directory: thoughts/shared/handoffs/<session>/
  """
)

出力：TLDR キャッシュ、継続性台帳

research-codebase:

Task(
  subagent_type="research-codebase",
  prompt="""
  [Contents of research-codebase SKILL.md]

  ---

  Research question: How should we implement <description>?
  Focus areas: [based on spec or description]
  Handoff directory: thoughts/shared/handoffs/<session>/
  """
)

出力：thoughts/shared/research/<date>-<topic>.md の調査ドキュメント

tldr-impact（リファクターモード用）：

# Run impact analysis on the function/module being refactored
tldr impact <target> src/ --depth 3 > thoughts/shared/handoffs/<session>/impact-analysis.json

# Also run architecture analysis
tldr arch src/ > thoughts/shared/handoffs/<session>/architecture.json

出力：影響分析ファイルとアーキテクチャ分析ファイル

plan-agent:

Task(
  subagent_type="plan-agent",
  prompt="""
  [Contents of plan-agent SKILL.md]

  ---

  ## Context
  Feature request: <description>

  [Include spec if exists from discovery-interview]
  [Include research findings if exists]
  [Include impact analysis if refactor mode]

  Handoff directory: thoughts/shared/handoffs/<session>/
  """
)

出力：thoughts/shared/plans/PLAN-<name>.md の計画、<session>/plan-<name>.md の引き継ぎ資料

チェックポイント：plan-agent の後

Plan created: thoughts/shared/plans/PLAN-<name>.md

Please review the plan. Options:
1. Approve and continue to [next phase]
2. Request changes to plan
3. Abort workflow

[Show plan summary]

validate-agent:

Task(
  subagent_type="validate-agent",
  prompt="""
  [Contents of validate-agent SKILL.md]

  ---

  Plan to validate: [Plan content]
  Plan path: thoughts/shared/plans/PLAN-<name>.md
  Handoff directory: thoughts/shared/handoffs/<session>/
  """
)

出力：<session>/validation-<name>.md の検証引き継ぎ資料

チェックポイント：validate-agent の後（問題が見つかった場合）

Validation complete with issues:
- [Issue 1]
- [Issue 2]

Options:
1. Proceed anyway (acknowledge risks)
2. Update plan and re-validate
3. Abort workflow

test-driven-development（TDD／リファクターモード用）：

Present TDD guidance to user:

"Entering TDD mode. For each feature:
1. Write failing test first
2. Implement minimal code to pass
3. Refactor while keeping tests green

I'll guide you through each cycle. Starting with first test..."

インタラクティブ形式です。TDD サイクルを通じてユーザーをガイドします。

implement_plan:

# Check plan size
if task_count <= 3:
    # Direct implementation
    Follow implement_plan skill directly
else:
    # Agent orchestration mode
    For each task:
        Task(
          subagent_type="implement_task",
          prompt="""
          [Contents of implement_task SKILL.md]

          ---

          Plan: [Plan content]
          Your task: Task N of M: <task description>
          Previous handoff: [Previous task handoff or "First task"]
          Handoff directory: thoughts/shared/handoffs/<session>/
          """
        )

出力：<session>/task-NN-<description>.md のタスク引き継ぎ資料

チェックポイント：実装フェーズごとに

Phase [N] Complete

Automated verification:
- [x] Tests passing
- [x] Type check passed
- [ ] Manual testing required

Please verify:
- [Manual test items from plan]

Continue to next phase? [Y/n]

commit:

Follow commit skill:
1. Show git status and diff
2. Present commit plan
3. Execute on user approval
4. Generate reasoning file

describe_pr:

Follow describe_pr skill:
1. Create PR if not exists
2. Generate description from changes
3. Update PR with description

ステップ 3：エラーへの対応

フェーズが失敗するか、ブロック状態を返した場合：

# Update orchestration.yaml
phases:
  - skill: plan-agent
    status: complete
  - skill: validate-agent
    status: blocked
    error: "Validation found deprecated library"
    blocker: "Need to replace X with Y"

ユーザーに提示します：

Workflow blocked at: validate-agent

Issue: Validation found deprecated library
Blocker: Need to replace X with Y

Options:
1. Retry this phase
2. Skip this phase (not recommended)
3. Abort workflow
4. Manual intervention (I'll help you fix it)

ステップ 4：完了

すべてのフェーズが完了したら：

Build workflow complete!

Session: thoughts/shared/handoffs/<session>/

Artifacts created:
- Spec: thoughts/shared/specs/<name>-spec.md (if greenfield)
- Plan: thoughts/shared/plans/PLAN-<name>.md
- Validation: <session>/validation-<name>.md
- Implementation handoffs: <session>/task-*.md
- PR: #<number> (if --skip-pr not set)

Commit: <hash> (if --skip-commit not set)

Total phases: N completed, M skipped

人によるチェックポイント

チェックポイントでは、重要な判断のタイミングで人による確認を行うため、処理を一時停止します。

フェーズの後	チェックポイントの目的
discovery-interview	仕様に要件が反映されていることを確認する
plan-agent	実装計画を承認する
validate-agent（問題がある場合）	検証上の懸念を確認する
各実装タスク	続行する前にフェーズが機能することを確認する
commit	コミットメッセージとファイルを承認する

チェックポイントをスキップするには： --no-checkpoint を付けて実行します（上級ユーザーのみ）

再開のサポート

ワークフローが中断された場合は、最後のチェックポイントから再開します：

/build resume thoughts/shared/handoffs/<session>/

orchestration.yaml を読み込み、最後に完了していないフェーズから続行します。

セッションの例

新規機能

User: /build greenfield Add user authentication with OAuth

Claude: Starting greenfield workflow for "Add user authentication with OAuth"

Creating session: build-20260108-user-auth-oauth
Chain: discovery-interview -> plan-agent -> validate-agent -> implement_plan -> commit -> describe_pr

Phase 1/6: Discovery Interview
[Spawns discovery-interview agent]

Interview questions:
1. What OAuth providers do you need? (Google, GitHub, etc.)
2. What user data should we store after auth?
3. Should sessions persist across browser closes?
...

[After interview completes]

Spec created: thoughts/shared/specs/2026-01-08-user-auth-spec.md

Phase 2/6: Planning
[Spawns plan-agent]

Plan created: thoughts/shared/plans/PLAN-user-auth.md

--- CHECKPOINT ---
Plan Summary:
- Task 1: Set up OAuth provider configuration
- Task 2: Create user model and session storage
- Task 3: Implement OAuth callback endpoints
- Task 4: Add auth middleware
- Task 5: Create login/logout routes

Approve plan and continue? [Y/n]

User: Y

Phase 3/6: Validation
[Spawns validate-agent]

Validation: PASSED
All tech choices are current best practices.

Phase 4/6: Implementation (5 tasks)
[Spawns implementation agents for each task]

Task 1/5: OAuth configuration... Complete
Task 2/5: User model... Complete
Task 3/5: OAuth callbacks... Complete
Task 4/5: Auth middleware... Complete
Task 5/5: Login/logout routes... Complete

--- CHECKPOINT ---
All implementation complete.
Tests: 24 passing
Manual verification needed:
- [ ] Test OAuth flow end-to-end
- [ ] Verify session persistence

Continue to commit? [Y/n]

User: Y

Phase 5/6: Commit
[Shows changes, creates commit]

Phase 6/6: PR Description
[Creates/updates PR]

Build complete!
PR #42: https://github.com/user/repo/pull/42

TDD モード

User: /build tdd Add rate limiting to API endpoints

Claude: Starting TDD workflow for "Add rate limiting to API endpoints"

Phase 1/3: Planning
[Creates plan with test specifications]

--- CHECKPOINT ---
Plan approved? [Y/n]

User: Y

Phase 2/3: TDD Implementation

Let's start with the first test. According to the plan, we need to test:
"Rate limiter returns 429 after 100 requests per minute"

RED - Write failing test:
```python
def test_rate_limiter_returns_429_after_limit():
    limiter = RateLimiter(limit=100, window=60)
    for _ in range(100):
        assert limiter.check("user1") == True
    assert limiter.check("user1") == False

テストを実行中... 失敗（想定どおり — RateLimiter が存在しません）

GREEN — 最小限のコードを実装します： [実装をガイドします]

テストを実行中... 成功

REFACTOR — クリーンアップが必要ですか？

次のテスト：「ウィンドウの期限が切れるとレートリミッターがリセットされる」 ...

フェーズ 3/3：実装 [レートリミッターをエンドポイントに統合します]

ビルド完了！

### Refactor Mode

ユーザー：/build refactor 認証ロジックを別モジュールに切り出す

Claude：「認証ロジックを別モジュールに切り出す」のリファクターワークフローを開始します

フェーズ 1/4：影響分析 実行中：tldr impact auth src/ --depth 3

影響分析が完了しました：

• 12 個のファイルが認証関数を直接呼び出しています
• 3 個のエントリーポイントが影響を受けます
• 循環依存は検出されませんでした

アーキテクチャ分析：

• auth の現在の場所：src/api/middleware/
• 呼び出し元：src/api/routes/、src/api/handlers/

--- チェックポイント --- 計画の前に影響を確認しますか？ [Y/n]

ユーザー：Y

[詳細な影響レポートを表示します]

フェーズ 2/4：計画 [影響分析に基づいてリファクター計画を作成します]

...

## Error Recovery

### If a phase fails:

フェーズ 3（validate-agent）が失敗しました：

エラー：WebSearch を利用できません

選択肢：

1. フェーズを再試行する（推奨）
2. 検証をスキップする（--skip-validate）
3. ワークフローを中止する

選択：

### If implementation is blocked:

タスク 3/5 がブロックされました：

ブロッカー：データベーススキーマが想定される構造と一致しません 検出：users.email（VARCHAR） 想定：users.email（UNIQUE VARCHAR）

選択肢：

1. スキーマを修正するマイグレーションを作成する
2. 現在のスキーマに合わせて計画を調整する
3. 中止して調査する

選択：

## Parallel Execution

With `--parallel` option, independent phases run concurrently:

/build brownfield --parallel ダッシュボード機能を追加する

フェーズ 1：オンボード（開始） フェーズ 2：コードベースの調査（並行して開始）

[両方が完了]

フェーズ 3：plan-agent（両方の結果を使用） ...

Only truly independent phases run in parallel. Dependencies are respected.

## Configuration

### Default mode preferences

Set in `.claude/settings.json`:

```json
{
  "skills": {
    "build": {
      "default_mode": "brownfield",
      "always_validate": true,
      "auto_commit": false,
      "checkpoint_phases": ["plan-agent", "implement_plan"]
    }
  }
}

トラブルシューティング

問題	解決策
「継続性台帳が見つかりません」	先に /onboard を実行するか、新規プロジェクトモードを使用します
「計画の検証に失敗しました」	検証結果を確認し、計画を更新します
「実装がブロックされました」	引き継ぎ資料のブロッカーを確認し、依存関係を解決します
「ワークフローが停止しています」	orchestration.yaml で状態を確認し、再開するか再起動します

関連スキル

• /discovery-interview - 要件の詳細なインタビュー
• /plan-agent - 実装計画の作成
• /validate-agent - 技術選択の検証
• /implement_plan - 実装計画の実行
• /implement_task - 単一タスクの実装
• /test-driven-development - TDD ワークフロー
• /commit - コミットの作成
• /describe_pr - PR の説明文の生成
• /onboard - コードベースの分析
• /research-codebase - 既存コードの調査
• /tldr-code - コード分析 CLI