autonomous-dev

name	autonomous-dev
description	コードを変更する実装作業（機能追加、バグ修正、リファクタリング、テスト追加）を始めるときに使うスキル。 「実装して」「作って」「追加して」「直して」「書いて」といった依頼のほか、 方針合意後に「進めて」「お任せ」「どんどんやって」と任された場合にも使う。 調査・質問回答・レビューだけで完結するタスクや、方針が未決で相談段階のものには使わない。

Autonomous Dev - 自律実装スキル

方針が固まったら、確認を挟まず一気に完成まで持っていく。品質は、セルフレビューの反復と「実際に動かして確かめる」ことで担保する。

ユーザーが方針に合意した後の逐次確認は、作業を中断させるだけで価値を生まない。代わりに、自分自身で何度もレビューと改善を回すことで、ユーザーの時間を奪わずに高い品質を実現する。

前提: プロジェクトの作法を最初に特定する

このスキルは特定の言語・ツールを前提にしない。着手時に作業対象プロジェクトの作法を特定し、以降のフェーズではそれを使う。

• 品質ゲートのコマンド: プロジェクトの指示ファイル（CLAUDE.md / AGENTS.md 等）→ CI 設定（.github/workflows/ 等）→ package.json / pyproject.toml / Makefile の順に確認する。lint・テストに加えて、型チェック・ビルド・フォーマットチェックがあればそれも含める
• 適用ルール: CLAUDE.md のルール表や .claude/rules/ から、変更対象ファイルに適用されるルールを確認する。実在を確認したルールだけに従う（例: robustness.md、code-intent-documentation.md）
• 進め方のルール: ファイル単位のルールに加えて、worktree・ブランチ運用・並列作業・PR フローなど、作業の進め方を定めるルールの有無もここで確認する

以降、本文の lint & test はここで特定したコマンド群を指す。例: pnpm のプロジェクトなら pnpm lint:fix && pnpm lint && pnpm test、Python なら flake8 + pytest など。

ワークフロー

Phase 1: 方針確認（ユーザーと対話するのは原則ここだけ）

実装の方向性が不明確な場合のみ、ユーザーに確認する。

• 何を作るか / 何を直すか
• 設計上のトレードオフがある場合の判断

方針が明確なら（ユーザーが「進めて」と言っている、要件が自明、など）、この Phase はスキップして即座に Phase 2 に入る。

Phase 1 を抜けたら、以降はユーザーに確認を求めない。 完成するまで自律的に進める。

例外として、次に該当したときだけは手を止めて確認する。

• データ削除・本番環境への影響など、破壊的・不可逆な操作が必要になった
• 作業中の発見で、合意した方針自体が成り立たないと分かった
• スコープが当初の合意から大きく膨らむ

これ以外の迷いは自分で判断して進める。

Phase 2: 全体像の把握

設計やUXの判断は、局所的なコードだけ見ていると的外れになる。実装に入る前に、変更が影響する範囲の全体像を掴む。

原因や変更箇所が特定済みのタスクでも、このフェーズを丸ごと飛ばさない。最低限、変更箇所の呼び出し元と既存テストのカバー範囲は確認する。「分かっているつもり」の小さな修正が、呼び出し元の暗黙の前提を壊す事故はここで防ぐ。

UI が絡む変更の場合

devtools（Chrome DevTools MCP 等）で画面を確認できる環境なら、関係する画面を渡り歩いて現状のUIを把握する。

• 変更対象の画面をスクリーンショットで確認
• 関連する画面（遷移元・遷移先、同じコンポーネントを使っている画面）も確認
• 既存のレイアウト、間隔、色使いのパターンを目で見て理解する

コードだけ読んでも、実際の見た目やユーザーの操作感は分からない。画面を見ることで「ここに追加すると狭くなる」「この色は周囲と合わない」といった判断ができる。ここで撮った変更前のスクリーンショットは、Phase 5 の最終確認で変更後と見比べる材料にもなる。

画面を確認する手段がない環境では、コードとスタイル定義から把握した上で、実画面を確認できていないことを報告に明記する。

UI が絡まない変更の場合

主要ユースケースを洗い出し、データの流れや呼び出し関係を把握する。

• 変更対象の関数・モジュールがどこから呼ばれているか
• 入力されるデータのバリエーション
• 複数モジュールを跨ぐ変更なら、ストーリーテスト（ユースケース単位の統合テスト）を設計に組み込む

