workflow-patterns

ワークフローパターン

TDD ワークフローを使用したタスクの実装、フェーズのチェックポイント管理、Git コミットの処理、および実装全体の品質を確保する検証プロトコルの実行に関するガイドです。

このスキルを使う場面

• トラックの plan.md にあるタスクを実装する場合
• TDD のレッド・グリーン・リファクターサイクルに従う場合
• フェーズのチェックポイントを完了する場合
• Git コミットとノートを管理する場合
• 品質保証のゲートを理解する場合
• 検証プロトコルに対応する場合
• plan ファイルに進捗を記録する場合

TDD タスクのライフサイクル

各タスクで次の 11 ステップに従います。

ステップ 1：次のタスクを選択する

plan.md を読み、次に未着手の [ ] タスクを特定します。現在のフェーズ内で順番にタスクを選択します。後続のフェーズに先回りしないでください。

ステップ 2：進行中としてマークする

plan.md を更新し、タスクを [~] としてマークします。

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

このステータス変更は、実装とは別にコミットします。

ステップ 3：RED - 失敗するテストを書く

実装を書く前に、期待される動作を定義するテストを書きます。

• 必要に応じてテストファイルを作成します
• 正常系を網羅するテストケースを書きます
• エッジケースを網羅するテストケースを書きます
• エラー条件を網羅するテストケースを書きます
• テストを実行します。テストは失敗するはずです

例：

def test_validate_user_email_valid():
    user = User(email="[email protected]")
    assert user.validate_email() is True

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

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

テストを通すために必要な最小限のコードを書きます。

• 完璧さではなく、テストを成功させることに集中します
• 時期尚早な最適化は避けます
• 実装をシンプルに保ちます
• テストを実行します。テストは成功するはずです

ステップ 5：REFACTOR - 明瞭さを高める

テストが成功する状態で、コードを改善します。

• 共通パターンを抽出します
• 命名を改善します
• 重複を取り除きます
• ロジックを簡潔にします
• 変更のたびにテストを実行します。テストは成功したままである必要があります

ステップ 6：カバレッジを確認する

テストカバレッジが 80% の目標を満たしていることを確認します。

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

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

• カバーされていない行を特定します
• 不足しているパスのテストを追加します
• カバレッジを再確認します

ステップ 7：逸脱を記録する

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

• 新しい依存関係を 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"

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

• 種別：feat、fix、refactor、test、docs、chore
• スコープ：影響を受けるモジュールまたはコンポーネント
• 要約：命令形、現在形
• 本文：変更点を箇条書きで記載
• フッター：タスクとトラックへの参照

ステップ 9：Git ノートを追加する

タスクの詳しい要約を Git ノートとして追加します。

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.md を更新し、コミット SHA とともにタスクを完了としてマークします。

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

ステップ 11：プランの更新をコミットする

プランのステータス更新をコミットします。

git add .claude/context/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>

種類：

• 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`

これにより、次のことが可能になります：

• 計画からコードへのトレーサビリティ
• セマンティックなリバート操作
• 進捗の監査

逸脱への対処

実装中に、計画から逸脱することがあります。体系的に対処してください：

逸脱の種類

スコープの追加 元の仕様にない要件が見つかった場合です。

• 新しい要件として 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. 依存関係を解決するトラックの作成を検討します

ベストプラクティス

1. RED を決してスキップしない：必ず最初に失敗するテストを書く
2. 小さなコミット：1 つの論理的な変更につき 1 コミット
3. すぐに更新：タスク完了後すぐに plan.md を更新する
4. 承認を待つ：チェックポイントの検証を決してスキップしない
5. 詳細な Git ノート：将来の理解に役立つコンテキストを含める
6. カバレッジを徹底する：目標を下回るカバレッジを受け入れない
7. 品質ゲート：完了とする前に、すべてのゲートを確認する
8. フェーズを順番に進める：フェーズを順序どおりに完了する
9. 逸脱を記録する：元の計画からの変更を記録する
10. クリーンな状態：各コミット後、コードが動作する状態にする
11. 迅速なフィードバック：開発中に関連するテストを頻繁に実行する
12. ブロッカーを明確にする：ブロッカーには速やかに対処し、回避して進めない

メモリプロトコル（必須）

開始前：

cat .claude/context/memory/learnings.md

完了後：

• 新しいパターン → .claude/context/memory/learnings.md
• 見つかった問題 → .claude/context/memory/issues.md
• 決定事項 → .claude/context/memory/decisions.md

作業が中断されることを前提にしてください。メモリに記録されていないことは、起きていないのと同じです。