ワークフローパターン

Conductor の TDD ワークフローを使用してタスクを実装し、フェーズチェックポイントを管理し、git コミットを処理し、実装全体を通じて品質を確保する検証プロトコルを実行するためのガイドです。

このスキルを使用する場合

• トラックの plan.md からタスクを実装する場合
• TDD の red-green-refactor サイクルに従う場合
• フェーズチェックポイントを完了する場合
• git コミットとメモを管理する場合
• 品質保証ゲートを理解する場合
• 検証プロトコルを処理する場合
• plan ファイルに進捗を記録する場合

TDD タスクライフサイクル

各タスクについて以下の 11 ステップに従ってください:

ステップ 1: 次のタスクを選択

plan.md を読んで、次の保留中の [ ] タスクを識別します。現在のフェーズ内でタスクを順序に従って選択します。後のフェーズにスキップしないでください。

ステップ 2: 進行中としてマーク

plan.md を更新してタスクを [~] としてマーク:

- [~] **Task 2.1**: Implement user validation

このステータス変更を実装とは別にコミットしてください。

ステップ 3: RED - テストの失敗を記述

実装を記述する前に、期待される動作を定義するテストを記述します:

• 必要に応じてテストファイルを作成
• ハッピーパスをカバーするテストケースを記述
• エッジケースをカバーするテストケースを記述
• エラー条件をカバーするテストケースを記述
• テストを実行 - FAIL するはずです

例:

def test_validate_user_email_valid():
    user = User(email="test@example.com")
    assert user.validate_email() is True

def test_validate_user_email_invalid():
    user = User(email="invalid")
    assert user.validate_email() is False

ステップ 4: GREEN - 最小限のコードを実装

テストをパスさせるために必要な最小限のコードを記述:

• テストを成功させることに焦点を当て、完璧さを求めない
• 早すぎる最適化を回避
• 実装をシンプルに保つ
• テストを実行 - PASS するはずです

ステップ 5: REFACTOR - 明確性を改善

テストが成功した状態で、コードを改善:

• 共通パターンを抽出
• 名前付けを改善
• 重複を削除
• ロジックを簡潔に
• 各変更後にテストを実行 - GREEN のままであるべき

ステップ 6: カバレッジを確認

テストカバレッジが 80% の目標を満たしているかチェック:

pytest --cov=module --cov-report=term-missing

カバレッジが 80% 未満の場合:

• カバーされていない行を特定
• 欠落しているパスのテストを追加
• カバレッジチェックを再実行

ステップ 7: 逸脱を文書化

実装が plan から逸脱した、または新しい依存関係を導入した場合:

• tech-stack.md を新しい依存関係で更新
• plan.md のタスクコメントに逸脱を記述
• 要件が変更された場合は spec.md を更新

ステップ 8: 実装をコミット

タスクの焦点を絞ったコミットを作成:

git add -A
git commit -m "feat(user): implement email validation

- Add validate_email method to User class
- Handle empty and malformed emails
- Add comprehensive test coverage

Task: 2.1
Track: user-auth_20250115"

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

• Type: feat, fix, refactor, test, docs, chore
• Scope: 影響を受けるモジュールまたはコンポーネント
• Summary: 命令形、現在形
• Body: 変更内容の箇条書き
• Footer: タスクおよびトラック参照

ステップ 9: Git ノートを追加

リッチなタスク概要を git note として追加:

git notes add -m "Task 2.1: Implement user validation

Summary:
- Added email validation using regex pattern
- Handles edge cases: empty, no @, no domain
- Coverage: 94% on validation module

Files changed:
- src/models/user.py (modified)
- tests/test_user.py (modified)

Decisions:
- Used simple regex over email-validator library
- Reason: No external dependency for basic validation"

ステップ 10: コミット SHA で plan を更新

plan.md を更新してタスクを完了としてマーク (コミット SHA 付き):

- [x] **Task 2.1**: Implement user validation `abc1234`

ステップ 11: plan 更新をコミット

plan ステータス更新をコミット:

git add conductor/tracks/*/plan.md
git commit -m "docs: update plan - task 2.1 complete

Track: user-auth_20250115"

フェーズ完了プロトコル

フェーズのすべてのタスクが完了したら、検証プロトコルを実行:

変更ファイルを特定

最後のチェックポイント以降に変更されたすべてのファイルを一覧表示:

git diff --name-only <last-checkpoint-sha>..HEAD

テストカバレッジを確保

変更されたファイルごと:

1. 対応するテストファイルを特定
2. 新規/変更されたコードのテストが存在することを確認
3. 変更されたモジュールのカバレッジを実行
4. カバレッジが 80% 未満の場合はテストを追加

完全なテストスイートを実行

完全なテストスイートを実行:

pytest -v --tb=short

すべてのテストは、先に進む前にパスする必要があります。

手動検証ステップを生成

手動検証のチェックリストを作成:

## Phase 1 Verification Checklist

- [ ] User can register with valid email
- [ ] Invalid email shows appropriate error
- [ ] Database stores user correctly
- [ ] API returns expected response codes

ユーザー承認を待機

検証チェックリストをユーザーに提示:

Phase 1 complete. Please verify:
1. [ ] Test suite passes (automated)
2. [ ] Coverage meets target (automated)
3. [ ] Manual verification items (requires human)

Respond with 'approved' to continue, or note issues.

明示的な承認なしに進まないでください。

チェックポイントコミットを作成

承認後、チェックポイントコミットを作成:

git add -A
git commit -m "checkpoint: phase 1 complete - user-auth_20250115

Verified:
- All tests passing
- Coverage: 87%
- Manual verification approved

Phase 1 tasks:
- [x] Task 1.1: Setup database schema
- [x] Task 1.2: Implement user model
- [x] Task 1.3: Add validation logic"

チェックポイント SHA を記録

plan.md のチェックポイントテーブルを更新:

## Checkpoints

| Phase   | Checkpoint SHA | Date       | Status   |
| ------- | -------------- | ---------- | -------- |
| Phase 1 | def5678        | 2025-01-15 | verified |
| Phase 2 |                |            | pending  |

品質保証ゲート

タスクを完了としてマークする前に、これらのゲートを確認:

テスト成功

• 既存テストがすべてパス
• 新しいテストがパス
• テストの回帰がない

カバレッジ >= 80%

• 新しいコードのカバレッジが 80% 以上
• プロジェクト全体のカバレッジが維持される
• クリティカルパスが完全にカバーされている

スタイル準拠

• コードがスタイルガイドに従っている
• リンティングをパス
• フォーマットが正しい

ドキュメント

• 公開 API がドキュメント化されている
• 複雑なロジックが説明されている
• 必要に応じて README が更新されている

型安全性

• 型ヒントが存在する (該当する場合)
• 型チェッカーをパス
• 理由のない type: ignore がない

リンティングエラーなし

• リンターエラーがゼロ
• 警告に対応または正当な理由がある
• 静的分析がクリーン

モバイル互換性

該当する場合:

• レスポンシブデザインの検証
• タッチインタラクションが機能
• パフォーマンスが許容範囲

セキュリティ監査

• コードにシークレットがない
• 入力検証がある
• 認証/認可が正しい
• 依存関係に脆弱性がない

Git 統合

コミットメッセージ形式

<type>(<scope>): <subject>

<body>

<footer>

Type:

• feat: 新機能
• fix: バグ修正
• refactor: 機能/修正のない変更
• test: テスト追加
• docs: ドキュメント
• chore: 保守

リッチサマリーのための Git ノート

コミットに詳細なノートを添付:

git notes add -m "<detailed summary>"

ノートを表示:

git log --show-notes

メリット:

• コミットメッセージを無駄にせずにコンテキストを保持
• コミット間でセマンティッククエリが可能
• トラックベースの操作をサポート

plan.md での SHA 記録

タスク完了時には常にコミット SHA を記録:

- [x] **Task 1.1**: Setup schema `abc1234`
- [x] **Task 1.2**: Add model `def5678`

これにより以下が可能になります:

• plan からコードまでの追跡可能性
• セマンティック revert 操作
• 進捗監査

検証チェックポイント

チェックポイントが重要な理由

チェックポイントはセマンティック reversion のための復元ポイントを作成:

• 任意のフェーズ終了時に復元
• 論理的なコード状態を維持
• 安全な実験を可能に

チェックポイントを作成する場合

以下の後にチェックポイントを作成:

• すべてのフェーズタスクが完了
• すべてのフェーズ検証がパス
• ユーザー承認を受信

チェックポイントコミット内容

チェックポイントコミットに含める:

• すべての未コミット変更
• 更新された plan.md
• 更新された metadata.json
• ドキュメント更新

チェックポイントを使用する方法

復元するには:

# Phase 1 終了時に復元
git revert --no-commit <phase-2-commits>...
git commit -m "revert: rollback to phase 1 checkpoint"

レビューするには:

# Phase 2 で何が変更されたかを確認
git diff <phase-1-sha>..<phase-2-sha>

逸脱への対処

実装中に、plan からの逸脱が発生する可能性があります。系統的に対処してください:

逸脱のタイプ

スコープ追加 元の仕様に含まれていない発見された要件。

• spec.md に新しい要件として文書化
• plan.md にタスクを追加
• タスクコメントに追加を記述

スコープ削減 実装中に不要と判断された機能。

• タスクを [-] (スキップ) として理由付きでマーク
• spec.md のスコープセクションを更新
• 決定の根拠を文書化

技術的逸脱 計画とは異なる実装アプローチ。

• タスク完了コメントに逸脱を記述
• 依存関係が変更された場合は tech-stack.md を更新
• 元のアプローチが不適切だった理由を文書化

要件変更 作業中に要件の理解が変更。

• 修正された要件で spec.md を更新
• 必要に応じて plan.md タスクを調整
• 受理基準を再検証

逸脱ドキュメント形式

逸脱のあるタスクを完了する場合:

- [x] **Task 2.1**: Implement validation `abc1234`
  - DEVIATION: Used library instead of custom code
  - Reason: Better edge case handling
  - Impact: Added email-validator to dependencies

エラー回復

GREEN の後のテスト失敗

GREEN に達した後にテストが失敗する場合:

1. REFACTOR に進まない
2. どのテストが失敗し始めたかを特定
3. リファクタリングが何を破ったかを確認
4. 最後に既知の GREEN 状態に復元
5. 実装を再度試みる

チェックポイント拒否

ユーザーがチェックポイントを拒否する場合:

1. plan.md に拒否理由をメモ
2. 問題に対処するためのタスクを作成
3. 修復タスクを完了
4. チェックポイント承認を再度リクエスト

依存関係によるブロック

タスクが進められない場合:

1. タスクを [!] としてブロッカー説明付きでマーク
2. 他のタスクが進められるかチェック
3. 予想される解決タイムラインを文書化
4. 依存関係解決トラックの作成を検討

タスクタイプ別 TDD バリエーション

データモデルタスク

RED: モデル作成と検証のテストを記述
GREEN: フィールド付きモデルクラスを実装
REFACTOR: 計算プロパティを追加、型を改善

API エンドポイントタスク

RED: リクエスト/レスポンスコントラクトのテストを記述
GREEN: エンドポイントハンドラーを実装
REFACTOR: 検証を抽出、エラー処理を改善

統合タスク

RED: コンポーネント相互作用のテストを記述
GREEN: コンポーネントを一緒に配線
REFACTOR: エラー伝播を改善、ロギングを追加

リファクタリングタスク

RED: 現在の動作の特性化テストを追加
GREEN: リファクタリングを適用 (テストは成功のままであるべき)
REFACTOR: 導入された複雑さをクリーンアップ

既存テストの使用

既存テストのあるコードを変更する場合:

置換ではなく拡張

• 既存テストを成功させ続ける
• 新しい動作のテストを追加
• 要件が変更された場合のみテストを更新

テスト移行

リファクタリングがテスト構造を変更する場合:

1. 既存テストを実行 (パスするはず)
2. リファクタリング済みコードの新しいテストを追加
3. テストケースを新しい構造に移行
4. 古いテストは新しいテストがパス後にのみ削除

回帰防止

任意の変更後:

1. 完全なテストスイートを実行
2. 予期しない失敗をチェック
3. 新しい失敗を調査
4. 回帰を修正してから進む

チェックポイント検証の詳細

自動検証

承認をリクエストする前に実行:

# テストスイート
pytest -v --tb=short

# カバレッジ
pytest --cov=src --cov-report=term-missing

# リンティング
ruff check src/ tests/

# 型チェック (該当する場合)
mypy src/

手動検証ガイダンス

手動アイテムについては、具体的な指示を提供:

## Manual Verification Steps

### User Registration

1. Navigate to /register
2. Enter valid email: test@example.com
3. Enter password meeting requirements
4. Click Submit
5. Verify success message appears
6. Verify user appears in database

### Error Handling

1. Enter invalid email: "notanemail"
2. Verify error message shows
3. Verify form retains other entered data

パフォーマンスに関する考慮事項

テストスイートパフォーマンス

テストスイートを高速に保つ:

• フィクスチャを使用して冗長なセットアップを回避
• 遅い外部呼び出しをモック
• 開発中はサブセットを実行、チェックポイント時に完全スイート

コミットパフォーマンス

コミットはアトミックに保つ:

• 論理変更ごとに 1 コミット
• 完全な考え、未完了の作業ではない
• すべてのコミット後にテストが成功するべき

ベストプラクティス

1. RED をスキップしない: 常に失敗するテストを最初に記述
2. 小さいコミット: 論理変更ごとに 1 コミット
3. 即座に更新: タスク完了直後に plan.md を更新
4. 承認を待つ: チェックポイント検証をスキップしない
5. リッチな git ノート: 将来の理解を助けるコンテキストを含める
6. カバレッジ規律: 目標を下回るカバレッジを受け入れない
7. 品質ゲート: 完了としてマークする前にすべてのゲートをチェック
8. 順序付きフェーズ: フェーズを順序に従って完了
9. 逸脱を文書化: 元の plan からの変更を記述
10. クリーンな状態: 各コミットはコードを動作状態で残すべき
11. 高速フィードバック: 開発中に関連テストを頻繁に実行
12. ブロッカーを明確に: ブロッカーに速やかに対処、回避しない