autonomous-dev

TDD 開発ワークフロー

テスト駆動開発、Git worktree による分離、コードレビュー、CI 検証、E2E テストを徹底する、完全な開発ワークフローです。2 つのモードで動作します。人間がガイドするセッション向けの対話モード（デフォルト）と、GitHub の issue を完全に無人で実装する自律モードです。

絶対遵守のルール — MANDATORY と記された各ステップは必須です。 これらのステップを省略したり、後回しにしたり、実行するかユーザーに尋ねたりしないでください。ワークフローの一環として自動的に実行してください。これには PR の作成、CI の完了待ち、E2E テストの実行、レビュアーの指摘への対応が含まれます。

---

モードの判定

対話モード（デフォルト）

開発者が参加している場合に使用します。このワークフローでは、次のことを行います。

• 実装に進む前に、ユーザーに設計の承認を求めます
• 設計キャンバスを提示し、フィードバックを待ちます
• 重要な判断が必要な段階で一時停止し、ユーザーの入力を求めます
• 最終状況を報告し、マージするタイミングはユーザーに委ねます

自律モード

scripts/autonomous-dev.sh ラッパー内で実行すると開始します。このワークフローでは、次のことを行います。

• すべての判断を自律的に行います（以下の「判断ガイドライン」を参照）
• 質問する代わりに、GitHub issue に進捗コメントを投稿します
• 設計ドキュメントを作成しますが、対話形式での承認は省略します
• 検証後に停止し、マージは行いません（レビューエージェントが対応します）
• 作業の進行に応じて、issue の本文にある要件チェックボックスにチェックを入れます

---

クロスプラットフォームに関する注意事項

このスキルは、skills.sh をサポートする IDE で利用できます。このドキュメントにある汎用動詞は、お使いの IDE のツールに読み替えてください（Claude Code の Bash は Cursor のターミナルに相当する、など）。フックによる強制は Claude Code、Codex CLI、Kiro CLI で利用できます。フックがインストールされていないクライアントでは、各ステップを手動で実行してください。求められる規律は同じです。

IDE の全一覧と動詞からツールへの対応表については、references/cross-platform.md を参照してください。

---

開発ワークフローの概要

すべての機能開発とバグ修正で、以下のワークフローに従ってください。

Step 1:  DESIGN CANVAS (Pencil MCP, if available)
Step 2:  CREATE GIT WORKTREE (MANDATORY)
Step 3:  WRITE TEST CASES (TDD)
Step 4:  IMPLEMENT CHANGES
Step 5:  LOCAL VERIFICATION
Step 6:  CODE SIMPLIFICATION
Step 7:  COMMIT AND CREATE PR          -- MANDATORY
Step 8:  PR REVIEW AGENT               -- MANDATORY
Step 9:  WAIT FOR ALL CI CHECKS        -- MANDATORY
Step 10: ADDRESS REVIEWER BOT FINDINGS -- MANDATORY
Step 11: ITERATE UNTIL NO BLOCKING FINDINGS
Step 12: E2E TESTS & READY FOR MERGE   -- MANDATORY
Step 13: CLEANUP WORKTREE

---

ステップ 1：設計キャンバス

新しい UI の作業、ユーザー向け機能、アーキテクチャの決定、複雑なデータフローについて、設計キャンバスを作成します。動作を変更しない簡単な修正やリファクタリングでは省略してください。

• Pencil MCP に対応する IDE：docs/designs/<feature>.pen を作成します。
• Pencil MCP に対応していない IDE：docs/designs/<feature>.md を作成します。

Pencil MCP の完全な呼び出し手順、Markdown キャンバスのテンプレート、モード別（対話モードと自律モード）の承認ゲートについては、references/design-canvas.md を参照してください。

---

ステップ 2：Git Worktree の作成（MANDATORY）

すべての変更は、分離された Git worktree 内で開発しなければなりません。メインのワークスペースで直接開発しないでください。

