Fork: 0
hasegawa / programming-template
Transfer to URL with SHA Find file
Newer
Older
programming-template / docs / 01_GUIDE / GUIDE_05_エージェント運用ルール.md
@rintoHasegawa rintoHasegawa 7 days ago 7 KB [update] Git 運用ルールを .claude/rules/git-conventions.md と /commit の reference.md へ分割移行
Raw Blame History

エージェント運用ルール (Agent Operation Rules)

実装品質を担保するために，3 つの専門エージェントを用いた開発パイプラインを定義する．

基本方針 (Basic Policy)

  • 「実装完了」とは，コーディング・テスト・リファクタリングの全フェーズが完了した状態を指す．
  • 各フェーズは専門エージェントが担当し，フレッシュなコンテキストでレビューする．
  • フェーズのスキップは原則禁止する．リファクタリング不要の判断は Refactorer エージェント自身が行う．
  • 各フェーズ間で人間が確認・判断を行う．

エージェント一覧 (Agent List)

エージェント役割フェーズ
coder機能実装・バグ修正Phase 1
tester仕様ベースのテスト作成・実行Phase 2
refactorerコード品質の改善Phase 3

実装パイプライン (Implementation Pipeline)

開始方法

/implement <タスク内容>

全体フロー

人間: /implement <タスク内容>
  │
  ├─ ブランチ作成（git-conventions ルール準拠）
  │
  ├─ Phase 1 ──▶ [Coder]
  │                実装に集中．テスト・リファクタは行わない
  │
  ├─ 人間の確認ポイント 1
  │    ブラウザ/実機で動作確認
  │    OK → 続行 / NG → フィードバックして修正
  │
  ├─ Phase 2 ──▶ [Tester]
  │                仕様ベースでテスト作成・実行
  │
  ├─ Phase 2 完了後の分岐
  │    全テスト成功 → 自動で Phase 3 へ
  │    テスト失敗 → 人間に報告し判断を仰ぐ
  │
  ├─ Phase 3 ──▶ [Refactorer]
  │                テストを安全網としてリファクタリング
  │                テスト再実行で挙動が変わっていないことを保証
  │
  ├─ Phase 4 ──▶ ドキュメント更新
  │                docs/, CLAUDE.md, docs/PROGRESS.md を必要に応じて更新
  │                更新がある場合のみ人間の確認を挟む
  │                結果を .claude/commit-context.md に書き出す
  │
  └─ 完了 → /commit でコミット

Phase 1: コーディング (Coding)

  • Coder エージェントが docs/ を読んで実装する．
  • 実装完了後，実装サマリーを出力する．
  • テストやリファクタリングは行わない．
  • コミットはしない．

人間の確認ポイント 1

  • ブラウザ・実機での動作確認（AI にはできない確認）．
  • 問題があればフィードバックし，Coder に修正を指示する．

Phase 2: テスト (Testing)

  • Tester エージェントが仕様（docs/04_SPEC/）を基準にテストを作成する．
  • テストは実装コードではなく仕様を基準に書く．
  • 実装が仕様と異なればテストが失敗し，バグを検出する．

Phase 2 完了後の分岐

  • 全テスト成功: テストサマリーを表示し，自動的に Phase 3 に進む．
  • テスト失敗あり: 人間に報告し，判断を仰ぐ．
    • 仕様の問題 → 仕様を修正
    • 実装の問題 → Coder に修正を委譲
    • テストの問題 → Tester に修正を委譲

Phase 3: リファクタリング (Refactoring)

  • Refactorer エージェントがテストを安全網としてコード品質を改善する．
  • 挙動は変更しない．
  • リファクタリング後にテストを再実行し，全テストが通ることを確認する．
  • リファクタリング不要と判断した場合は，理由を明示して終了する．

Phase 4: ドキュメント更新 (Documentation)

Phase 3 完了後，実装内容に応じて docs/, CLAUDE.md, docs/PROGRESS.md を更新する．

  • チェック観点:
    • API・データ構造の変更 → docs/04_SPEC/ の該当仕様を更新
    • 環境・依存関係の変更 → docs/02_ENV/ を更新
    • 開発ステップの進捗 → docs/03_PLAN/ や進捗記録（CLAUDE.md の進捗欄＋ docs/PROGRESS.md）を更新（書式は進捗記録ルール .claude/rules/progress-log.md に従う．git log で取れる詳細は書かない）
    • 規約・運用ルールの変更 → docs/01_GUIDE/ を更新
  • 該当なし: ドキュメント更新が不要な変更（軽微なバグ修正，リファクタリングのみ等）はスキップ可．
  • 更新がある場合のみ人間の確認を挟む．更新不要の場合は確認なしで完了処理に進む．
  • コミットコンテキストの書き出し: Phase 4 の結果（更新の有無と理由）を .claude/commit-context.md に書き出す．このファイルは /commit が参照し，docs/, CLAUDE.md, docs/PROGRESS.md の更新漏れチェックをスキップするために使う（.gitignore 対象）．

完了処理

  • /implement はコミットを行わない．完了後は /commit でコミットする．
  • /commit は .claude/commit-context.md が存在する場合，docs/, CLAUDE.md, docs/PROGRESS.md の更新漏れチェックをスキップする．存在しない場合（/implement を経由していない場合）は警告のみ行う．

コンテキスト受け渡し (Context Passing)

各エージェントは前フェーズのサマリーを入力として受け取る．加えて git diff で実際の変更差分を自ら確認する．

フェーズ受け取る情報
Coderタスク内容
TesterCoder の実装サマリー + git diff
RefactorerCoder + Tester のサマリー + git diff

人間の役割 (Human's Role)

タイミング人間がやること
開始時タスクの指示（/implement <何をするか>）
Phase 1 後動作確認（ブラウザ・実機など AI にできない確認）
Phase 2 後テスト失敗時のみ方針判断（全成功なら自動で Phase 3 へ）
Phase 4 後ドキュメント更新がある場合のみ確認 → /commit でコミット

人間の本質的な役割は「AI にできない判断と確認」であり，各フェーズの品質のゲートキーパーとなる．

コミットルール (Commit Rules)

パイプライン完了後は /commit でコミットする．コミットメッセージのタグ等は .claude/rules/git-conventions.md に従う．

※ リファクタリングとテストは実装と一体の成果物として，まとめてコミットする．必要に応じて分割コミットも可．

※ 例外（無人運転）: 以下のループは CLAUDE.md の「/commit 自発実行禁止」ルールに対するユーザー承認済みの例外として，専用ブランチに自律コミットする．いずれも push・PR・マージ・main への操作は行わず，取り込み可否は人間が判断する．

  • /auto-refactor（リファクタ／ドキュメント整理ループ）→ refactor/ 専用ブランチ
  • /auto-audit（バグ／脆弱性の巡回監査ループ．発見を裏取り後，再現テストで正しさを担保できるものだけ自動修正し，それ以外は台帳へ報告）→ fix/ 専用ブランチ

進捗記録の運用ルール（CLAUDE.md / PROGRESS.md）

進捗記録（CLAUDE.md「開発進捗」・docs/PROGRESS.md の書き方）のルールは .claude/rules/progress-log.md に定義されている．該当ファイルを編集する際に自動で読み込まれる．