/dev-workflow スキル

Goal

実装タスクを「探索 → 計画 → 実装 → 検証 → コミット」の流れで進め、検証（テスト・リンタ）を飛ばさずに品質を担保する。新規開発と既存改修で手順を使い分ける。

Principle

常に自分の作業を検証する。テストとリンタを通さずにタスクを完了扱いにしない。これがコード品質に対する最もレバレッジの高い実践。

適用範囲

• explore / plan がハーネス側の仕組み（Claude Code の Plan Mode 等）で既に済んでいる場合、その2フェーズは重複させず、implement 以降（テスト戦略 → verify → commit）から適用する。本スキルの中核価値は検証とコミットの規律にある。
• Plan Mode を持たない CLI（Codex）では explore から順に全フェーズを適用する。
• フローは「タスク単位」ではなく「変更対象単位」で選ぶ。1 つのタスクに新規モジュール追加・既存改修・設定/ドキュメントが同居する場合、対象ごとに new product / existing product / テストの無いタスクを使い分けてよい。
• テスト基盤自体が存在しないプロダクトコードでは、テストフレームワークの新規導入はスコープ判断としてユーザーに委ねる。導入しない場合でも test_first の精神は移植する（実装前に「失敗する検証スクリプト」を書き、期待どおりの理由で落ちることを確認してから実装に入る）。
• 依存/lockfile 更新は本スキルの分岐に当てはまらない。dependency-update スキルの領分なので、そちらの手順に寄せる。

テストの無いタスク（IaC / 設定 / ドキュメント）

Terraform 等の IaC、CI/設定ファイル、ドキュメントのようにユニットテストの概念が無いタスクでは、フローを次のように読み替える:

• test_first はスキップする（挙動不変のリファクタも同様）。再現テストを書く対象が無い。
• verify を静的検証に読み替える。該当するものを実行して全て通す:
  • Terraform: fmt -check / validate / tflint / terraform plan -out→show -json での生成 JSON 検証
  • GitHub Actions: actionlint
  • 共通: markdownlint / secret-scan（gitleaks）/ 生成物の再生成差分チェック
• 環境要因を切り分ける。IaC の verify はローカルの .terraform backend キャッシュや sandbox のネットワーク制限で失敗しうる（認証エラー・プロバイダ DL 失敗など）。変更ファイルの種別を見て「コード起因か環境要因か」を切り分け、環境要因ならクリーン再実行（キャッシュ退避 / sandbox 無効）で確認する。
• 静的検証で終わらせない。lint が全部通っても実行時にしか出ない不具合は残る（実例: 整形結果がタブでなくスペース、パイプ下で tput cols が既定値を返す、jq の index() 内で . の束縛が変わる）。変更した機能を実際に動かし、出力そのものを読み返すまで verify とみなさない（cat -A でタブ/スペースを見る、CLI 側の結果と突き合わせる）。手で押さないと確認できない経路に当たったときの検証点の作り方は references/verification-points.md を参照。
• verify や反映が破壊的にならないか事前に確認する。稼働中の共有プロセス（開いている nvim セッション、ユーザーのターミナル）を止める必要がないか調べ、まず使い捨て環境（docker run --rm、テスト用ペイン）で確認してから本番反映の同意を取る。テスト用に立てたものを片付けるところまでを verify に含める。

新規プロダクト開発（new product）

1. explore: Plan Mode で既存コードと構造を読み、関連モジュール・依存・既存パターンを把握する。このフェーズではコードを書かない。
2. plan: 詳細な実装計画を立てる。テスト戦略（対象・エッジケース・期待挙動）を定義し、適用するリンタ・型チェッカを特定する。着手前にユーザー確認を取る。
3. implement: 計画に沿って実装する。各単位の実装と同時か直後にテストコードを書く。大きな一括変更より小さな増分変更を優先する。
4. verify: テストを実行して全て通ることを確認。リンタ（eslint, ruff, golangci-lint 等）と型チェッカ（tsc, mypy, pyright 等）を実行し全エラー・警告を解消。失敗したら直して全て通るまで再実行する。実行は verify-runner サブエージェントへの委譲を推奨（下記「検証ルール」参照）。
5. commit: commit-and-draft-pr スキルに委譲する（ブランチ確認 → ステージング → コミット → push → PR反映まで一貫して任せる）。git commit を単体で直接実行しない。

既存プロダクト改修（existing product）