フックがインストールされている場合は、block-commit-outside-worktree.sh フックによって強制されます。worktree 外でのコミットは自動的にブロックされます。メインへの直接の push は block-push-to-main.sh によってブロックされます。

Worktree を使う理由

• 分離：機能や修正ごとに独自のディレクトリを用意し、相互干渉を防ぎます
• 並行作業：複数の機能を同時に進められます
• メインのワークスペースをクリーンに保つ：メインのチェックアウトを main のままにし、すぐに確認できる状態に保ちます
• 安全なロールバック：メインのワークスペースに影響を与えずに worktree を破棄できます

Worktree の作成手順

ターミナルで実行します。

# 1. Determine branch name based on change type
#    feat/<name>, fix/<name>, refactor/<name>, etc.
BRANCH_NAME="feat/my-feature"

# 2. Create worktree with new branch from main
git worktree add .worktrees/$BRANCH_NAME -b $BRANCH_NAME

# 3. Enter the worktree
cd .worktrees/$BRANCH_NAME

# 4. Install dependencies (use your project's package manager)
npm install  # or: bun install, yarn install, pnpm install

# 5. Verify clean baseline
npm run build && npm test

ディレクトリの規約

項目	値
Worktree のルート	.worktrees/（プロジェクト内、gitignore 対象）
パスのパターン	.worktrees/<branch-name>
例	.worktrees/feat/user-authentication

安全確認

worktree を作成する前に、.worktrees/ が .gitignore に含まれていることを確認してください。

git check-ignore -q .worktrees 2>/dev/null || echo "WARNING: .worktrees not in .gitignore!"

以降のすべての手順はワークツリー内で実行します

ワークツリーを作成した後、すべての開発コマンド（テスト、lint、ビルド、コミット、プッシュ）はワークツリーのディレクトリ内から実行します。クリーンアップまで、メインのワークスペースには触れません。

対話形式で作業する場合は、共通スキルの scripts/session-knowledge.sh begin を使って、任意でナレッジ評価を開始します（該当する場合は --task issue-<N> を使用します）。 自律型ラッパーは自動で開始します。引き継ぎの前に、新たに確認できた事実を評価するか、更新が不要な理由を記録してください。 ../autonomous-common/references/session-knowledge.md をお読みください。 Stop フックは評価状況を確認しますが、教訓の記録やファイルの更新は必須ではありません。

---

ステップ 3：テストケースを作成する（TDD）

実装コードを書く前に、次の作業を行います。

1. 設計キャンバスと要件を読む
2. すべてのユーザーシナリオ、エッジケース、エラー処理の経路を特定する
3. テストケースのドキュメント docs/test-cases/<feature>.md を作成または編集する
   • すべてのテストシナリオ（正常系、エッジケース、エラー処理）を列挙する
   • テスト ID（例：TC-AUTH-001）を割り当てる
   • 期待される結果と受け入れ基準を定義する
4. 単体テストのひな形を作成する
5. 該当する場合は E2E テストケースを作成する

---

ステップ 4：変更を実装する

• テストケースに従ってコードを書く（ワークツリー内で実施）
• 新しい機能の単体テストを新たに作成する
• 動作が変わった場合は既存のテストを更新する
• 実装がすべてのテストシナリオを網羅していることを確認する

---

ステップ 5：ローカルで検証する

最初のプッシュ前と、ブロッキング修正の後に、ローカルで実行可能なチェックを実施します。 リポジトリのテストコマンドと CI 設定を確認してください。まず対象を絞った回帰テストを実行し、次に関連する lint、型チェック、ビルド、統合チェックを実施します。 共有の動作に変更がある場合や、リポジトリのポリシーで求められる場合は、より広範なテストスイートを実行してください。ローカルで実行可能なチェックを初めて試す場にしてはならず、CI は候補を確認するものです。 ドキュメントのみの変更では、無関係なアプリケーションのビルドではなく、関連するドキュメントとワークフローのチェックを実施してください。

