45395 - シコウサクゴ -

Claude Codeで53施策を回す施策ワークフロー:Markdown WBS、AIとの施策選定、1施策1セッション、完了後のIssue自動起票

Claude Code で複数の施策(機能追加や改善)を並行して進めていると、「この施策はどこまで進んだか」「テストは書いたか」「ドキュメントは更新したか」があいまいになります。筆者のプロジェクトでは、3つの処理エンジンにまたがって、実行中の施策が53件、計画中の施策が58件ありました。

この数になると、頭の中での管理は無理です。そこで、施策の一生を次の流れで標準化しました。

1
何をやるか決める(AIと施策を選ぶ)
2
→ WBS に登録する
3
→ 「施策開始」で11ステップの標準手順を回す(1施策1セッション)
4
→ 完了したら、次の段階の Issue を自動で起票する

この記事では、それぞれの段階で何を決め、AI に何を任せたかを記録します。


問題:施策が散らかる

標準化する前は、次のような流れでした。

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とぶつかるコードを書いてしまった

最初は Markdown のチェックリストで管理しようとしました。しかし、50施策 × 9項目で450個のチェックボックスになり、続きませんでした。


土台:施策の状態を Markdown の WBS で持つ

なぜ Trello や Jira ではなく Markdown か

WBS(作業分解構成図)は .wbs/CURRENT.md という1つの Markdown ファイルにしています(約600行)。理由は3つです。

  1. AI が直接読み書きできる: @.wbs/CURRENT.md と書くだけで、Claude Code がコンテキストとして読み込めます。外部ツールの API を叩くより速く、正確です
  2. Git で差分を追える: 「3週間前の計画と今の計画の差」を git diff で確認できます
  3. 1ファイルで全体を見渡せる: 53施策を、画面を行き来せずに一覧できます
1
## 実行中プロジェクト(53件)
2
3
### データ処理エンジンA(22件)
4
| ID | 施策名 | ステータス | 依存 | 期限 |
5
|---|---|---|---|---|
6
| NEW-30 | バッチサイズ自動調整 | Practice中 | - | 04-22 |
7
| NEW-11 | リトライ上限の自動調整 | Dry-Run中 | CORE-A2 | 04-01 |
8
...
9
10
## 計画中プロジェクト(58件)
11
## 完了済みプロジェクト(40件以上)

施策のライフサイクル

ステータスは「実装中」「レビュー中」のようなあいまいな言葉ではなく、検証の段階で区切りました。

1
計画中 → 実行中 → Dry-Run中 → Practice中 → 本番稼働 → 完了
2
↓
3
NO-GO → 凍結
ステータス意味
計画中設計の前。WBS に登録済み
実行中実装〜テスト中
Dry-Run中Pre 環境で検証中。外部への書き込みはしない
Practice中本番環境で、最小限のリソースで実際に動かしている
本番稼働通常のリソースで運用中
完了検証が終わり、WBS の完了セクションに移した
凍結統計的に NO-GO と判定。将来また検討するかもしれない

Pre 環境での Dry-Run の仕組みは「本番・Pre・開発の3環境を1台のMacで1人で運用する」に書きました。

依存関係と Go/No-Go のゲート

施策には前提条件があります。WBS に依存列を設け、依存先が終わっていない施策に手を付けようとしたら、AI に「依存先の CORE-A2 がまだ完了していません」と警告させます。依存を逆引きする使い方もよくします。

1
@.wbs/CURRENT.md で CORE-A2 に依存している施策をすべて挙げてください。

「この施策の GO 判定が出るまで、次の施策を有効にしない」というゲートも WBS に書きます。

1
NEW-11(リトライ上限の自動調整):
2
Go/No-Go判定日: 2026-04-01
3
判定基準: 30回以上の処理で、事前に決めた統計的な基準を満たすこと
4
依存施策: CORE-A2 の GO 後に有効化

