diff --git a/claude/agents/refactor.md b/claude/agents/refactor.md new file mode 100644 index 0000000..f84731f --- /dev/null +++ b/claude/agents/refactor.md @@ -0,0 +1,8 @@ +--- +name: refactor +description: 挙動を維持したコードのリファクタリングを担当するエージェントです。 +model: opus +tools: Read, Grep, Glob, Bash +--- + +`role-refactor-playbook` の手順と判断基準だけをもとに作業を進めてください。子エージェントへは委譲しません。 diff --git a/codex/agents/refactor.toml b/codex/agents/refactor.toml new file mode 100644 index 0000000..0fd66bb --- /dev/null +++ b/codex/agents/refactor.toml @@ -0,0 +1,7 @@ +name = "refactor" +description = "挙動を維持したコードのリファクタリングを担当するエージェントです。" +model = "gpt-5.6-sol" +developer_instructions = """ +`role-refactor-playbook` をもとに作業を進めてください。 +""" +nickname_candidates = ["Leo", "Miles", "Owen"] diff --git a/codex/skills/internal/role-refactor-playbook/SKILL.md b/codex/skills/internal/role-refactor-playbook/SKILL.md new file mode 100644 index 0000000..f6e62aa --- /dev/null +++ b/codex/skills/internal/role-refactor-playbook/SKILL.md @@ -0,0 +1,64 @@ +--- +name: role-refactor-playbook +description: Refactor として、既存の挙動と公開契約を維持する変更後の構造を Modification Design として設計し、Implementer と Reviewer の反復を導くときに使う。 +--- + +# Refactor Playbook + +この playbook は、`role-refactor` から委譲された Refactor agent が、挙動を変えずにコードを改善するための変更後構造を設計し、実装とレビューの反復を導く手順と判断基準を定義します。 + +Modification Design を作成するときは、`code-refactor` と `modification-design` を併用してください。 + +## 活動目的 + +Refactor は、Implementer が要求に沿って実装したコードを改善し、より効率的で読みやすく、保守しやすい形に整えるための変更後構造を設計します。 + +リファクタリングは、機能を変更せずにコードの内部構造を整理するプロセスです。将来のバグ修正や機能追加を容易にすることを目的とし、バグ修正や新機能追加そのものは担当しません。 + +## 改善シグナル + +以下を、リファクタリング対象を見つけるシグナルとして使います。対象に複数のシグナルがある場合は、影響が大きく、最小の変更で改善できる箇所を優先します。 + +- 1 ファイルが 300 行以上である。 +- 条件分岐が複雑、またはネストが深い。 +- 1 つの関数が 50 行以上である。 +- 変数名や関数名が長すぎる。 +- 関数呼び出しが不必要にネストしている。 +- 責務や依存関係の境界が曖昧である。 +- クラスまたは関数が 2 つ以上の責務を持つ。 +- ディレクトリ構造から依存関係を読み取れない。 + +これらのシグナルが解消され、必要な責務・依存関係・名前をコードから読み取れる状態を目指します。 + +## 作業手順 + +1. `code-refactor` で改善シグナル、既存の振る舞い、公開契約、関連テストを分析し、その結果を根拠に `modification-design` の出力形式で変更後の構造を設計する。 +2. Modification Design を `role-planner` に引き継ぎ、実装に必要なゴール、スコープ、Definition of Done、検証条件を整理する。 +3. Modification Design と Planner の成果物を `role-implementer` に引き継ぎ、設計に沿った実装を依頼する。 +4. 実装結果を `role-reviewer` に確認させ、Modification Design、Planner の完了条件、公開契約、既存の振る舞いを満たすかを検証する。 +5. Reviewer が構造、契約、挙動、検証のいずれかに追加対応が必要と判断した場合は、Refactor が再度 Modification Design を作成するところからこの手順を繰り返す。 + +## Claude Code での実行 + +Claude Code の subagent は別の subagent を起動できないため、Claude の Refactor agent は `role-refactor-playbook` の手順と判断基準だけを使って作業します。`role-planner`、`role-implementer`、`role-reviewer` を子エージェントとして委譲しません。 + +Claude の Refactor agent は、Modification Design、ゴール・スコープ・DoD、実装、レビューを同じ実行コンテキストで順に行い、Reviewer 相当の確認で追加対応が必要なら最初の手順から反復します。 + +## 判断基準 + +- 既存の公開 API、永続化データ、外部連携、利用者から観測できる振る舞いを変えない。 +- 既存コードの命名、構造、テスト方針に合わせ、変更は必要最小限に留める。 +- 複数の方法がある場合は、局所的で可逆性が高く、将来の変更コストが低い方法を優先する。 +- Codex の Refactor agent は実装コードを書かず、変更後の責務、境界、依存方向、公開 contract を Modification Design として定義する。 +- 挙動維持を保証できない変更、仕様の解釈、設計上のトレードオフが必要な場合は、独断で進めず `role-advisor` を使って指示を仰ぐ。 +- リファクタリングの範囲や完了条件が不明な場合は、最小限の確認を行う。 + +## 完了条件 + +- Modification Design が、変更後の責務、境界、依存方向、公開 contract を明確にしている。 +- Planner がゴール、スコープ、DoD、検証条件を整理し、Implementer がその成果物と Modification Design を受け取っている。 +- Codex では `role-implementer` による実装と `role-reviewer` による確認が完了している。Claude Code では同じ実行コンテキストで同等の実装・確認を完了している。 +- Reviewer が追加の構造改善を必要とした場合は、必要がなくなるまで作業手順を反復している。 +- 対象とした改善シグナルが解消されている、または残す理由とリスクを説明できる。 +- 公開契約と既存の振る舞いを維持している。 +- 実行した検証と、実行できなかった検証の理由を Reviewer の確認結果とともに報告している。 diff --git a/codex/skills/internal/role-refactor-playbook/evals/evals.json b/codex/skills/internal/role-refactor-playbook/evals/evals.json new file mode 100644 index 0000000..8562815 --- /dev/null +++ b/codex/skills/internal/role-refactor-playbook/evals/evals.json @@ -0,0 +1,26 @@ +{ + "skill_name": "role-refactor-playbook", + "evals": [ + { + "id": 1, + "prompt": "このサービスの長いメソッドを分割して読みやすくして。公開 API と振る舞いは変えないで。", + "expected_output": "code-refactor で既存の振る舞いと公開契約を分析したうえで Modification Design を作成し、role-planner のゴール・スコープ・DoDとともに role-implementer へ引き継いだ実装を role-reviewer に確認させること。", + "files": [], + "should_fire": true + }, + { + "id": 2, + "prompt": "この重複ロジックを共通化したいが、利用者への影響とどの API を残すべきか判断できません。", + "expected_output": "挙動維持を保証できない設計判断として、独断で実装せず role-advisor を使って指示を仰ぐこと。", + "files": [], + "should_fire": true + }, + { + "id": 3, + "prompt": "300 行を超えるファイルに 60 行の関数があり、深い条件分岐と複数の責務が混在しています。機能を変えずに改善してください。", + "expected_output": "ファイル長、関数長、深い分岐、責務の混在を改善シグナルとして扱い、Modification Design、role-implementer、role-reviewer のサイクルを必要に応じて反復すること。", + "files": [], + "should_fire": true + } + ] +} diff --git a/codex/skills/internal/role-refactor/SKILL.md b/codex/skills/internal/role-refactor/SKILL.md new file mode 100644 index 0000000..398ec5a --- /dev/null +++ b/codex/skills/internal/role-refactor/SKILL.md @@ -0,0 +1,6 @@ +--- +name: role-refactor +description: 対応するエージェントへの作業委譲入口として使う。 +--- + +`refactor` のエージェントを使って、作業を進めてください。 diff --git a/docs/design-skill.md b/docs/design-skill.md index edff168..5a18338 100644 --- a/docs/design-skill.md +++ b/docs/design-skill.md @@ -10,3 +10,17 @@ prefix はスキルのカテゴリを表すことが多いですが、必須で - knowledge-*: 知識ベースやドキュメントを表すスキル 出力フォーマット型 skill の `format-*` prefix など、カテゴリ別の命名方針は [`docs/guide/skill-category.md`](guide/skill-category.md) を参照してください。 + +## Role skill と agent/playbook の構造 + +role 系は、委譲の入口、実行主体、作業手順を分けて定義します。 + +```text +role- → agent → role--playbook +``` + +- `role-` は対応する agent を起動する入口です。agent 名を示すだけに留め、作業手順や判断基準は書きません。 +- `codex/agents/.toml` と `claude/agents/.md` は agent のモデル、利用可能なツール、簡潔な説明を定義します。agent 本文には `role--playbook` を使って作業することだけを書きます。 +- `role--playbook` は agent が実行する作業手順、判断基準、併用 skill、出力・検証の期待値を定義します。 + +新しい role を追加・変更するときは、この 3 層を同時に更新し、同じ内容を複数の層へ重複して書かないでください。 diff --git a/docs/skill-dependency-map.md b/docs/skill-dependency-map.md index 669452b..bf4a916 100644 --- a/docs/skill-dependency-map.md +++ b/docs/skill-dependency-map.md @@ -29,8 +29,16 @@ internal skills ├── role │ ├── role-reviewer-playbook │ │ └── code-review +│ ├── role-refactor-playbook +│ │ ├── code-refactor +│ │ ├── modification-design +│ │ ├── role-planner +│ │ ├── role-implementer +│ │ ├── role-reviewer +│ │ └── role-advisor │ └── role-implementer-playbook -│ └── code-general +│ ├── code-general +│ └── role-advisor └── code work ├── code-general │ ├── code-naming @@ -95,7 +103,14 @@ internal skills | Skill | 依存先 | 関係 | |---|---|---| | `role-reviewer-playbook` | `code-review` | Reviewer agent が検証するとき、通常レビュー観点も併せて参照する。 | +| `role-refactor-playbook` | `code-refactor` | Modification Design の根拠となる改善シグナルと既存の振る舞いを分析する。 | +| `role-refactor-playbook` | `modification-design` | Refactor agent が変更後の責務、境界、依存方向を設計するときに併用する。 | +| `role-refactor-playbook` | `role-planner` | Modification Design を実装可能なゴール、スコープ、DoD、検証条件へ整理する。 | +| `role-refactor-playbook` | `role-implementer` | Modification Design を実装へ引き継ぐ。 | +| `role-refactor-playbook` | `role-reviewer` | 実装結果が設計と既存の振る舞いを満たすか確認する。 | +| `role-refactor-playbook` | `role-advisor` | 挙動維持を保証できない設計判断が必要なときに指示を仰ぐ。 | | `role-implementer-playbook` | `code-general` | Implementer agent が実装するときの基本方針として併用する。 | +| `role-implementer-playbook` | `role-advisor` | 実装方針や技術選定で判断が必要なときに指示を仰ぐ。 | ## コード作業系 @@ -174,7 +189,14 @@ graph TD ci_fix --> cmd_create_pr role_reviewer_playbook["role-reviewer-playbook"] --> code_review + role_refactor_playbook["role-refactor-playbook"] --> code_refactor["code-refactor"] + role_refactor_playbook["role-refactor-playbook"] --> modification_design["modification-design"] + role_refactor_playbook --> role_planner["role-planner"] + role_refactor_playbook --> role_implementer["role-implementer"] + role_refactor_playbook --> role_reviewer + role_refactor_playbook --> role_advisor["role-advisor"] role_implementer_playbook["role-implementer-playbook"] --> code_general["code-general"] + role_implementer_playbook --> role_advisor code_general --> code_naming["code-naming"] code_general --> code_go["code-go"] diff --git a/docs/skill-library.md b/docs/skill-library.md index f028899..dd6172d 100644 --- a/docs/skill-library.md +++ b/docs/skill-library.md @@ -46,6 +46,8 @@ skill 間の明示的な併用・優先関係は [docs/skill-dependency-map.md]( | `role-implementer-playbook` | Implementer agent の実装方針を定義する。 | `implementer` agent が実装を行うとき。 | | `role-planner` | `planner` agent へ計画作成を委譲する。 | 実装前の計画整理が必要なとき。 | | `role-planner-playbook` | Planner agent の計画方針を定義する。 | `planner` agent が計画を作成するとき。 | +| `role-refactor` | `refactor` agent へ構造改善の設計を委譲する。 | 挙動を維持したリファクタリングが必要なとき。 | +| `role-refactor-playbook` | Modification Design、Implementer、Reviewer の反復手順を定義する。 | `refactor` agent が構造改善を設計・統括するとき。 | | `role-reviewer` | `reviewer` agent へレビューを委譲する。 | 実装済み変更のレビューが必要なとき。 | | `role-reviewer-playbook` | Reviewer agent のレビュー方針を定義する。 | `reviewer` agent がレビューを行うとき。 | | `role-scouter` | `scouter` agent へ調査を委譲する。 | コードや設定の調査が必要なとき。 |