Claude Codeの施策ワークフローを標準化した：開始から完了まで11ステップの自動化

Claude Codeで複数の施策（機能追加・改善）を並行して進めていると、「この施策はどこまで進んだ？」「テストは書いた？」「ドキュメントは？」が曖昧になります。

これを防ぐために、施策の開始から完了まで11ステップの標準ワークフローを設計しました。AIに「施策開始」と伝えるだけで、ブランチ作成からドキュメント生成まで自動的にチェックポイントが走る仕組みです。

問題：施策が散らかる

Before（標準化前）

1
「機能Xを実装してください」
2
  → Claude Codeが実装
3
  → テストもまあ書いた
4
  → でもドキュメントは更新してない
5
  → ブランチ名もバラバラ
6
  → WBS（進捗管理表）も更新してない
7
  → 2週間後に「機能Xってどうなった？」

1つ2つの施策なら記憶で管理できます。しかし50以上の施策を並行管理していると、抜け漏れが頻発します。

抜け漏れの具体例

施策Aのテストは書いたが、施策Bのテストを忘れた
施策Cのドキュメントを.tmp/に書いたが、.docs/への移動を忘れた
施策Dのブランチがdevelopにマージされないまま放置
施策Eの実装中に施策Fと競合するコードを書いてしまった

11ステップのワークフロー

Phase A: 施策開始（AUTO実行）

「{施策名} 施策開始」とClaude Codeに伝えると、以下が自動実行されます。

A-1: ブランチ作成

1
./scripts/git-new-feature.sh {kebab-case-name}
2
# → develop から feature/{kebab-case-name} ブランチを作成

ブランチ命名はkebab-case（ハイフン区切りの小文字）に統一しています。AIが自動変換します。

A-2: 施策内容の把握

CLAUDE.md、WBS（.wbs/CURRENT.md）、施策ドキュメント（.docs/）を読み込み、施策の目的・スコープ・依存関係をサマリー出力します。

1
=== 施策サマリー ===
2
施策名: NEW-11 リトライ上限の自動調整
3
目的: エラー率が一定水準を超えたらリトライ間隔を自動引き上げ
4
依存: CORE-A2（負荷レジーム自動識別）のGO判定後
5
影響範囲: _processingEngine/core/shared/resource_manager.py
6
テスト要件: 状態機械の3状態遷移テスト

A-3: 競合チェック

既存の稼働中施策と、新施策の間に競合がないかを自動チェックします。

1
チェック項目:
2
- 同一ファイルを変更する施策がないか
3
- 同一APIエンドポイントを使う施策がないか
4
- launchdスケジュールが重複しないか
5
- リソース操作が競合しないか

競合が見つかった場合は、実装前に人間に確認を求めます。

Phase B: 仕様駆動開発（ユーザー確認付き）

B-4: Requirements（要件定義）

.tmp/requirements.mdを生成します。必ず以下を含めます。

1
## 必須要件（施策ワークフロー標準）
2
- [ ] ログタグ: [{施策名}] をログ出力に含める
3
- [ ] 効果定量記録: 施策の効果を数値で記録する手段
4
- [ ] 個別ON/OFF: 設定ファイルで enabled=true/false を切り替え可能
5
- [ ] フォールバックログ: 無効化時に理由をログに記録

この4項目は全施策共通の必須要件です。「施策を個別にON/OFFできること」は、問題発生時のロールバックに必須です。

B-5: Design（技術設計）

.tmp/design.mdを生成します。ユーザーが確認して承認したら次へ進みます。

B-6: Test Design（テスト設計）

.tmp/test_design.mdを生成します。

B-7: Task List（タスク分解）

.tmp/tasks.mdを生成し、TodoWriteで進捗管理します。

B-8: Implementation（実装 + テスト）

コード実装後、自動的にQAワークフローが走ります。

1
/sc:analyze → 品質・セキュリティ・パフォーマンス分析
2
/sc:test    → テスト実行・カバレッジ確認
3
/sc:improve → 改善提案
4
/sc:document → ドキュメント更新

Phase C: 施策完了（AUTO実行）

C-9: ドキュメント移動

.tmp/の一時ドキュメントを、各モジュールの.docs/に正式配置します。

1
移動元: .tmp/requirements.md, .tmp/design.md, .tmp/test_design.md
2
移動先: _processingEngine/.docs/340_core_add_d2_requirements.md
3
       _processingEngine/.docs/341_core_add_d2_design.md
4
       _processingEngine/.docs/342_core_add_d2_test_design.md

CLAUDE.mdとWBSの参照も自動更新します。

C-10: デプロイ手順書作成

以下のセクションを含むデプロイ手順書を自動生成します。

