Claude Code /goal 実務事例集 — テスト全件通過・デプロイ監視・大規模リファクタリング自動化

「/goal で何ができるのか」を、3つの完全形CASEで示す。ゴール文・context・done whenを丸ごとコピペして、自分のリポジトリで実行できる形で公開する。

なぜ「完全形」が大事か

実例として「テスト自動化」「デプロイ監視」と書かれた記事は多いが、実際にコピペして動くゴール文を載せているものは少ない。

/goal の精度は完了条件の書き方に9割依存する。1文字違うだけで評価器の判定が変わるため、動く実例こそが最強の学習素材だ。

CASE 1: テスト全件通過まで自走

認証モジュールのリファクタリング後、テストが落ちている状態から全件通過まで自律実行する。

ゴール文（完全形）

/goal src/auth/ のリファクタリング後、test/auth/ のテストがすべて通り、
npm test が exit 0 で完了する状態, or stop after 15 turns

context:
- Next.js 16 + TypeScript プロジェクト
- src/auth/ を better-auth ライブラリへ移行中
- migration スクリプトは scripts/migrate-auth.ts に完成済み
- 環境変数 DATABASE_URL, AUTH_SECRET が .env に設定済み

done when:
- test/auth/ 配下の全テストが exit 0
- npm test --coverage で auth モジュールが80%以上
- TypeScript 型エラーが0件（npm run typecheck で exit 0）