PR のテスト計画に、コマンド、終了ステータス、テストしたリビジョン／ツリー、カバレッジを記録します。認証情報、サービス、ツールの不足でローカルチェックを実施できない場合は、具体的な制約を記録し、そのチェックは CI で行うものとして保留にします。実行していないチェックを合格と報告してはいけません。入力と環境に変更がない場合に限り、成功した検証結果を再利用してください。修正後は影響を受けるチェックを再実行し、影響に応じて範囲を広げます。

Node プロジェクトの例（実際のプロジェクトで使われているコマンドを使用してください）：

timeout 1800 bash -lc 'npm run build && npm run test' > /tmp/verify.log 2>&1; rc=$?; [ $rc -ne 0 ] && tail -100 /tmp/verify.log; exit $rc

先に進む前に、ローカルでの失敗を修正してください。実行可能な場合は、機能チェック／E2E チェックをローカルで実施します。デプロイは、プロジェクトで必要とされ、承認されている場合に限り実施します。

時間のかかる検証の実行方法

プロジェクトのビルド／テストスイートは、十分に長いタイムアウトを設定した同期コマンド 1 つとして実行してください。バックグラウンドで実行し、複数のターンにわたってポーリングしてはいけません。

1. トップレベルのスイートコマンドを、十分に長いタイムアウトを明示して同期実行します。 1 回のブロッキング呼び出し（またはビルド後にテストを行うなど、いくつかの連続したブロッキング呼び出し）で、ターン内に全結果を取得します。出力を取得し、失敗時に限り末尾部分を表示します。

   timeout 1800 bash -lc '<your project's build & test command>' > /tmp/verify.log 2>&1; rc=$?; [ $rc -ne 0 ] && tail -100 /tmp/verify.log; exit $rc
   

2. トップレベルのスイートをバックグラウンド実行してはいけません（& やバックグラウンドタスクモードは使用しません。ホストの CLI で run_in_background などと呼ばれるものも含みます）。その後、エージェントのターンをまたいでログをポーリングすることも禁止です。ポーリングのたびにモデルとの往復処理が発生し、合計のポーリングコストがスイート自体の実行時間を桁違いに上回る可能性があります。
3. ツールの最大タイムアウトではスイートを実行できないことが明らかな場合は、ディレクトリやプレフィックスごとに分割し、同期呼び出しを数回連続して実行します。ポーリングは行いません。
4. プロジェクトが並列実行ランナーを提供している場合は、それを優先します。

対象範囲：禁止されているのは、トップレベルの検証コマンドをバックグラウンド実行することです。子プロセスやローカルサーバーを内部で起動するテスト／スクリプトは対象外です。また、イベント駆動で実際に待機する処理（ステップ 9 の CI チェック、ステップ 10～11 のボットレビュー）も対象外です。

ステップ 6：コードの簡素化

1. 最も強力なネイティブの選択肢を使って、独立した簡素化レビューを実施します。
   • Codex CLI：不要な複雑さ、重複、リポジトリの規約に焦点を当てるネイティブレビュアーのサブエージェントを Codex に起動するよう依頼します。サブエージェントの役割は助言にとどめ、変更はメインセッションで適用します。
   • Claude Code：プラグインがインストールされている場合は、code-simplifier:code-simplifier を使用します。
   • その他のクライアント：利用可能なレビュー用サブエージェントを使うか、同じレビューを手動で実施します。
2. 以下のブロッキングポリシーに従って提案をトリアージします。命名、スタイル、任意のリファクタリングは助言として扱い、現在のスコープ内で有用な場合にのみ適用します。助言事項をなくすことだけを目的として、別のレビューサイクルを開始しないでください。
3. 同じ独立したレビュアーが、簡素化とステップ 8 の正確性レビューを 1 回のレビューで行ってもかまいません。両方の結果を記録してください。同一のコードに対する 2 回目の全差分レビューは不要です。編集後は修正内容と影響を受ける契約をレビューします。
4. 完了としてマークします（フックがインストールされている場合）。

   hooks/state-manager.sh mark code-simplifier
   

