dev-workflow

name	dev-workflow
description	タスク実行の標準ワークフロー。plan.md のタスクを実行する際に必ず使用する。 「次のタスクを実行」「plan.md に従って進めて」「標準作業フローで」「タスクNを実施」 といった指示で発動する。git worktree での分離作業、品質ゲート（静的解析・テスト・ codex レビュー）、ユーザー確認、KPT ふりかえり、squash マージまでの全12ステップを ガイドする。タスク実行に関連する指示があれば積極的に使用すること。

標準作業フロー

タスクごとに以下の12ステップを順番に実行する。各品質ゲートは問題が 0 になるまでループする。ステップをスキップしてはならない。

ステップ一覧

1. 計画（Plan モード）

Plan モードに入り、docs/plan.md を読んで対象タスクの実装計画を立てる。

• EnterPlanMode で Plan モードに入る
• docs/plan.md の対象タスクを読み込む
• Explore エージェントでコードベースを調査する
• Plan エージェントで実装設計を行う
• 完了条件をリスト化し、計画ファイルに記載する（後のステップ7で照合する）
• ExitPlanMode でユーザーの承認を得てから実装に進む

2. 環境チェック

作業に必要なツールと設定ファイルを事前に確認する。

# ツールの存在確認（プロジェクトに応じて変更）
which docker qlty luacheck 2>/dev/null

• テスト対象の設定ファイル（kong.yml, keycloak-client.json 等）の値を読んでからテストケースを設計する
• 不足ツールがあればインストールまたはユーザーに報告する

3. git worktree 作成

Agent ツールの isolation: "worktree" でブランチを分離する。main を直接変更しない。

作成後、最初に main と同期する:

git merge main

worktree 内で作業が完了するまで main には一切触れない。

4. 作業実施

コード変更・ドキュメント作成等を行う。

• 変更は最小限に保つ
• 既存のコードパターン・スタイルに従う

5. 静的解析ゲート

プロジェクトの静的解析ツールを実行する。問題が 0 になるまで修正をループする。

このプロジェクトでのコマンド:

qlty check --all
luacheck kong/

ループ条件: 問題が 0 件になるまで修正して再実行。

6. テストゲート

テストを実行する。問題が 0 になるまで修正をループする。

• テストが存在しない場合でも、ビルド確認は行う
• コード変更を伴うタスクでは、ビルドが通ることを確認する

# ユニットテスト
busted spec/unit/

# カバレッジ計測（コード変更を伴うタスクで実施）
busted --coverage spec/unit/
luacov kong/plugins/oidc/
# luacov.report.out の Summary でファイル別・全体のカバレッジを確認
# 閾値: ファイル別 95% 以上、全体 95% 以上（詳細は docs/test-strategy.md 3.3）

# ビルド確認
docker build -t kong:kong-oidc .

ループ条件: テスト/ビルドが全て通り、カバレッジが閾値以上になるまで修正して再実行。

7. 完了条件ゲート

ステップ1で整理した完了条件を1つずつ照合する。

• 全条件を満たすまで修正をループする
• 条件を満たせない場合はユーザーに相談する

加えて、バンドルスクリプトによるドキュメント同期チェックを実行する:

bash .claude/skills/dev-workflow/scripts/check-test-doc-sync.sh

テストスクリプトと README.md のテストケース ID が一致しない場合はエラーになる。テストケースを追加・削除した場合は README.md も更新すること。

8. codex レビューゲート

codex によるレビューを実施する。

/codex:rescue Review ...

• 指摘が 0 件になるまで修正をループする
• 修正後はステップ5（静的解析）から再実行する

9. ユーザー確認（必須・スキップ不可）

動作確認できる環境を準備し、確認手順を提示する。

• コード変更: サービス起動手順と確認方法を提示
• ドキュメント変更: プレビュー確認手順を提示（VS Code で開く等）
• ユーザーの承認を得るまで次のステップに進まない

このステップは絶対にスキップしない。 ドキュメントのみの変更でも必ず実施する。

10. ユーザー指摘対応

ユーザーから変更指示があった場合、ステップ5（静的解析）からやり直す。

• 指摘を反映して修正
• 静的解析 → テスト → 完了条件 → codex レビュー → ユーザー確認のサイクルを再実行

11. ふりかえり

KPT（Keep / Problem / Try）形式で振り返り、worktree 内で反映する。

• Keep: うまくいったこと、継続すべきこと
• Problem: 問題があったこと、改善が必要なこと
• Try: 次回試すこと、改善アクション

反映先:

• docs/memory.md: 開発ルール・技術知見の追加・更新
• docs/plan.md: タスクや方針の見直し
• CLAUDE.md: アーキテクチャや手順の更新（必要に応じて）

12. マージ

全ゲート通過後、main にマージする。

# main の状態を確認
cd <project-root>
git status  # clean であること

# squash マージ
git merge --squash <worktree-branch>
git commit -m "コミットメッセージ"

# worktree クリーンアップ
git worktree remove <worktree-path>

タスク1つにつきコミット1つを原則とする。

最後に docs/plan.md のタスクチェックボックスを更新する。

重要なルール

• 不要な確認質問をしない: 「次はどうしますか？」と聞かず、自分で判断して進める
• テストが通らないとタスク完了にならない: コード変更のみでチェックボックスを埋めない
• ユーザー確認は必須: どんな変更でもステップ9をスキップしない
• ふりかえりはマージ前: worktree 内でふりかえりを反映してからマージする