1. explore: 関連コード・git 履歴・既存テストを読み、現挙動を理解。問題の根本原因や変更範囲を特定する。コードは書かない。
2. plan: blast radius を最小化し不要な変更を避ける計画を立てる。影響範囲をカバーする既存テストと、必要な新規/修正テストを洗い出す。
3. test_first: 変更前に、バグを再現するか新挙動を検証する失敗するテストを書く。実行して、期待どおりの理由で失敗することを確認する。
4. implement: 問題修正・改修に必要な最小限の変更のみ行う。無関係なリファクタリングはしない。
5. verify: 失敗していたテストが通ることを確認。関連テスト一式を回して回帰がないことを確認。リンタ・型チェッカを実行し全エラーを解消。全て通るまで再実行する。実行は verify-runner サブエージェントへの委譲を推奨（下記「検証ルール」参照）。
6. commit: commit-and-draft-pr スキルに委譲する（ブランチ確認 → ステージング → コミット → push → PR反映まで一貫して任せる）。git commit を単体で直接実行しない。

test_first の読み替え

標準的な red → green が成立しない場合は、次の順で代替する:

• 型・契約変更で変更前のテストがコンパイルできない場合、型追随に必要な最小限の修正だけを先に行い、その後に失敗する期待値を追加する。
• テストコード自体を変更する場合、対象実装を一時的に壊し、追加・変更したテストが期待どおり落ちることを確認してから必ず復元する。
• ガード・検査スクリプトを追加する場合、正常系だけでなく意図的な違反で非ゼロ終了する negative test を行う。
• 実時間待ちなど再現テストのコストが変更規模に不釣り合いな場合、スキップ理由を明示し、既存テスト・境界値・設定値の関係を検証する。

代替検証で実装を一時変更した場合、git diff で完全に復元されたことを確認する。

検証ルール（共通）

• テスト・リンタの実行は、利用可能なら verify-runner サブエージェント（Agent tool で subagent_type: verify-runner）に委譲する。長いテスト・lint 出力を隔離してメインコンテキストの汚染を防ぐため。失敗があればメインエージェントが修正し、再度 verify-runner を起動して全て通るまで繰り返す。verify-runner が使えない環境では自分で直接実行する。
• バックグラウンド検証は、全結果を受け取るまで完了扱いにしない。結果未着の状態を success と報告しない。
• verify-runner の報告項目を依頼したコマンド一覧と突き合わせ、欠落や途中終了があれば残りを再実行する。
• verify 完了後に git status --untracked-files=all と git diff を確認し、想定した変更ファイルだけであること、一時ファイルや退避物が残っていないことを確認する。
• 実装後は必ずテストを実行する。スキップしない。
• 実装後は必ずリンタを実行し、コミット前に全エラーを解消する。
• 型チェックが構成されているプロジェクトでは実行し全エラーを解消する。
• test/lint/typecheck コマンドが不明なら、まず package.json / Makefile / pyproject.toml 等の設定ファイルを確認する。
• テスト失敗時は根本原因に対処する。エラー抑制やテストスキップで逃げない。
• 既存テストがないプロジェクトでは、プロジェクトの慣習に従ってテストファイルを作る。
• 既存の lint 指摘があるリポジトリでは、HEAD ベースラインとの差分で評価する。git show HEAD:<file> 等で変更前の指摘件数を取り、「新規混入ゼロ」を示す。verify-runner の報告に既存違反と新規違反が混在する場合も同様。
• 「環境差」と結論づける前に、ローカルのツールバージョンを CI と突き合わせる（which / --version で mise 等の解決先を確認）。そのうえで CI と同一条件（--isolated 等）で再現を取る。
• リンタが落ちたら設定の除外ではなくコード側を直す。ルールを disable / exclude して緑にするのは、その設定の意図を骨抜きにする行為。
• verify タスクがリポジトリ全体を舐める構成では、作業ツリーの無関係な差分（未追跡ファイル等）が verify を汚染する。変更ファイルにスコープした確認を併用し、残存指摘が自分の変更由来かを切り分ける。

Notes

• リポジトリ常設の lint hook（lint-changed.sh）が編集完了時に対象リンタを自動実行し、検証漏れを可視化する。本スキルの verify はそれと併用する。
• 言語別の lint/format コマンドは触れたファイルに応じて path-scoped rules（.claude/rules/, ~/.claude/rules/）が読み込む。
• 並行更新のあるリポジトリでは、編集の直前に対象ファイルを Read し直し、最新状態に追従してから変更する（upstream main の進行で対象ファイルが変わっていることがある）。