From d09c2e2cb4a4ad97df37a10a64e0243b6e84a26f Mon Sep 17 00:00:00 2001 From: Jiro Date: Tue, 28 Jul 2026 08:46:22 +0900 Subject: [PATCH] =?UTF-8?q?role=20skill=20=E3=81=AE=E7=99=BA=E7=81=AB?= =?UTF-8?q?=E6=9D=A1=E4=BB=B6=E3=82=92=E6=98=8E=E7=A2=BA=E5=8C=96?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 理由: role skill の発火条件を明確にし、適切な skill 選択を安定させる。 変更: 各 role skill の description と design-skill の記述を更新し、対応する evals を追加・更新した。 検証: quick_validate、JSON、forward-test 24/24、deploy を実行済み。 --- codex/skills/internal/role-advisor/SKILL.md | 2 +- .../internal/role-advisor/evals/evals.json | 26 +++++++++++++++++++ codex/skills/internal/role-gardener/SKILL.md | 2 +- .../internal/role-gardener/evals/evals.json | 26 +++++++++++++++++++ .../skills/internal/role-implementer/SKILL.md | 2 +- .../role-implementer/evals/evals.json | 26 +++++++++++++++++++ codex/skills/internal/role-planner/SKILL.md | 2 +- .../internal/role-planner/evals/evals.json | 26 +++++++++++++++++++ codex/skills/internal/role-refactor/SKILL.md | 2 +- .../internal/role-refactor/evals/evals.json | 26 +++++++++++++++++++ codex/skills/internal/role-reviewer/SKILL.md | 2 +- .../internal/role-reviewer/evals/evals.json | 26 +++++++++++++++++++ codex/skills/internal/role-scouter/SKILL.md | 2 +- .../internal/role-scouter/evals/evals.json | 26 +++++++++++++++++++ codex/skills/internal/role-worker/SKILL.md | 2 +- .../internal/role-worker/evals/evals.json | 26 +++++++++++++++++++ docs/design-skill.md | 4 +-- 17 files changed, 218 insertions(+), 10 deletions(-) create mode 100644 codex/skills/internal/role-advisor/evals/evals.json create mode 100644 codex/skills/internal/role-gardener/evals/evals.json create mode 100644 codex/skills/internal/role-implementer/evals/evals.json create mode 100644 codex/skills/internal/role-planner/evals/evals.json create mode 100644 codex/skills/internal/role-refactor/evals/evals.json create mode 100644 codex/skills/internal/role-reviewer/evals/evals.json create mode 100644 codex/skills/internal/role-scouter/evals/evals.json create mode 100644 codex/skills/internal/role-worker/evals/evals.json diff --git a/codex/skills/internal/role-advisor/SKILL.md b/codex/skills/internal/role-advisor/SKILL.md index 646ceb5..86ca627 100644 --- a/codex/skills/internal/role-advisor/SKILL.md +++ b/codex/skills/internal/role-advisor/SKILL.md @@ -1,6 +1,6 @@ --- name: role-advisor -description: 対応するエージェントへの作業委譲入口として使う。 +description: 技術的な助言を Advisor agent へ委譲する入口として使う。実装を始める前のアーキテクチャ、設計、技術選定、トレードオフ、ベストプラクティス、リスク、方針判断について専門的な意見が必要なときに使う。コードや設定の実装、事実調査、実装済み差分のレビュー、実装計画の作成だけが目的なら使わない。 --- `advisor` のエージェントを使って、作業を進めてください。 diff --git a/codex/skills/internal/role-advisor/evals/evals.json b/codex/skills/internal/role-advisor/evals/evals.json new file mode 100644 index 0000000..7faa334 --- /dev/null +++ b/codex/skills/internal/role-advisor/evals/evals.json @@ -0,0 +1,26 @@ +{ + "skill_name": "role-advisor", + "evals": [ + { + "id": 1, + "prompt": "この認証基盤はセッション方式と JWT のどちらにすべきか、実装前にトレードオフを含めて専門家へ相談したい。", + "expected_output": "role-advisor が発火し、技術選定とトレードオフの助言を Advisor agent へ委譲すること。", + "files": [], + "should_fire": true + }, + { + "id": 2, + "prompt": "採用技術は決まっています。実装はまだせず、ゴール、タスク、依存関係、Definition of Done を計画にまとめて。", + "expected_output": "技術判断ではなく計画作成依頼なので role-advisor は発火せず、role-planner を優先すること。", + "files": [], + "should_fire": false + }, + { + "id": 3, + "prompt": "仕様と計画は確定済みです。この内容に沿って認証 API を実装して。", + "expected_output": "実装依頼なので role-advisor は発火せず、role-implementer を優先すること。", + "files": [], + "should_fire": false + } + ] +} diff --git a/codex/skills/internal/role-gardener/SKILL.md b/codex/skills/internal/role-gardener/SKILL.md index e407e48..a24e431 100644 --- a/codex/skills/internal/role-gardener/SKILL.md +++ b/codex/skills/internal/role-gardener/SKILL.md @@ -1,6 +1,6 @@ --- name: role-gardener -description: Git と GitHub の操作を専門の Gardener agent へ委譲する入口として使う。git clone、checkout、pull、push、rebase、worktree、log、および gh による repository、Pull Request、Issue の取得や PR の作成・更新など、実装・レビュー・テスト・内容の解釈を伴わない Git / GitHub 操作を依頼するときに使う。 +description: Git と GitHub の機械的な操作を Gardener agent へ委譲する入口として使う。clone、checkout、branch、pull、push、rebase、worktree、log、commit 履歴の取得、および gh による repository、Pull Request、Issue の取得・作成・更新などを依頼するときに使う。コード実装、テスト、差分や Issue の内容解釈、レビュー、PR 本文の考案が目的なら使わない。 --- `gardener` のエージェントを使って、Git / GitHub 操作を進めてください。 diff --git a/codex/skills/internal/role-gardener/evals/evals.json b/codex/skills/internal/role-gardener/evals/evals.json new file mode 100644 index 0000000..31ba441 --- /dev/null +++ b/codex/skills/internal/role-gardener/evals/evals.json @@ -0,0 +1,26 @@ +{ + "skill_name": "role-gardener", + "evals": [ + { + "id": 1, + "prompt": "Git 操作担当に、作業ブランチを最新の main へ rebase してもらって。", + "expected_output": "role-gardener が発火し、Git の rebase 操作を Gardener agent へ委譲すること。", + "files": [], + "should_fire": true + }, + { + "id": 2, + "prompt": "この PR の差分に回帰やセキュリティ上の問題がないかレビューして。", + "expected_output": "内容のレビュー依頼なので role-gardener は発火せず、role-reviewer を優先すること。", + "files": [], + "should_fire": false + }, + { + "id": 3, + "prompt": "Git 操作は不要です。指定済みのテストコマンドを実行し、終了コードだけ報告して。", + "expected_output": "一般的な機械作業なので role-gardener は発火せず、role-worker を優先すること。", + "files": [], + "should_fire": false + } + ] +} diff --git a/codex/skills/internal/role-implementer/SKILL.md b/codex/skills/internal/role-implementer/SKILL.md index 42b7f6b..29b7ed1 100644 --- a/codex/skills/internal/role-implementer/SKILL.md +++ b/codex/skills/internal/role-implementer/SKILL.md @@ -1,6 +1,6 @@ --- name: role-implementer -description: 対応するエージェントへの作業委譲入口として使う。 +description: コードや設定の実装を Implementer agent へ委譲する入口として使う。合意済みの仕様、計画、スコープ、Definition of Done に沿った機能追加、バグ修正、テスト追加など、ファイル変更と検証が必要なときに使う。実装前の調査や計画、技術判断だけの相談、実装済み差分のレビュー、挙動維持の構造改善を統括する依頼には使わない。 --- `implementer` のエージェントを使って、作業を進めてください。 diff --git a/codex/skills/internal/role-implementer/evals/evals.json b/codex/skills/internal/role-implementer/evals/evals.json new file mode 100644 index 0000000..2aa905f --- /dev/null +++ b/codex/skills/internal/role-implementer/evals/evals.json @@ -0,0 +1,26 @@ +{ + "skill_name": "role-implementer", + "evals": [ + { + "id": 1, + "prompt": "Planner がまとめたタスクと Definition of Done に沿って、この機能を実装してテストも追加して。", + "expected_output": "role-implementer が発火し、計画済みのコード実装を Implementer agent へ委譲すること。", + "files": [], + "should_fire": true + }, + { + "id": 2, + "prompt": "実装はまだ不要です。まずゴール、スコープ、タスク、完了条件を計画にまとめて。", + "expected_output": "計画作成依頼なので role-implementer は発火せず、role-planner を優先すること。", + "files": [], + "should_fire": false + }, + { + "id": 3, + "prompt": "公開 API と振る舞いを維持したまま、責務が混在したサービスの構造改善を設計し、実装とレビューまで統括して。", + "expected_output": "挙動維持の構造改善を統括する依頼なので role-implementer は発火せず、role-refactor を優先すること。", + "files": [], + "should_fire": false + } + ] +} diff --git a/codex/skills/internal/role-planner/SKILL.md b/codex/skills/internal/role-planner/SKILL.md index 3d9cdf9..4bcf145 100644 --- a/codex/skills/internal/role-planner/SKILL.md +++ b/codex/skills/internal/role-planner/SKILL.md @@ -1,6 +1,6 @@ --- name: role-planner -description: 対応するエージェントへの作業委譲入口として使う。 +description: 実装前の計画作成を Planner agent へ委譲する入口として使う。要件からゴール、スコープ、タスク、依存関係、リスク、未解決事項、Definition of Done を整理し、Implementer と Reviewer が実行・検証できる計画が必要なときに使う。コード実装、事実調査、技術選定の助言、実装済み差分のレビューだけが目的なら使わない。 --- `planner` のエージェントを使って、作業を進めてください。 diff --git a/codex/skills/internal/role-planner/evals/evals.json b/codex/skills/internal/role-planner/evals/evals.json new file mode 100644 index 0000000..84f42da --- /dev/null +++ b/codex/skills/internal/role-planner/evals/evals.json @@ -0,0 +1,26 @@ +{ + "skill_name": "role-planner", + "evals": [ + { + "id": 1, + "prompt": "この機能追加について、実装前にゴール、in/out scope、タスク、依存関係、リスク、DoD を整理して。", + "expected_output": "role-planner が発火し、実装前の計画作成を Planner agent へ委譲すること。", + "files": [], + "should_fire": true + }, + { + "id": 2, + "prompt": "この障害の原因と影響範囲をコードと設定から調べ、根拠ファイルを示して。", + "expected_output": "事実調査依頼なので role-planner は発火せず、role-scouter を優先すること。", + "files": [], + "should_fire": false + }, + { + "id": 3, + "prompt": "実装計画の前に、同期 API と非同期ジョブのどちらを採用すべきか、トレードオフを評価して推奨して。", + "expected_output": "技術判断の助言依頼なので role-planner は発火せず、role-advisor を優先すること。", + "files": [], + "should_fire": false + } + ] +} diff --git a/codex/skills/internal/role-refactor/SKILL.md b/codex/skills/internal/role-refactor/SKILL.md index 398ec5a..848db17 100644 --- a/codex/skills/internal/role-refactor/SKILL.md +++ b/codex/skills/internal/role-refactor/SKILL.md @@ -1,6 +1,6 @@ --- name: role-refactor -description: 対応するエージェントへの作業委譲入口として使う。 +description: 挙動と公開契約を維持するリファクタリングの設計と進行を Refactor agent へ委譲する入口として使う。重複、長い関数、深い条件分岐、責務混在、密結合などを改善するため、変更後の構造を設計し、実装とレビューの反復まで統括するときに使う。機能追加、仕様変更、単純な実装、レビューだけの依頼には使わない。 --- `refactor` のエージェントを使って、作業を進めてください。 diff --git a/codex/skills/internal/role-refactor/evals/evals.json b/codex/skills/internal/role-refactor/evals/evals.json new file mode 100644 index 0000000..49422b4 --- /dev/null +++ b/codex/skills/internal/role-refactor/evals/evals.json @@ -0,0 +1,26 @@ +{ + "skill_name": "role-refactor", + "evals": [ + { + "id": 1, + "prompt": "公開 API と振る舞いを変えずに、責務が混在した長いメソッドを分割し、設計から実装とレビューまで進めて。", + "expected_output": "role-refactor が発火し、挙動維持の構造改善を Refactor agent へ委譲すること。", + "files": [], + "should_fire": true + }, + { + "id": 2, + "prompt": "新しい通知チャネルの仕様、実装計画、Definition of Done は確定済みです。計画に沿って機能追加を実装して。", + "expected_output": "計画済みの機能追加なので role-refactor は発火せず、role-implementer を優先すること。", + "files": [], + "should_fire": false + }, + { + "id": 3, + "prompt": "このリファクタリング済み差分が公開 API と振る舞いを維持しているかレビューして。", + "expected_output": "実装済み差分のレビュー依頼なので role-refactor は発火せず、role-reviewer を優先すること。", + "files": [], + "should_fire": false + } + ] +} diff --git a/codex/skills/internal/role-reviewer/SKILL.md b/codex/skills/internal/role-reviewer/SKILL.md index 1793983..fb61798 100644 --- a/codex/skills/internal/role-reviewer/SKILL.md +++ b/codex/skills/internal/role-reviewer/SKILL.md @@ -1,6 +1,6 @@ --- name: role-reviewer -description: 対応するエージェントへの作業委譲入口として使う。 +description: 実装済みの差分、PR、コミット、指定ファイルのレビューを Reviewer agent へ委譲する入口として使う。仕様適合、公開契約、回帰、境界条件、セキュリティ、データ整合性、責務、検証不足を確認し、マージ前や実装後のリスクを指摘してほしいときに使う。実装前の計画、コード変更の実装、事実調査だけが目的なら使わない。 --- `reviewer` のエージェントを使って、作業を進めてください。 diff --git a/codex/skills/internal/role-reviewer/evals/evals.json b/codex/skills/internal/role-reviewer/evals/evals.json new file mode 100644 index 0000000..e762fda --- /dev/null +++ b/codex/skills/internal/role-reviewer/evals/evals.json @@ -0,0 +1,26 @@ +{ + "skill_name": "role-reviewer", + "evals": [ + { + "id": 1, + "prompt": "実装済みの PR を、仕様違反、回帰、境界条件、検証不足の観点でマージ前レビューして。", + "expected_output": "role-reviewer が発火し、実装済み変更のレビューを Reviewer agent へ委譲すること。", + "files": [], + "should_fire": true + }, + { + "id": 2, + "prompt": "この機能がどこから呼ばれているか、関連ファイルと設定を調査して。", + "expected_output": "事実調査依頼なので role-reviewer は発火せず、role-scouter を優先すること。", + "files": [], + "should_fire": false + }, + { + "id": 3, + "prompt": "レビュー対象の実装はまだありません。この機能のゴール、スコープ、タスク、完了条件を整理して。", + "expected_output": "実装前の計画作成依頼なので role-reviewer は発火せず、role-planner を優先すること。", + "files": [], + "should_fire": false + } + ] +} diff --git a/codex/skills/internal/role-scouter/SKILL.md b/codex/skills/internal/role-scouter/SKILL.md index fe252ff..fa91a23 100644 --- a/codex/skills/internal/role-scouter/SKILL.md +++ b/codex/skills/internal/role-scouter/SKILL.md @@ -1,6 +1,6 @@ --- name: role-scouter -description: 対応するエージェントへの作業委譲入口として使う。 +description: コード、設定、ドキュメント、履歴の調査を Scouter agent へ委譲する入口として使う。実装前に現状、原因、影響範囲、関連箇所、呼び出し経路、既存仕様を根拠付きで明らかにし、不確実性を下げる必要があるときに使う。コード変更、実装計画の作成、技術判断、実装済み差分のレビューだけが目的なら使わない。 --- `scouter` のエージェントを使って、作業を進めてください。 diff --git a/codex/skills/internal/role-scouter/evals/evals.json b/codex/skills/internal/role-scouter/evals/evals.json new file mode 100644 index 0000000..15609fe --- /dev/null +++ b/codex/skills/internal/role-scouter/evals/evals.json @@ -0,0 +1,26 @@ +{ + "skill_name": "role-scouter", + "evals": [ + { + "id": 1, + "prompt": "実装前に、この機能のエントリーポイント、呼び出し経路、関連設定、影響範囲を根拠付きで調査して。", + "expected_output": "role-scouter が発火し、コードベース調査を Scouter agent へ委譲すること。", + "files": [], + "should_fire": true + }, + { + "id": 2, + "prompt": "調査結果は揃っています。そこから実装タスクと Definition of Done を整理して。", + "expected_output": "計画作成依頼なので role-scouter は発火せず、role-planner を優先すること。", + "files": [], + "should_fire": false + }, + { + "id": 3, + "prompt": "調査済みの実装差分について、仕様違反、回帰、境界条件、検証不足をレビューして。", + "expected_output": "実装済み差分のリスク評価なので role-scouter は発火せず、role-reviewer を優先すること。", + "files": [], + "should_fire": false + } + ] +} diff --git a/codex/skills/internal/role-worker/SKILL.md b/codex/skills/internal/role-worker/SKILL.md index 18c8735..5841a62 100644 --- a/codex/skills/internal/role-worker/SKILL.md +++ b/codex/skills/internal/role-worker/SKILL.md @@ -1,6 +1,6 @@ --- name: role-worker -description: 対応するエージェントへの作業委譲入口として使う。 +description: 判断をほとんど要しない機械的な作業を Worker agent へ委譲する入口として使う。実行内容と対象が明確なコマンド実行、定型的なファイル操作、テスト・lint・build・検証、情報収集を任せるときに使う。設計、技術判断、コード実装、原因調査、レビュー、Git / GitHub 専門操作には使わない。 --- `worker` のエージェントを使って、作業を進めてください。 diff --git a/codex/skills/internal/role-worker/evals/evals.json b/codex/skills/internal/role-worker/evals/evals.json new file mode 100644 index 0000000..fa8f7ce --- /dev/null +++ b/codex/skills/internal/role-worker/evals/evals.json @@ -0,0 +1,26 @@ +{ + "skill_name": "role-worker", + "evals": [ + { + "id": 1, + "prompt": "判断は不要です。指定済みのテストと lint コマンドを実行し、終了コードと結果だけ報告して。", + "expected_output": "role-worker が発火し、明確な機械作業を Worker agent へ委譲すること。", + "files": [], + "should_fire": true + }, + { + "id": 2, + "prompt": "失敗ログとコードからテスト失敗の原因、影響範囲、関連箇所を根拠付きで調査して。", + "expected_output": "原因調査依頼なので role-worker は発火せず、role-scouter を優先すること。", + "files": [], + "should_fire": false + }, + { + "id": 3, + "prompt": "調査結果をもとに、同期処理と非同期処理のどちらへ設計変更すべきか推奨して。", + "expected_output": "技術判断の助言依頼なので role-worker は発火せず、role-advisor を優先すること。", + "files": [], + "should_fire": false + } + ] +} diff --git a/docs/design-skill.md b/docs/design-skill.md index 5a18338..d718d4e 100644 --- a/docs/design-skill.md +++ b/docs/design-skill.md @@ -19,8 +19,8 @@ role 系は、委譲の入口、実行主体、作業手順を分けて定義し role- → agent → role--playbook ``` -- `role-` は対応する agent を起動する入口です。agent 名を示すだけに留め、作業手順や判断基準は書きません。 +- `role-` は対応する agent を起動する入口です。frontmatter の `description` には、他の role と区別できる発火場面と対象外の場面を記載します。本文は agent 名を示すだけに留め、作業手順や実行時の判断基準は書きません。 - `codex/agents/.toml` と `claude/agents/.md` は agent のモデル、利用可能なツール、簡潔な説明を定義します。agent 本文には `role--playbook` を使って作業することだけを書きます。 - `role--playbook` は agent が実行する作業手順、判断基準、併用 skill、出力・検証の期待値を定義します。 -新しい role を追加・変更するときは、この 3 層を同時に更新し、同じ内容を複数の層へ重複して書かないでください。 +新しい role を追加・変更するときは、この 3 層の整合を同時に確認し、routing 条件は入口の `description`、モデルと利用可能なツールは agent 定義、作業手順と実行時の判断基準は playbook に置いてください。同じ内容を複数の層へ重複して書かないでください。