WBS 運用で失敗したこと

  • WBS と CLAUDE.md の食い違い: WBS だけ更新して CLAUDE.md の参照を直し忘れ、AI が古い情報で作業を進めたことがありました。両方の変更を全ブランチへすぐ同期するルールにしました
  • 計画中の施策が増えすぎた: 「いつかやりたい」を足し続けて58件になり、優先順位がつけられなくなりました。四半期ごとに見直し、6ヶ月以内に着手しないものは「アイデア」セクションに移します
  • 施策の粒度がばらばら: 「エンジンAの基盤構築」と「通知フォーマットの修正」が同じ粒度で並んでいました。大きな施策はサブタスクに分け、1施策を1〜2週間で終わる大きさに揃えました

何をやるか決める:AI に PM 役をさせる

施策が50を超えると、「次に何をやるか」の判断がいちばんのボトルネックになります。全施策の依存関係・期待効果・実装コストを、1人で見渡すのは困難です。そこで、Claude Code にプロダクトマネージャー(PM)の役をさせています。ただし、最終判断は必ず人間がします。

6ステップの対話パターン

  1. 現状分析を頼む: 「@.wbs/CURRENT.md を読んで、運用状況と未解決の課題を整理してください」。この段階では事実の整理だけを頼みます
  2. 課題を具体的に伝える: 「改善したい」ではなく、観測した事実を伝えます。あいまいな要望からは、あいまいな提案しか出ません
  3. 制約を明示する: 「実装は2週間以内」「既存のパイプラインへの影響は最小限」「新しい外部 API への依存は足さない」。制約がないと、作り直しのような大規模な提案が出てきます
  4. 絞り込んで提案させる: 「星3以上の効果が見込めるものだけ」と閾値を指定します。指定しないと20案出てきて、人間が選べなくなります
  5. 同じ基準で比べさせる: 期待効果、実装の難しさ(日数と変更範囲)、リスク、既存施策との競合の4つで横並びにします
  6. 人間が採否を決め、WBS に登録させる: 「案2を採用。WBS に OPT-35 として追加してください」

6つ目の「WBS に登録する」が大事です。対話で出たよい案も、WBS に載せなければ次のセッションでは消えています。WBS への登録が、施策の「コミット」です。

対話の例:根拠のない既定値を見直す

1
人間: 判定期間の既定値はどうすべきか。
2
今は固定で30日にしているが、根拠がない。
3
4
AI: 過去6ヶ月の Go/No-Go 判定データでは、
5
30回の処理サイクルに届くまでの平均は22.4日、標準偏差は8.7日です。
6
既定値 = ceil(平均 + 1σ) = 32日 を提案します。
7
これで約84%の施策が既定の期間内に判定できます。
8
代替案: 保守的に ceil(平均 + 2σ) = 40日、早く判断するなら ceil(平均) = 23日。
9
10
人間: 32日を採用。ただし設定ファイルで変えられるようにして、
11
ハードコードはしないでください。

AI が得意なこと、苦手なこと

AI に任せる人間が決める
全施策を見渡した依存関係・競合のチェック運用環境の変化の「肌感覚」(例: 上流 API の仕様変更が近そうだ)
過去データにもとづく定量的な見積もりどこまでリスクを取るか
効果順・リスク順・速さ順の並べ替え「今の自分にとって何がいちばん大事か」という優先順位
採用した施策の WBS への登録やめどき(ただし、サンクコストに引きずられない点は AI の強み)

たとえば AI は「効果順なら案2、リスク順なら案1」と並べられますが、「今月は安定性を優先したいので案1から」と決めるのは人間です。

CLAUDE.md に書いた施策提案のルール

提案の質のばらつきを抑えるため、次のルールを CLAUDE.md に書いています。

