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

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

## 基本方針 (Basic Policy)

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

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

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

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

### 開始方法

```bash
/implement <タスク内容>
```

### 全体フロー

```
人間: /implement <タスク内容>
  │
  ├─ ブランチ作成（GUIDE_04 準拠）
  │
  ├─ 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.md / PROGRESS.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 | タスク内容 |
| Tester | Coder の実装サマリー + git diff |
| Refactorer | Coder + Tester のサマリー + git diff |

## 人間の役割 (Human's Role)

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

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

## コミットルール (Commit Rules)

パイプライン完了後は `/commit` でコミットする．コミットメッセージのタグ等は [GUIDE_04](GUIDE_04_Git運用ルール.md) に従う．

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

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

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

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

進捗記録は **2 ファイルの二段構成**で管理する．Phase 4 や `/setup` 中断時にこれらを更新する．

| ファイル | 役割 | 更新方法 |
| --- | --- | --- |
| `CLAUDE.md` の「開発進捗」セクション | **最新ステップ 1 行のみ**（毎ターン読み込まれる薄い目印） | 上書き |
| `docs/PROGRESS.md` | **追記型のフル進捗ログ**（動機・設計判断・失敗パターン含む） | 末尾に追記 |

**背景**: CLAUDE.md は毎ターン読み込まれるため，追記型運用にするとコンテキスト圧迫の原因になる．一方で進捗の経緯・失敗パターン・設計判断はタスクを跨いで価値があるため捨てたくない．そこで「常に読まれる薄いポインタ（CLAUDE.md）」と「必要な時だけ読む厚いログ（PROGRESS.md）」に分離する．関数名・引数・テスト件数等の実装詳細は `git log` とコミットメッセージに完全な形で残るため，どちらにも書かない．

### CLAUDE.md「開発進捗」の書き方

- **最新 1 行のみ**．古い行は上書きで消す（履歴は PROGRESS.md に残るので消えてよい）
- 基本形式: `最新: <ステップ見出し>`
- 関数名・テスト件数・実装手順詳細は書かない（PROGRESS.md と `git log` に任せる）

### docs/PROGRESS.md の書き方

`docs/PROGRESS.md` は追記型．最新エントリを**末尾に追記**する（時系列順．古いものが上，新しいものが下）．

**書く（PROGRESS.md に残す価値が高いもの）**:

以下は PROGRESS.md に置く価値があるが，全て書く必要はない．シンプルなステップなら状況の 1 行だけで十分．書くことが少ない時に無理に伸ばさない．

- 状況: 何が完了したか（1 行）
- 動機・原因: なぜそれをやったか（既存の問題点・要件変更・前バージョンの欠点など）
- 重要な設計判断: 他案との比較が必要な場合のみ．「A 案ではなく B 案を選んだ理由」が将来の判断材料になるとき
- 失敗パターンの圧縮サマリ: 「① X 案 → Y で破綻 / ② Z 案で解決」のような 1〜2 行．同じ轍を踏まないための知識として残す．試行錯誤を時系列で全部書かず，本質的に異なるアプローチの失敗だけを並列項目として記録する
- 未実装・後段: 「次に何をすべきか」を思い出すための短いメモ

**書かない（コミットメッセージと `git log` に任せる）**:

以下は `git log <commit-hash>` または `git show <commit-hash>` で完全な情報が取れる．PROGRESS.md に書くと重複・陳腐化する．

- 関数名・引数・型シグネチャ
- テスト件数の内訳（合計件数のみなら可だが数字は陳腐化するので省略推奨）
- リファクタリングの手順詳細
- 撤去・新規追加の関数リスト
- 具体的な定数値・閾値（設計判断の核心に関わるものを除く）
- 数値範囲の細部（実装パラメータ等）
- 後方互換性の細かい仕様
- 「全テスト N passed」の報告（pass している前提のため不要）

**長さと書式**:

- 1 エントリの長さは内容次第で可変．書くことが少なければ **1 行で十分**．複数系統の作業を 1 ステップにまとめた等で必要なら長くなってもよい．無理に伸ばさず無理に削らず，「未来の自分（または他人）が辿れるか」だけを基準にする
- 基本形式: `- [x] **<簡潔な見出し>**: <1〜2 文の要約>`．必要に応じて下に動機・設計判断・失敗パターンを 1〜2 行ずつ追加
- 太字は**見出しに使う**（目次の項目として目立たせる）．本文中で多用しない
- 長い箇条書きを避ける．箇条書きは「失敗パターン ① ② ③」のような本質的に異なる選択肢の並列項目に限定する

**既存エントリの長文化に気付いたとき**:

過去のエントリで「詳細をベタ書きしていて目次として機能しなくなっている」ものを見つけたら，ユーザーに圧縮を提案する．自動で削らない（背景情報の価値判断はユーザーが行う）．提案時は「この情報は `git log` にあるので削れる / これは失敗パターンなので残すべき」のように切り分けて示すこと．