---

ステップ 7：コミットと PR の作成（必須）

最初のプッシュを行う前に、ステップ 8 の独立したレビューを完了します。関連するブロッキング修正をまとめ、ローカルでの検証を完了して、検証済みの候補を 1 回だけプッシュします。変更されていないコミットについては、最終的な未コミットのツリーで実施したレビューも有効です。

コミット

ターミナルで実行します。

git add <files>
git commit -m "type(scope): description"
git push -u origin <branch-name>

PR の作成

GitHub レーン（CODE_HOST=github） — 以下の例では GitHub CLI を使用しています。GitLab レーンでは、ラッパーが chp_create_pr プロバイダーのシーム経由でマージリクエストを作成します。エージェントがプラットフォーム API 呼び出しを独自に作成する必要はありません。CLI を直接呼び出す必要がある場合は、glab mr create --title … --description … に置き換えてください。

gh pr create --title "type(scope): description" --body "$(cat <<'EOF'
## Summary
<1-3 bullet points describing the change>

## Design
- [ ] Design canvas created (`docs/designs/<feature>.pen`)
- [ ] Design approved

## Test Plan
- [ ] Test cases documented (`docs/test-cases/<feature>.md`)
- [ ] Build passes (`npm run build`)
- [ ] Unit tests pass (`npm run test`)
- [ ] CI checks pass
- [ ] Code simplification review passed
- [ ] PR review agent review passed
- [ ] Blocking bot findings resolved; advisory findings recorded
- [ ] E2E tests pass

## Checklist
- [ ] New unit tests written for new functionality
- [ ] E2E test cases updated if needed
- [ ] Documentation updated if needed
EOF
)"

PR チェックリストの更新

各ステップの完了後、PR/MR の説明を更新します。現在の本文を取得し、項目に [x] を付けてから書き戻します。

# GitHub lane (CODE_HOST=github):
gh pr view {pr_number} --json body --jq '.body' > /tmp/pr_body.md
# Edit the checklist (mark items as [x])
gh pr edit {pr_number} --body "$(cat /tmp/pr_body.md)"

# GitLab lane (CODE_HOST=gitlab):
glab mr view {mr_number} -F json | jq -r .description > /tmp/pr_body.md
# Edit the checklist (mark items as [x])
glab mr update {mr_number} --description "$(cat /tmp/pr_body.md)"

---

ステップ 8：PR レビューエージェント（必須）

ステップ 7 の最初のプッシュを行う前に、このレビューを実施します。ステップ 6 ですでに同じツリーに対する独立した正確性レビューを実施している場合は、その結果を再利用します。後続のレビューでは修正内容と影響を受ける動作を確認します。変更または新たな根拠がある場合に限り、差分全体を再レビューします。

1. 独立した開発側レビューを実施します。
   • Codex CLI：ネイティブのレビュアーサブエージェントを使うか、最初のコミット前に codex review --uncommitted を実行し、コミット済みブランチの差分に対して codex review --base <base-branch> を実行します。
   • Claude Code：プラグインがインストールされている場合は、/pr-review-toolkit:review-pr を使用します。
   • その他のクライアント：利用可能なレビューエージェントを使うか、差分全体を手動でレビューします。
2. autonomous.conf またはラッパーのデリバリーポリシーにある、プロジェクトの REVIEW_BLOCKING_SEVERITY を適用します。デフォルトの P1 では、1 回目のレビューで見つかった P0/P1 の修正が必要です。P2 と P3 は固定されたより厳しいしきい値を選択します。adaptive では、1～2 回目／3～4 回目／5 回目以降に対する従来の P3/P2/P1 のしきい値を維持します。無効な値には、警告を出して厳格な P3 を適用します。重大度のタグがない正確性に関する指摘は、先送りする前に分類します。P0/P1、必須の受け入れ基準、セキュリティ制御、必須チェックの失敗、マージゲートは常にブロッキングです。重大度は、コードの整理に関する好みではなく、実証された影響に基づいて判断します。重大度の低い指摘は、コード変更を必須とせず、助言事項として記録します。
3. 完了としてマークします（フックがインストールされている場合）。

   hooks/state-manager.sh mark pr-review
   