1
## デプロイ手順書
2

3
### デプロイ後検証
4
1. plutil -lint → 手動実行 → validate_launchd_health.sh でエラー0件
5

6
### 環境変数チェック
7
plistの EnvironmentVariables に PROJECT_ROOT・PYTHONPATH が設定されていること
8

9
### ログ確認
10
デプロイ後の初回実行でstderrにエラーがないこと
11

12
### ロールバック手順
13
設定変更による即時無効化 + コードレベルのrevert手順
14

15
### 翌日監視
1 collapsed line
16
validate_launchd_health.sh でログ鮮度確認

C-11: 最終テスト → Push → PR → マージ

全テストPASSを確認し、developにPush、Pull Request作成、ユーザー承認後マージという流れです。

競合チェックの具体例

実際に発見した競合

ある施策（高負荷時のバッチ分割処理）と別の施策（OU Z-scoreによる自動リソース解放）を同日にデプロイした後、/sc:analyzeで以下の競合を検出しました。

1
⚠️ 潜在的リスク検出:
2
施策B3（バッチ分割処理）と施策B4（OU Z-score Exit）が
3
同一キューのリソースを操作する可能性があります。
4

5
具体的シナリオ:
6
1. B3がバッチ分割でリソースを確保する
7
2. B4がOU Z-scoreの閾値超過を検知
8
3. B4がB3のリソースを意図せず解放
9

10
現在のDry-Runでは影響なし（実際のリソース確保がないため）。
11
本番移行前に、リソースIDによる施策識別を実装してください。

このチェックがなければ、本番移行後に「意図しないリソース解放」が発生していました。

QAワークフロー（Post-Implementation）

コード変更が完了したら、Git commit前に以下が自動実行されます。

/sc:analyze

変更されたコードの品質・セキュリティ・パフォーマンスを分析します。

1
実行例:
2
  品質: cyclomatic complexity 19（閾値20以下: OK）
3
  セキュリティ: ハードコードされたシークレットなし
4
  パフォーマンス: N+1クエリなし
5
  結果: PASS（3項目全てクリア）

/sc:test

テスト実行とカバレッジ確認を行います。失敗時は/sc:troubleshootで修正を試行します。

1
テスト結果:
2
  Core: 4,150件 PASS / 0件 FAIL
3
  API:  2,064件 PASS / 0件 FAIL
4
  E2E:  1,270件 PASS / 0件 FAIL
5
  カバレッジ: 82%（閾値80%以上: OK）

/sc:improve

改善提案をユーザーに提示し、承認後に適用します。AIが自動的に変更することはありません（ユーザー承認が必須）。

/sc:document

変更箇所のドキュメントを更新します。

なぜ自動化が必要か

手動チェックリストの限界

最初はMarkdownのチェックリストで管理していました。

1
- [ ] ブランチ作成
2
- [ ] 要件定義
3
- [ ] 設計
4
- [ ] テスト設計
5
- [ ] タスク分解
6
- [ ] 実装
7
- [ ] テスト
8
- [ ] ドキュメント
9
- [ ] PR作成

50施策 × 9項目 = 450のチェックボックスです。手動で管理するのは現実的ではありません。

AIに「施策開始」と言うだけ

ワークフローを標準化してCLAUDE.mdに記載したことで、AIに「NEW-11 施策開始」と言うだけでA-1〜A-3が自動実行されます。人間は各ステージの承認のみ行えばよいのです。

学んだこと

1. 「全施策共通の必須要件」が品質の底上げになる

ログタグ・個別ON/OFF・フォールバックログ——これらを全施策に強制することで、問題発生時の調査と対処が格段に速くなりました。

2. 競合チェックは「実装前」に行う

実装後に競合を発見すると、大幅な手戻りが発生します。A-3で実装前に検出することで、設計段階で回避できます。

3. ドキュメントは「完了時に移動」が最適

実装中は.tmp/に気軽に書き、完了時に.docs/に正式配置します。実装中のドキュメントを正式な場所に置くと、中途半端な内容が残るリスクがあります。

まとめ

施策ワークフローの標準化で重要なのは以下の3点です。

11ステップの標準化: 開始（ブランチ・把握・競合チェック）→ 仕様駆動開発（5ステージ）→ 完了（ドキュメント・手順書・マージ）
全施策共通の必須要件: ログタグ・個別ON/OFF・効果定量記録・フォールバックログの4項目を強制
QA自動実行: analyze → test → improve → document をcommit前に自動実行

「AIに任せる」のではなく「AIと人間の役割を明確に分ける」のが標準化の目的です。AIは手順の実行を担い、人間は各ステージの判断を担います。