共通

• 既存の関連テストを読んで、どこまでカバーされているか把握する
• 変更の影響範囲を特定し、Phase 3 のテスト設計に反映する

Phase 3: テストを先に書く

実装コードより先にテストを書く。テストが実装の仕様書になる。

1. テスト設計 - 何をテストするか洗い出す

   • 機能追加なら、正常系（主要ユースケース）・境界値（エッジケース、空入力、最大値）・異常系（エラーパス、不正入力）を網羅する
   • 小さなバグ修正なら、最低限「バグを再現する回帰テスト1本」。減らしてよいのはケース数であって、先に書くこと自体は省略しない
   • 既存テストとの整合性を確認する

2. テスト実装 - 丁寧に書く

   • テスト名は「何が」「どうなるべきか」を日本語で明確に
   • 1テスト1アサーションの原則（複雑なケースは例外OK）
   • テストデータは意図が分かるものを選ぶ（"test" ではなく具体的な値）
   • プロジェクトにテスト規約があれば従う（「前提」で特定したルール）

3. テスト実行 - 新しく書いたテストが「未実装」を理由に失敗することを確認する

   • 既存テストはパスしたままであること。全テストを巻き込んで落ちていたら何かがおかしい
   • 想定外の理由（import エラー、設定ミス等）で落ちていないかチェック
   • この確認は省略しない。失敗を一度も見ていないテストは、何も検証できていない可能性がある
   • 例外: 挙動を変えない変更（リファクタリング、既存挙動へのテスト追加）では、新テストが現行実装でパスすることを先に確認する。変更後もパスし続けることが「挙動を保存した」証拠になる

Phase 4: 実装

テストを通すための最小限の実装を書く。

• 変更対象ファイルに適用されるプロジェクトルール（「前提」で特定）に従う
• 実装したら lint & test を実行
• テストが通らなければ、テストか実装を修正（テストの期待値が間違っている場合もある）

Phase 5: セルフレビュー（ここが核心）

実装が動いたら、ここから品質を磨き上げる。改善点が見つからなくなるまでレビューと修正を繰り返す。

各ラウンドで以下の観点をチェックし、問題を見つけたら即座に修正してから次のラウンドに進む。

レビュー観点

1. 正しさ - ロジックに穴はないか。エッジケースを見落としていないか
2. プロジェクト規約 - 変更ファイルに適用されるルールやライブラリの規約に従っているか（例: TypeScript なら neverthrow・ts-pattern・Zod・デザイントークン）
3. テストの十分さ - カバーすべきケースが漏れていないか。テスト自体が正しいか
4. コードの意図 - WHY のコメントが必要な箇所に書かれているか
5. シンプルさ - 不要な抽象化、過剰なエラーハンドリング、YAGNI違反がないか
6. 型・入力の安全性 - 言語の型システムや検証機構を素通りしていないか（例: TypeScript なら any や型アサーション as の濫用）
7. 波及先との整合性 - 呼び出し元・関連テスト・設定・ドキュメントに影響が漏れていないか。周辺コードのスタイルやパターンと調和しているか

レビューの進め方

ラウンド N:
  1. 変更した全ファイルを読み直す（差分ではなくファイル全体）
     ラウンド1では、呼び出し元・関連テスト・設定・ドキュメントも開いて波及を確認する
  2. 上記7つの観点でチェック
  3. 問題を発見 → 修正 → lint & test 実行
  4. 修正があった → ラウンド N+1 へ
  5. 修正がなかった → 最終確認へ

最低2ラウンド。修正が発生しなくなるまで回す。目安は3ラウンド程度。1ラウンド目で粗い問題、2ラウンド目で細かい問題、3ラウンド目で確認、という流れになることが多い。「修正ゼロ」のラウンドも、7つの観点を全て当てた上でのゼロであること。流し読みして「修正なし」と数えるのは収束ではない。

最終確認

レビューが収束したら、完了と言う前に次の3つを確認する。

1. lint & test 全パス - 特定した品質ゲートを一度通しで実行する
2. 動作確認 - テストが通ることと動くことは別。実際に動かす
   • UI 変更: devtools で変更後の画面を確認し、Phase 2 で撮った変更前と見比べる。同じコンポーネントを使う関連画面も確認する。レイアウト変更なら複数のビューポート幅でも確認する
   • API: 実リクエストを投げる。CLI: 実コマンドを実行する。バッチ: 最小入力で実行する
   • 動かす手段がない環境では、動作確認できていない旨を報告に明記する。「手段がない」とは確認用のツールや環境が存在しない場合を指す。手間がかかるだけなら手段はある
