requirement-workflow

要件ワークフロー（SDD）

仕様駆動開発に基づく構造化開発オーケストレーターです。まず仕様を定義し、タスクに分解して、品質ゲートを設けて実行し、受け入れ基準に照らして検証します。

基本原則：仕様が唯一の信頼できる情報源です。コードは仕様に従い、その逆ではありません。

前提条件

• Node.js >= 18
• ワークフローの状態ファイル（.trae/workflow/）を書き込み可能なプロジェクトディレクトリ

クイックスタート

User says anything about building/implementing/fixing →
  1. AI classifies the request (type + size + risk)
  2. AI runs: node init.cjs -r <root> -n <name> -t <type> -s <size> -k <risk>
  3. AI fills spec.md with structured requirements (EARS format)
  4. AI decomposes spec.md into tasks.md
  5. AI implements task by task, advancing stages
  6. AI verifies against checklist.md

作業モード

このスキルは、分類に基づいて選択される2つのモードに対応しています。

エージェントモード（デフォルト）

対象範囲が小規模／ごく小規模、または種類がバグ修正の場合は、仕様フェーズを省略し、すぐに実装に進みます。

INIT → IMPLEMENTING → TESTING → DONE

仕様モード（SDD）

対象範囲が中規模／大規模、またはリスクが高め／重大の場合は、SDDのライフサイクル全体を実施します。

INIT → DEFINING → PLANNING → DESIGNING → IMPLEMENTING → TESTING → DELIVERING → DONE

分類マトリックス

シグナル	種類	規模	リスク
"fix bug", "broken", "crash"	バグ修正	ごく小規模〜小規模	通常
"add feature", "implement", "build"	機能	小規模〜大規模	通常
"refactor", "clean up", "reorganize"	リファクタリング	小規模〜中規模	通常
"tech debt", "upgrade", "migrate"	技術的負債	中規模〜大規模	高め
認証、決済、データ、セキュリティ	任意	任意	高め〜重大
見積もりが15ファイルを超える	任意	大規模	高め

規模の目安

規模	ファイル数	期間	ステージ
ごく小規模	≤2	<30min	INIT → IMPLEMENTING → DONE
小規模	3-5	30min-2h	INIT → IMPLEMENTING → TESTING → DONE
中規模	6-15	2h-1d	SDD全体
大規模	>15	>1d	SDD全体 + すべてのチェックポイント

SDDのライフサイクル

ステージ1：INIT

リクエストを分類し、ワークフローを初期化して、成果物ディレクトリを作成します。

node init.cjs -r <project_root> -n "<name>" -t <type> -s <size> -k <risk>

出力：workflow.yaml、空のspec.md、tasks.md、checklist.md

ステージ2：DEFINING（仕様モードのみ）

EARS形式を使用して、構造化された要件をspec.mdに記入します。

# Feature Name

## Background
{Why this is needed — problem statement}

## Scope
- In: {what IS included}
- Out: {what is NOT included}

## Acceptance Criteria (EARS format)
- [ ] When <condition>, the system shall <response>
- [ ] While <state>, the system shall <behavior>
- [ ] Where <constraint>, the system shall <limit>

## Constraints
- {Performance, security, compatibility requirements}

## Out of Scope
- {Explicitly deferred items}

チェックポイント：リスクが高め／重大な場合は、一時停止してユーザーにspec.mdを確認してもらいます。

フック：pre_stage_DEFINING → iron-audit-pm, problem-definer, risk-auditor

ステージ3：PLANNING（仕様モードのみ）

spec.mdをtasks.mdに分解します。各受け入れ基準は、1つ以上のタスクに対応させます。

# Tasks

## Phase 1: Foundation
- [ ] Task 1.1: {description} [files: x, y]
- [ ] Task 1.2: {description} [files: z]

## Phase 2: Core Logic
- [ ] Task 2.1: {description} [files: a, b]

## Phase 3: Integration & Polish
- [ ] Task 3.1: {description} [files: c]

## Verification
- [ ] All acceptance criteria pass
- [ ] Lint clean
- [ ] Type check pass

ルール：各タスクは単独で完了できる単位とし、仕様項目との対応を追跡できるようにします。

フック：pre_stage_PLANNING → story-mapper, mvp-freeze-architect

ステージ4：DESIGNING（仕様モードのみ）

アーキテクチャ上の決定を記載したdesign.mdを作成します（中規模以上の場合のみ）。

• コンポーネント構成
• データフロー
• APIコントラクト
• 主なトレードオフ

チェックポイント：リスクが高め／重大な場合は、一時停止してユーザーに確認してもらいます。

フック：pre_stage_DESIGNING → domain-modeler, architecture-advisor, responsibility-modeler

ステージ5：IMPLEMENTING

tasks.mdのタスクを順番に実行します。各タスクについて、次の手順を行います。

1. タスクの説明を読む
2. 変更を実装する
3. tasks.mdでタスクを[x]にする
4. 利用可能であれば、関連するテストを実行する