1
## 施策提案ルール
2
- 提案時は必ず★評価(1-5)を付けること
3
- 既存施策との競合を確認すること
4
- 実装期間と期待効果の比を明示すること
5
- 制約が明示されていない場合は、以下のデフォルト制約を適用:
6
- 実装期間: 2週間以内
7
- 既存パイプラインへの影響: 最小限
8
- 新しい外部API依存: 原則追加しない

11ステップの標準手順

施策が決まったら、Claude Code に「{施策名} 施策開始」と伝えます。ここから完了まで、次の11ステップを回します。

Phase A:施策開始(自動で実行)

A-1:ブランチ作成

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

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:競合チェック

稼働中の施策と新しい施策がぶつからないかを確かめます。同じファイルを変える施策、同じ API エンドポイントを使う施策、重なる launchd のスケジュール、競合するリソース操作がないかを見て、見つかれば実装の前に人間に確認を求めます。

Phase B:仕様駆動開発(各段階でユーザーが確認)

  • B-4 要件定義(.tmp/requirements.md)
  • B-5 技術設計(.tmp/design.md)
  • B-6 テスト設計(.tmp/test_design.md)
  • B-7 タスク分解(.tmp/tasks.md。TodoWrite で進捗を管理)
  • B-8 実装とテスト(commit 前に QA の手順を自動で実行)

要件定義には、全施策に共通する次の4項目を必ず入れます。

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

特に「施策ごとに ON/OFF できること」は、問題が起きたときにすぐ止めるために欠かせません。B-8 の QA の手順については「1人開発のコードレビューをAIに任せる」にまとめています。

Phase C:施策完了(自動で実行)

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

.tmp/ の一時ドキュメントを、各モジュールの .docs/ に連番付きで正式に置きます。CLAUDE.md と WBS の参照も更新します。

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

実装中は .tmp/ に気軽に書き、完了時に正式な場所へ移します。書きかけのドキュメントが正式な場所に残るのを防ぐためです。

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

デプロイ後の検証、環境変数のチェック、初回実行のログ確認、ロールバック手順、翌日の監視を必ず含めます。

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

全テストの PASS を確かめ、develop に push し、PR を作り、ユーザーが承認したらマージします。

競合チェックが実際に見つけた問題

高負荷時にバッチを分割する施策(B3)と、統計的な閾値を超えたらリソースを自動で解放する施策(B4)を同じ日に Pre 環境へデプロイした後、AI が次の競合を指摘しました。

1
⚠️ 潜在的リスク検出:
2
施策B3(バッチ分割処理)と施策B4(閾値超過時の自動リソース解放)が
3
同一キューのリソースを操作する可能性があります。
4
5
具体的シナリオ:
6
1. B3 がバッチ分割でリソースを確保する
7
2. B4 が閾値超過を検知する
8
3. B4 が B3 のリソースを意図せず解放する
9
10
現在の Dry-Run では影響なし(実際のリソース確保がないため)。
11
本番移行前に、リソースIDによる施策識別を実装してください。

Dry-Run では実害が出ないので、このチェックがなければ本番に移した後で初めて気づいていたはずです。ただ、本来は A-3 の段階、つまり実装の前に見つけるべき競合でした。実装後に見つかると手戻りが大きくなります。


1施策1セッション

長いセッションで起きること

Claude Code はコンテキストが上限に近づくと、古いメッセージを自動で要約・圧縮します。この挙動は制御できず、圧縮されると詳細が失われます。特に「会話の序盤に決めた制約」「具体的な変数名」「エラーメッセージの細部」が消えやすく、直近の作業や CLAUDE.md の内容(毎回読み込まれるため)は残りやすい傾向があります。

1つのセッションで施策Aの実装を終えた後に施策Bに取りかかると、施策Aで決めた制約が圧縮で消え、AI が施策Aと矛盾するコードを書くことがありました。そこで、「1つのセッションでは1つの施策だけを、開始から完了まで進める」ことを原則にしました。

  • 範囲がはっきりする: このセッションで何を終わらせるかが決まっています
  • コンテキストに余裕がある: 1施策分のコード・テスト・ドキュメントなら収まります
  • ブランチと PR が1対1になる: feature/{施策名} に変更が集まり、レビューしやすくなります