3. 混入チェック - git status と git diff を見て、意図しない変更・デバッグ用コードの残骸・無関係ファイルが紛れていないか確認する

Phase 6: push・PR への接続（依頼に含まれる場合）

commit・push・PR 作成まで依頼されている場合は、プロジェクトの PR フロールールに接続する。Phase 5 のセルフレビューは内省であり、PR 前に求められる外部レビューの代替にはならない。

• push 前: CI で実行されるチェックをローカルで全て実行する（ci-workflow.md）
• PR 作成前: codex review 等の外部レビューを規定回数実施し、記録する（pr-self-review.md。hook＝ツール実行を自動ブロックする仕組みで強制されるプロジェクトもある）
• PR 作成後: CI が全て pass するまで監視する。通るまで「完了」と報告しない（pr-ci-watch.md）

これらのルールがないプロジェクトでも、push 前に CI 相当のチェックをローカルで通すことだけは省略しない。

依頼に push・PR まで含まれるか不明な場合は、push せずに Phase 7 で報告し、push・PR の要否を添える。push は外部に出る不可逆寄りの操作なので、Phase 1 の例外（破壊的・不可逆な操作）と同じ扱いにする。

Phase 7: 報告

完了したら、ユーザーに簡潔に報告する。

報告に含めるもの:

• 何を実装したか（1-2行）
• セルフレビューで見つけて修正した主な問題（あれば）
• テスト結果と動作確認の結果
• PR フローを通った場合は、外部レビューの指摘と対応（修正したもの / あえて修正しなかったもの＋理由）

報告に含めないもの:

• 各ステップの詳細な経緯
• 「〜しました」の羅列
• 自明な情報の繰り返し

時間圧力がかかったとき

「急ぎで」「デモまでに」と言われても、ワークフローを黙って崩さない。縮めてよいものと縮めてはならないものを区別する。

縮めてよい	縮めてはならない
Phase 2 の調査範囲（呼び出し元と既存テストの確認は残す）	テストを先に書くこと（回帰テスト1本まで減らすのは可）
テストケース数（バグ修正なら回帰1本まで）	Phase 3 のテスト実行確認（失敗確認、挙動保存ならパス確認）
レビューラウンド数（最低の2回まで）	lint & test 全パス
動作確認の範囲（変更箇所そのものの確認は残す）	動作確認を実施すること自体
報告の詳しさ	git status / git diff での混入チェック

時間圧力はアンチパターン表と Phase 6 の外部レビュー・CI 監視を無効化しない。縮めた場合（レビューを2ラウンドで打ち切った・動作確認の範囲を絞った等）は、何をどこまで縮めたかを報告に含める。縮めてはならない側が時間内に収まらないなら、品質を黙って落とすのではなく、間に合わないことと残作業をその時点でユーザーに報告する。

アンチパターン

やりがち	なぜダメか	代わりに
実装の途中で「この方針でいいですか？」	ユーザーの時間を奪う	方針は Phase 1 で合意済み。迷ったら自分で判断
「原因は分かっている」と Phase 2 を飛ばす	小さな修正ほど呼び出し元の前提を壊したことに気づけない	呼び出し元と既存テストだけは必ず確認
「3行の修正だからテスト不要」	回帰したとき誰も検知できない	回帰テスト1本を先に書く
テストを後から書く	実装に引きずられて甘いテストになる	テストを先に書く
セルフレビュー1回で完了	最初のレビューでは構造的な問題を見落としやすい	最低2ラウンド、収束するまで回す
diff だけ見てレビュー	文脈を見失い、周辺との不整合を見逃す	ファイル全体を読み直す
テストが通ったので動かさずに完了報告	結合部の不具合や見た目の崩れはテストの外で起きる	最終確認で実際に動かす
スキル記載の例のコマンドをそのまま実行	pnpm ... は一例。プロジェクトごとにコマンドは違う	「前提」で特定したコマンドを使う
「完了しました」だけ報告	ユーザーが変更内容を把握できない	何を変えたかと、レビューで直した点を簡潔に