do not:
- migrations/ フォルダは触らない
- 既存のAPIエンドポイント（/api/users/*）の引数を変更しない
- node_modules / package-lock.json は変更しない

progress tracking:
completed steps を progress.md に随時記録すること
失敗したテストごとに原因と修正アプローチを decisions.md に書く

想定動作

Claudeが npm test を実行 → 失敗テスト一覧を取得
失敗の原因を分析（progress.mdに記録）
修正コードを書き、再度 npm test
通るまで 1-3 を繰り返し、すべて exit 0 になったら評価器が「達成」を判定して停止

中規模リポジトリで 平均3-5ターン、複雑な型エラー含む場合は10-15ターン。

CASE 2: デプロイ監視 — Cloudflare Pages ヘルスチェック

Cloudflare Pages へのデプロイ後、ヘルスチェック5項目すべて pass するまで監視する。

ゴール文（完全形）

/goal Cloudflare Pages にデプロイした最新版が、ヘルスチェック5項目を
すべてpassしている状態を確認, or stop after 10 turns or 15 minutes

context:
- 直前に pnpm build && wrangler deploy 実行済み
- 本番URL: https://kanautech.jp
- ヘルスチェックスクリプト: scripts/health-check.sh
  - / の応答が200
  - /blog の応答が200
  - /api/health の "ok": true
  - LCP が 2.5s 未満
  - 画像LCP（/images/hero）が3秒以内にロード完了

done when:
- scripts/health-check.sh の全5項目が exit 0
- health-check の結果が health-report.md に記録される
- 各項目のレスポンスタイム実測値が記録される

do not:
- 本番環境への破壊的変更（DB変更・キャッシュフラッシュ等）は実行しない
- デプロイのロールバックは絶対に自動実行しない（人手の最終確認必須）

progress tracking:
失敗した項目は原因仮説と次の検証手順を decisions.md に記録

想定動作

Claudeが scripts/health-check.sh を実行 → 失敗項目を取得
失敗項目の原因仮説をログから推定（例：LCP超過なら画像最適化不足）
数分待って再実行（Cloudflareキャッシュ反映待ち）
全項目passするまで繰り返し

重要な安全装置

do not ブロックに「ロールバックは自動実行しない」を明記している。評価器が誤判定した場合に正常デプロイを巻き戻すリスクを排除する。 デプロイ系の /goal ではこの安全装置を必ず付ける。

CASE 3: 大規模リファクタリング — TypeScript 型エラー0件まで

レガシーコードの any 型を排除し、TypeScript の --strict 設定で型エラー0件にする。

ゴール文（完全形）

/goal src/ 配下の TypeScript 型エラーが0件になり、tsconfig.json の strict: true で
npm run typecheck が exit 0 で完了する状態, or stop after 25 turns

context:
- Next.js 16 + TypeScript 5.6 プロジェクト
- 現状: src/ 配下に any型が47箇所、型エラー約120件
- tsconfig.json を strict: true に切替済み
- 移行対象: src/components/, src/lib/, src/app/ の全 .ts/.tsx
- 型定義ファイル: src/types/ に既存型あり

done when:
- npm run typecheck が exit 0
- npm test が exit 0（型変更による既存テスト破壊なし）
- src/ 配下の any 型出現回数が0（grep -r ': any' src/ | wc -l が 0）
- 変更したファイル数と削除した any 型数を refactor-summary.md に記録

do not:
- public/ 配下のJSONファイルは触らない
- src/lib/legacy/ は非対象（別フェーズで対応予定）
- @ts-ignore / @ts-nocheck コメントの新規追加は禁止

progress tracking:
ファイルごとに「修正前any数 / 修正後any数」を progress.md に随時記録
複雑な型推論が必要な箇所は decisions.md に判断根拠を残す
plan.md には開始前に「先に直すファイル順序」を書き出す

想定動作

開始時に plan.md で対応順序を決定（依存度の低いものから）
ファイルごとに any 型を順次置換、各回 npm run typecheck で進捗確認
型エラーが連鎖的に発生した場合は decisions.md に記録しつつ深掘り
全120件のエラーがゼロになるまで繰り返し

このCASEは 10-15ターンが想定。Pillarで触れた「複数時間かかる作業」に該当するため、plan.md と decisions.md の併用が必須。

中小企業の業務応用への布石

3つのCASEは開発作業だが、「完了条件が明確な業務」ならコード以外でも同じパターンが効く。

介護施設の 日報集約：各スタッフのチャット内容を summary.md にまとめる
税理士事務所の 法令変更チェック：今月のe-Gov更新と顧客への影響を impact.md に出力
飲食店の 在庫発注計算：POS データから次週発注量を order-draft.csv に作成

ゴール文の構造（context / done when / do not / progress tracking）は完全に同じだ。

📘 業種別の実装パターンとROI試算は中小企業の業務自動化 — 介護・福祉・士業・飲食向け実装パターンで詳説。

よくある質問

テスト全件通過まで何ターンかかりますか？

中規模リポジトリ（50ファイル程度）で平均3-5ターン、TypeScript型エラー含む大規模リファクタリングで10-15ターンが目安だ。ターン数はCLAUDE.mdの充実度と完了条件の明確さに大きく依存する。

デプロイ失敗時のロールバック自動化は可能ですか？

可能だが推奨しない。/goal で「ヘルスチェック失敗時にロールバック」と書くと評価器が誤判定した場合に正常デプロイをロールバックしかねない。ロールバックは人手の最終確認を残すべきだ。

リファクタリング中に矛盾した変更が起きませんか？

progress.md への進捗書き出しを完了条件に含めることで防げる。各ターンで「前のターンの決定」を読み返してから次のステップに進む仕組みになり、矛盾した修正を避けられる。

CI/CD から呼び出せますか？

可能だ。claude -p "/goal ..." で非対話実行ができ、GitHub Actions などから job 内で呼び出せる。詳細はSpoke『Remote Control + CI/CD統合』を参照。

中小企業の業務にも応用できますか？

可能だ。コードを書く作業以外でも、日報集約・在庫計算・申告書類のドラフト生成など「完了条件が明確な業務」なら同じパターンが使える。Atomic DX™の発想で業務を分解すると適用範囲が広がる。

Claude Code /goal 完全ガイド — シリーズPillar
Claude Code /goal 完了条件の書き方 — 5つのベストプラクティス — ゴール文の書き方詳細
中小企業の業務自動化 — 介護・福祉・士業・飲食向け実装パターン — 業種別応用
Claude Code Remote Control で /goal を外部制御 — CI/CDパイプライン統合 — CI/CD連携

なぜ「完全形」が大事か

CASE 1: テスト全件通過まで自走

ゴール文（完全形）

想定動作

CASE 2: デプロイ監視 — Cloudflare Pages ヘルスチェック

ゴール文（完全形）

想定動作

重要な安全装置

CASE 3: 大規模リファクタリング — TypeScript 型エラー0件まで

ゴール文（完全形）

想定動作

中小企業の業務応用への布石

よくある質問

テスト全件通過まで何ターンかかりますか？

デプロイ失敗時のロールバック自動化は可能ですか？

リファクタリング中に矛盾した変更が起きませんか？

CI/CD から呼び出せますか？

中小企業の業務にも応用できますか？

関連記事

参照