フック：pre_stage_IMPLEMENTING → tdd-coach

ステージ6：TESTING

テストスイート全体を実行します。checklist.mdを更新します。

# Checklist

## Code Quality
- [ ] Implementation complete
- [ ] Lint clean (run lint command)
- [ ] Type check pass (run typecheck command)

## Tests
- [ ] Unit tests pass
- [ ] Integration tests pass (if applicable)

## Acceptance Criteria
- [ ] AC 1: {criterion from spec} — verified
- [ ] AC 2: {criterion from spec} — verified

## Review
- [ ] Self-review complete
- [ ] No TODO/FIXME left unresolved

フック：pre_stage_TESTING → test-strategy-advisor, test-strategist, code-reviewer

ステージ7：DELIVERING（仕様モードのみ）

spec.mdに照らして最終検証を行います。すべての受け入れ基準が満たされていることを確認します。

フック：post_stage_DELIVERING → code-reviewer, tech-design-reviewer

ステージ8：DONE

ワークフローが完了しました。次の内容を要約して出力します。

• 提供したもの
• 変更したファイル
• 合格したテスト
• 経過時間

ステージの進行

# Check current status
node status.cjs -r <project_root>

# Advance to next stage
node advance.cjs -r <project_root>

# Force advance (skip checkpoint)
node advance.cjs -r <project_root> --force

フックシステム

フックは、ステージの移行時に実行されるエージェント／スキルです。スコープは3種類あります。

スコープ	ファイル	優先度
グローバル	hooks.yaml（スキルディレクトリ）	最低
プロジェクト	.trae/workflow/hooks.yaml	中
ワークフロー	workflow.yaml（ワークフローディレクトリ内）	最高

フックポイント

フック	タイミング	デフォルトエージェント
pre_stage_DEFINING	仕様を記入する前	iron-audit-pm, risk-auditor
pre_stage_PLANNING	タスクを分解する前	story-mapper, mvp-freeze-architect
pre_stage_DESIGNING	アーキテクチャを設計する前	domain-modeler, architecture-advisor
pre_stage_IMPLEMENTING	コーディングの前	tdd-coach
pre_stage_TESTING	テストフェーズの前	test-strategy-advisor, code-reviewer
post_stage_DELIVERING	最終チェックの後	tech-design-reviewer

# List hooks
node hooks.cjs -r <project_root> list

# Add a hook
node hooks.cjs -r <project_root> add pre_stage_TESTING -n my-validator --type skill

品質ゲート

チェックポイントのルール

ステージ	チェックポイントの条件
DEFINING	リスク = 高または重大
PLANNING	規模 = 大またはリスク ≥ 高
DESIGNING	規模 ≥ 中またはリスク ≥ 高
TESTING	常に（すべてのリスクレベル）

チェックポイントでは、次に進む前に AI が一時停止してユーザーに確認を求めます。

SDD のトレーサビリティルール

すべてのコード行は、次の項目まで追跡できなければなりません。

1. tasks.md のタスク
2. そのタスクが追跡する spec.md の受け入れ基準

タスクに含まれていないコードを書いていることに気づいた場合は、作業を止めて、まず tasks.md を更新してください。

エラー処理

問題	解決策
ユーザーのリクエストが曖昧	feature/small に分類し、Agent Mode を使用して、実装中に詳細を詰めます
仕様が不完全	PLANNING に進む前に、不足している受け入れ基準を追加します
タスクが大きすぎる	それぞれの変更を ≤1 ファイルに抑えてサブタスクに分割します
TESTING 中にテストが失敗する	TESTING に留まり、問題を修正して再実行します
ユーザーがチェックポイントを却下した	現在のステージに留まり、フィードバックに沿って成果物を修正します
ワークフローを中断した	クリーンアップは不要です。状態は .trae/workflow/ に保持されます

スクリプト

スクリプト	目的
init.cjs	分類を行ってワークフローを初期化します
advance.cjs	次のステージに進みます
status.cjs	現在のワークフローの状態を表示します
hooks.cjs	フック登録を管理します
lib/common.cjs	共有 YAML ユーティリティ

エージェント

全エージェントの一覧は AGENTS.md を参照してください。フェーズごとの主なエージェントは次のとおりです。

フェーズ	エージェント	手法
DEFINING	iron-audit-pm	PRD 監査、DNA 抽出
DEFINING	risk-auditor	リスクスキャン
DEFINING	problem-definer	Weinberg の問題分析
PLANNING	story-mapper	Patton のストーリーマッピング
PLANNING	mvp-freeze-architect	スコープの凍結
DESIGNING	domain-modeler	DDD/Evans モデリング
DESIGNING	architecture-advisor	品質特性
IMPLEMENTING	tdd-coach	Beck の TDD サイクル
TESTING	test-strategist	Crispin のテスト戦略
TESTING	code-reviewer	コードレビュー
DELIVERING	tech-design-reviewer	アーキテクチャレビュー

参考資料

• クイックリファレンス - 要点をまとめた判断表