よくある崩れ方

崩れ方何が起きるか対策
「ついでに」直す見つけたバグの修正が施策のブランチに混ざり、PR の範囲があいまいになるバグは Issue に記録し、別のセッションで直す
「待ち時間に」始めるテストを待つ間に施策Bの設計を始め、AI が施策Aの制約を施策Bに当てはめる待つ。思いついたことは別ファイルにメモだけする
「似ているから一緒に」やる2施策分のコンテキストで後半の品質が落ちる関連が深くても別セッションにし、依存関係は WBS で管理する

セッションをまたぐ情報は、ファイルに逃がす

コンテキストは作業用のメモリで、セッションが終われば消えます。残すべき情報は、種類ごとに置き場所を決めています。

情報の種類置き場所次のセッションでの戻し方
開発ルール・ワークフローCLAUDE.md自動で読み込まれる
施策の進捗.wbs/CURRENT.mdA-2 で読み込む
設計判断ADR必要なときに参照する
一時的な設計メモ.tmp/*.md必要なときに参照する
実装済みのコードGitファイルを読む

CLAUDE.md に何を置き、何を置かないかの線引きは「CLAUDE.mdの肥大化と圧縮の記録」に書きました。

セッションを終えるときは、必ず WBS を更新します。

1
NEW-11(リトライ上限の自動調整):
2
ステータス: B-8(実装中)
3
進捗: 設計完了、コア実装完了、テスト15/24件作成
4
残作業: テスト9件追加、QA実行、PR作成
5
ブランチ: feature/auto-adjust-retry-limit

これがないと、次のセッションの AI は「どこまで進んだか」が分かりません。同じ作業を繰り返すか、誤った前提で途中から始めることになります。長い回帰テストの結果待ちなどでセッションを区切るときも、「何を実行中で、完了の条件は何で、結果はどこに出るか」を WBS に書いてから終えます。予期せず中断したときに備えて、WIP: {施策名} - {現在のステップ} のようなコミットもこまめに残します。


完了後の空白を埋める:SessionEnd hook で次段階の Issue を起票する

PR をマージした後に、施策が止まる

PR をマージすると「施策完了」と感じて、別の作業に移ってしまいます。しかし本来は、その後にも段階が続きます。

1
Phase A: 機能実装(PR マージ)
2
↓ 1〜3日後
3
Phase B: 翌日監視・指標の確認
4
↓ 1週間後
5
Phase C: 効果測定レポート
6
↓ 必要なら
7
Phase D: 改善 PR

マージした後に何日も空白ができ、1ヶ月後に「あの施策、結局効果はあったのか」となることが何度かありました。次の段階の Issue を手で立てれば追えるのですが、マージのたびに立てるのは面倒で、忘れます。

仕組み

Claude Code の SessionEnd hook で、直前のコミットが「施策完了(C-11)」のときだけ、次段階の Issue を起票します。

.claude/settings.json
1
{
2
"hooks": {
3
"SessionEnd": [
4
{ "hooks": [{ "type": "command", "command": "bash .claude/hooks/session_end.sh" }] }
5
]
6
}
7
}
.claude/hooks/session_end.sh
1
#!/bin/bash
2
{
3
if ! gh auth status &>/dev/null; then
4
echo "gh not authenticated, skipping" >&2
5
exit 0
6
fi
7
8
last_commit_msg=$(git log -1 --pretty=%s)
9
# 施策完了パターン: 「feat(measure-xxx): C-11 マージ」など
10
if [[ "$last_commit_msg" =~ ^feat\(measure-([a-z0-9-]+)\):.*C-11 ]]; then
11
create_followup_issues "${BASH_REMATCH[1]}"
12
fi
13
} 2>> /tmp/session_end_hook.log
14
exit 0 # 何があっても 0 で終わる

create_followup_issues では、.docs/issue_templates/ のテンプレートに施策名を埋め込み、Phase B(翌日監視)と Phase C(効果測定)の Issue を立てます。Issue の本文には実施推奨日とチェックリストを入れます。

1
## 実施推奨日
2
2026-05-09(PR マージから1週間後)
3
4
## チェックリスト
5
- [ ] launchd ジョブのログを確認
6
- [ ] エラー件数の推移を確認(before/after)
7
- [ ] アラート発生件数の推移を確認
8
- [ ] 効果測定レポートをコメント追記

gh issue list --label phase-c --state open で、今週やるべきフォローアップが一覧できます。

踏んだ罠

  1. 同じ Issue が5個立った: 最初は無条件に起票していたので、同じ施策で何度も発火しました。コミットメッセージの C-11 で絞り、さらに起票前に既存の Issue をタイトルで検索して、あれば飛ばすようにしました
  2. hook のエラーがセッションに響いた: hook のスクリプトが非ゼロで終わると、次のセッションの起動時に hook 失敗のメッセージが出ました。エラーはログファイルに書き、終了コードは常に0にしています
  3. gh の認証切れで黙って失敗した: 冒頭で gh auth status を確かめ、未認証なら何もしないようにしました
  4. テンプレートの置換に sed を使っていた: 置き換える文字列にスラッシュなどが入ると壊れるので、bash の文字列置換(${body//\{measure\}/$measure})に変えました

効いた点

  • 「次にやること」が消えなくなりました。1週間たつと自分でも何をしていたか忘れますが、Issue に実施推奨日とチェックリストが残っています
  • 終わった Issue を見ると、「Phase B は終えたが Phase C は手つかず」という施策が見えるようになりました
  • Issue があれば、「この Issue の内容を実行してください」と Claude Code にそのまま渡せます。ただし本番に影響する作業は、人間がレビューする前提にとどめています

学んだこと

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

ログタグ・施策ごとの ON/OFF・フォールバックログを全施策に強制したことで、問題が起きたときの調査と対処が格段に速くなりました。

2. 記録しないものは、次のセッションには存在しない

AI との対話で出た施策案も、セッションの途中の進捗も、WBS に書かなければ次のセッションでは消えています。「WBS に登録する」「WBS を更新してから終える」を、手順の一部として固定しました。

3. 「完了」の定義を PR マージで終わらせない

施策の価値が分かるのは、マージした後の監視と効果測定です。そこまでを Issue として自動で残すことで、施策が途中で止まらなくなりました。


まとめ

  1. Markdown の WBS を、AI と共有する状態管理にする: 53施策の状態・依存・Go/No-Go のゲートを1ファイルに置き、AI に読ませ、更新させます
  2. AI は施策の候補と比較を出し、人間が決める: 制約と「星3以上」の絞り込みを最初に渡し、採否と優先順位は人間が判断します
  3. 11ステップと1施策1セッションで、抜け漏れと文脈の混線を防ぐ: 開始(ブランチ・把握・競合チェック)→ 仕様駆動開発 → 完了(ドキュメント・手順書・マージ)を、1つのセッションで1つの施策に限って回します
  4. 完了後のフォローアップを自動で起票する: SessionEnd hook で、翌日監視と効果測定の Issue を実施推奨日付きで残します

目的は「AI に任せる」ことではなく、「AI と人間の役割をはっきり分ける」ことです。AI は手順の実行と候補の列挙を担い、人間は各段階の判断を担います。

AI駆動開発での開発・自動化・監視の仕組みづくりについて、ご相談を受け付けています

お仕事のご相談

記事へのご質問・ご感想はこちらのフォームからお送りください

Article title:Claude Codeで53施策を回す施策ワークフロー:Markdown WBS、AIとの施策選定、1施策1セッション、完了後のIssue自動起票
Article author:45395
Release time:2026-04-03