---

Step 9: すべての CI チェックを待つ（必須 -- 省略禁止）

ターミナルで実行します。GitHub レーンでは GitHub CLI を、GitLab レーンでは glab（または両ホストを green／pending／failed／none に正規化するパイプラインの chp_ci_status シーム）を使用します。

# GitHub lane (CODE_HOST=github):
gh pr checks {pr_number} --watch --interval 30

# GitLab lane (CODE_HOST=gitlab):
glab ci status {mr_number}   # add `--live` on newer glab for continuous updates

すべてのチェックに合格する必要があります：Lint、Unit Tests、Build、Deploy Preview、E2E Tests。

CI の実行中は、これらの作業が互いに独立している場合、既存のレビューコメントを確認し、検証の証拠を更新してください。ステータスを繰り返し読み取るのではなく、プロバイダーの監視コマンドを使用してください。レビューを再度実行させる目的だけで、内容のないコミットやプッシュを行わないでください。サポートされており適切な場合に限り、失敗したジョブを再実行させてください。

いずれかのチェックが失敗した場合：ログを分析し、修正してプッシュし、再度監視します。すべてのチェックが「pass」と表示されるまで先に進まないでください。

監視するチェック

チェック	説明	失敗時の対応
CI / build-and-test	ビルド + 単体テスト	コードを修正するか、スナップショットを更新します
Security Scan	SAST、npm audit	セキュリティ上の問題を修正します
設定済みの REVIEW_BOTS	プロジェクトごとのボットレビュアー（q、codex、claude、カスタム）	指摘に対応し、gh-as-user.sh で再実行させます
その他のレビューボット	各種チェック	指摘に対応し、各ボットのドキュメントに従って再実行させます

---

Step 10: レビューボットの指摘に対応する（REVIEW_BOTS が空でない場合は必須）

プロジェクトの autonomous.conf で REVIEW_BOTS（q codex claude のように、スペース区切りの短縮名）が宣言されている場合、Step 8 のブロック対象に関するポリシーに従って、設定された各ボットの指摘をトリアージします。ブロック対象の問題は修正してください。誤検知や助言的な指摘には、理由と重要度を添えて一度だけ返信します。保留中の助言的なスレッドは、その対応を記録した後、リポジトリのポリシーで許可されている場合に限り解決してください。保留中の指摘を修正済みとして説明しないでください。関連するコードを変更した場合、または必須のレビューが不足している場合に限り、再実行させてください。

REVIEW_BOTS="" の場合（または変数が未設定の場合）、このステップは完全にスキップされます。プロジェクトでは外部ボットによるレビューを必須としていません。

組み込みボットのトリガー：

短縮名	トリガーフレーズ	ボットのログイン名（user.login でフィルター）
q	/q review	amazon-q-developer[bot]
codex	/codex review	codex[bot]
claude	@claude review	claude[bot]

ボットレビューを再実行させるには scripts/gh-as-user.sh を使用してください。 3 つの組み込みボットはいずれも、GitHub App のボットアカウントが投稿したトリガーコメントを受け付けません。このラッパーを使うと、実際のユーザーとして投稿されます。

再実行コマンド、返信パターン、スレッドの解決に関する詳細は、references/review-threads.md を参照してください。

---

Step 11: ブロック対象の指摘がなくなるまで反復する

ブロック対象の指摘が残っている場合に限り、繰り返します：

1. 指摘が現在も存在することを確認し、重複をまとめ、関連する修正を一括して行います。
2. プッシュする前に、影響を受けるローカルテストを実行し、変更後の動作を確認します。
3. 対応可能な各スレッドに返信し、対応内容を記録した後に解決します。
4. 必要に応じて、新しい候補について影響を受ける設定済みレビュアーを一度だけ再実行させます。
5. 利用可能なステータスシグナルと回数を制限したポーリングを使って、レビュー完了を待ちます。
6. 同じしきい値で新たな指摘をトリアージします。助言的な注記は表示したままにしますが、新たな非ブロック対象の注記だけを理由にコードを編集したり、レビューを再開したりしないでください。
7. ブロック対象の指摘がなく、必須のチェックを満たした時点で先に進みます。

