開発ワークフロー

単一の開発タスクを実行するためのワークフローのガイドです。トップダウン開発モデルと階層化された TDD を採用しています。

言語規則

• 日本語と英語での質問をサポートします。
• 日本語で統一された回答を返します。

トリガー条件

• ユーザーが特定のタスク（例：T-01）の実行を開始したとき
• ユーザーが開発の指導を必要としているとき
• ユーザーが devdocs-dev-tasks から開発段階に入ったとき
• キーワード："開発タスク"、"実行タスク"、"開始 T-XX"

前提条件

• タスクドキュメント：docs/devdocs/04-dev-tasks.md
• タスクが定義されており、以下を含むこと：関連する要求、受け入れ基準、テスト方法

ワークフロー

1. タスク定義の読み込み
   ├── 04-dev-tasks.md からタスクの詳細を取得
   ├── 関連する F-XXX、AC-XXX を確認
   └── 関連するテストケース UT/IT/E2E-XXX を確認
           │
           ▼
2. スケルトンコードの生成（トップダウン）
   ├── インタフェーススケルトン + @requirement/@satisfies アノテーション
   └── テストスケルトン + @verifies/@testcase アノテーション
           │
           ▼
3. 開発の実行（階層化 TDD）
   ├── コアロジック 🔴：テスト先行
   ├── インタフェース層 🟡：テスト先行を推奨
   ├── UI 層 🟢：実装後にテストを追加可能
   └── インフラストラクチャ ⚪：統合テストで検証
           │
           ▼
4. 完了チェック
   ├── 受け入れ基準をすべて満たす
   ├── テストに合格
   └── レビューの要点を自己チェック
           │
           ▼
5. コードのコミット（`/commit-convention` に従う）
           │
           ▼
6. 追跡情報の更新（`/devdocs-sync --trace` を実行）

コード追跡アノテーションの仕様

ドキュメントとコードの双方向追跡を実現します。AI はコード生成時に自動的にアノテーションを追加します。

アノテーションの種類

アノテーションの例

/**
 * ユーザーを作成する
 * @requirement F-001 - ユーザー登録
 * @satisfies AC-001 - メールアドレスの形式検証
 * @satisfies AC-002 - パスワードの強度検証
 */
export async function createUser(dto: CreateUserDTO): Promise<User> {
  // 実装コード
}

/**
 * @verifies AC-001 - メールアドレスの形式検証
 * @testcase UT-001
 */
test('createUser は無効なメールアドレス形式を拒否するはず', () => {
  // テストコード
});

アノテーションの規則

トップダウン開発モデル

まずスケルトンを定義し、後で詳細を埋めます。コード生成時に追跡チェーンが確立されていることを確認します。

開発フロー

Step 1: インタフェーススケルトンの生成
        ├── メソッドシグネチャ（02-system-design.md から）
        ├── @requirement/@satisfies アノテーションの追加
        └── メソッド本体: throw new Error('Not implemented')
                │
                ▼
Step 2: テストスケルトンの生成
        ├── テスト構造（03-test-cases.md から）
        ├── @verifies/@testcase アノテーションの追加
        └── テスト本体: test.skip() または test.todo()
                │
                ▼
Step 3: インタフェースの詳細の実装（`/code-quality` に従う）
                │
                ▼
Step 4: テストの完成（`/testing-guide` に従う）
                │
                ▼
Step 5: `/devdocs-sync --trace` を実行して追跡マトリックスを更新

スケルトン生成の制約

• [ ] インタフェーススケルトンは完全なシグネチャを含む必要があります（パラメータ、戻り値、ジェネリック）
• [ ] インタフェーススケルトンは追跡アノテーションを追加する必要があります
• [ ] 未実装のメソッドは Error をスローし、タスク番号を明記する必要があります
• [ ] テストスケルトンは skip/todo マークを使用する必要があります
• [ ] テストスケルトンは @verifies と @testcase アノテーションを追加する必要があります

詳細は skeleton-examples.md を参照してください。

階層化 TDD モデル

タスクの種類に応じてテストの優先順位を決定します。

TDD サイクル

┌─────┐    ┌─────┐    ┌─────┐
│ 赤  │ → │ 緑  │ → │リファクタリング │ ──┐
│テストを書く│    │実装を書く│    │最適化 │   │
│(失敗)│    │(成功)│    │コード │   │
└─────┘    └─────┘    └─────┘   │
    ↑                           │
    └───────────────────────────┘

詳細な実行フローは execution-flow.md を参照してください。

Skill 連携

制約

スケルトン生成の制約

• [ ] インタフェーススケルトンは完全なシグネチャを含む必要があります
• [ ] インタフェーススケルトンは追跡アノテーションを追加する必要があります
• [ ] 未実装のメソッドは Error をスローする必要があります
• [ ] テストスケルトンは skip/todo マークを使用する必要があります
• [ ] テストスケルトンは @verifies と @testcase アノテーションを追加する必要があります

階層化 TDD の制約

• [ ] コアロジックタスクは 🔴 必須 TDD とマークする必要があります
• [ ] コアロジックタスクは最初にテストを書き、次に実装を書く必要があります
• [ ] コアロジックタスクはテストに合格する前にコミットしてはいけません
• [ ] インタフェース層タスクは 🟡 推奨 TDD とマークします
• [ ] UI 層タスクは 🟢 オプション TDD とマークします
• [ ] インフラストラクチャタスクは ⚪ 適用外 TDD とマークします
• [ ] TDD タスクは赤-緑-リファクタリングの 3 つのステップを含む必要があります

完了チェックの制約

• [ ] 受け入れ基準 (AC-XXX) をすべて満たす
• [ ] 関連するテストをすべて通過する
• [ ] レビューの要点の自己チェックを完了する
• [ ] コード追跡アノテーションが完全である

タスク完了フロー

TDD タスク（コアロジック 🔴）

1. テスト先行の確認：最初にテストを書いたかどうかを確認します
2. 赤-緑サイクルの確認：テストが失敗から成功に変わったかを確認します
3. リファクタリングのチェック：コードが最適化されたかどうかを確認します
4. 受け入れ基準の検証：すべての AC が満たされているかを確認します
5. レビューの要点の自己チェック：TDD フローのチェックを含む
6. コミットの確認：AskUserQuestion を使用して質問します。
   • "タスク T-XX（TDD）が完了し、テストに合格しました。コードをコミットしますか？"
   • 選択肢："コミット" / "修正を続ける" / "スキップ"
7. コミットする場合：git add と commit を実行します。メッセージにはタスク番号を含めます
8. 状態の更新：タスクを完了済みにマークします

非 TDD タスク（インタフェース/UI/インフラストラクチャ）

1. テストの実行：タスク定義のテスト方法を実行します
2. 受け入れ基準の検証：すべての受け入れ基準が満たされているかを確認します
3. レビューの要点の自己チェック：コードレビューの要点を確認します
4. コミットの確認：AskUserQuestion を使用して質問します
5. コミットする場合：git add と commit を実行します
6. 状態の更新：タスクを完了済みにマークします

コミットメッセージの形式

/commit-convention の仕様に従い、以下の形式を使用します。

<type>(T-XX): <タスク名>

- <完了内容1>
- <完了内容2>

関連: F-XXX, AC-XXX
テスト: UT-XXX, IT-XXX 合格

type タイプ：feat | fix | refactor | test | docs | chore

参考資料

• skeleton-examples.md - インタフェース/テストスケルトンの例
• execution-flow.md - タスク実行フローの詳細