---

ステップ 12：E2E テストとマージ準備（必須 -- 省略禁止）

1. デプロイ済みのプレビュー環境に対して、必須の E2E テストを実行します。自律モードで、レビューラッパーが設定済みの E2E を担当する場合は、ローカルでの機能検証と必須の CI が完了した後に引き継ぎます。ラッパーが最終 E2E を 1 回実行し、ファンアウトされたレビュー担当者はその証拠を確認します。既存の E2E の証拠を再利用できるのは、HEAD、対象環境、必須のシナリオ網羅範囲が一致する場合に限ります。未実行の最終 E2E は、完了扱いにせず保留のままにします。

2. 現在の候補で E2E が実際に成功した場合に限り、完了としてマークします（フックがインストールされている場合）。ラッパーが担当する E2E が保留中の間は、この状態を設定しないでください：

   hooks/state-manager.sh mark e2e-tests
   

3. PR チェックリストを更新し、完了したチェックと、ラッパーが担当する保留中の E2E を反映します

4. ここで停止：ステータスをユーザーに報告する（対話モード）か、イシューに概要コメントを投稿します（自律モード）。自律モードでは、設定された ID（アプリモードではボット、トークンモードではホストユーザー）でコメントが投稿されるよう、プロジェクトに同梱されたラッパーを介して投稿します：

   # GitHub lane (CODE_HOST=github):
   bash scripts/gh issue comment <ISSUE_NUMBER> --body "<summary>"
   

   裸の gh issue comment は呼び出さないでください。エージェントの Bash ツールでは、ラッパーが注入する PATH 経由で gh を確実に解決できず、裸の呼び出しはシステムの gh にフォールバックして、ホストの運用者の ID で投稿されます。詳しくは references/autonomous-mode.md を参照してください。

   GitLab レーン（CODE_HOST=gitlab） — 同じ原則が適用されます。ラッパー／itp_post_comment プロバイダーのシームを介して、設定された ID でコメントが投稿されます。エージェントが glab issue note や REST API を独自に組み立てることはありません。認証と ID の処理はシームが担います。

5. マージするタイミングは、ユーザーまたはレビューエージェントが決定します

---

ステップ 13：マージ後のナレッジ処理とクリーンアップ

PR がマージまたはクローズされた後、ターミナルで次の処理を実行します。

マージ済みの PR では、ワークツリーを削除する前に、保留中のナレッジ書き戻しを完了します。レビューラッパーはこれを自動的に行います。手動でマージする場合は、scripts/distill-knowledge.sh --issue <N> --pr <merged-pr> を使用してください。単独のタスクでは、共通リファレンスに記載されているローカルの apply ビルディングブロックを使用できます。有用な変更がある場合は、別のドキュメント用コミット／PR が作成されます。新しい事実も訂正された事実もない場合、コミットは作成されません。クローズされた未マージの PR の候補は公開されません。

# Return to main workspace
cd $(git rev-parse --show-toplevel)

# Remove the worktree
git worktree remove .worktrees/<branch-name>

# Prune stale worktree references
git worktree prune

---

参考資料

詳細なコマンドと規約については、以下を参照してください。

• references/commit-conventions.md -- ブランチ名とコミットメッセージの規約
• references/review-commands.md -- gh CLI と GraphQL コマンドの完全なリファレンス
• references/review-threads.md -- レビュースレッドの管理、応答パターン、クイックリファレンスコマンド
• references/autonomous-mode.md -- 意思決定、再開時の状況認識、要件の追跡、既存の変更、ボットレビューの統合、エラーからの復旧（自律モードのみ）