diff --git a/claude/agents/documenter.md b/claude/agents/documenter.md index 6f0d866..fa5733d 100644 --- a/claude/agents/documenter.md +++ b/claude/agents/documenter.md @@ -5,4 +5,4 @@ model: sonnet tools: Read, Grep, Glob, Bash --- -role-doc スキルを利用してください。 +`role-documenter-playbook` をもとに作業を進めてください。 diff --git a/codex/agents/documenter.toml b/codex/agents/documenter.toml index 58b04c9..135bc81 100644 --- a/codex/agents/documenter.toml +++ b/codex/agents/documenter.toml @@ -2,5 +2,5 @@ name = "documenter" description = "Documenter は、設計・構成・仕様・進捗に関する情報を整理し、読者に応じてわかりやすく伝えるドキュメント作成担当エージェントです。" model = "gpt-5.6-terra" developer_instructions = """ -`role-doc` skill を利用してください。 +`role-documenter-playbook` をもとに作業を進めてください。 """ diff --git a/codex/skills/internal/documenting/SKILL.md b/codex/skills/internal/documenting/SKILL.md index 5926fb3..5e65966 100644 --- a/codex/skills/internal/documenting/SKILL.md +++ b/codex/skills/internal/documenting/SKILL.md @@ -7,6 +7,20 @@ description: README、ADR、Runbook、API Docs、開発者向けドキュメン 目的：未来の自分（または他者）が「なぜ・何が・どう使う」を最短で理解できるようにする +## 作業手順 + +ドキュメントを作成・更新するときは、次の順序で進める。 + +1. ドキュメントする内容を調査する。 +2. 読み手、目的、調査結果をもとにドキュメントの構成を決定する。 +3. 決定した構成に沿ってドキュメントの内容を作成する。 +4. 必ずドキュメント全体を読み、次の観点でレビューする。 + - 冗長な内容がないか。 + - 重複した内容がないか。 + - 文章全体の整合性が自然か。 + - Progressive Disclosure を念頭に、ドキュメントを分割する必要がないか。 +5. レビュー結果を反映する。部分的な修正に固執せず、必要であれば構成から再検討してドキュメント全体を再構築する。 + ## どこに何を書くか（ドキュメントの地図） ### README（プロジェクト全体の入口） diff --git a/codex/skills/internal/role-documenter-playbook/SKILL.md b/codex/skills/internal/role-documenter-playbook/SKILL.md new file mode 100644 index 0000000..7749ef6 --- /dev/null +++ b/codex/skills/internal/role-documenter-playbook/SKILL.md @@ -0,0 +1,51 @@ +--- +name: role-documenter-playbook +description: Documenter として、README、ADR、Runbook、API Docs、開発者向け文書、ガイド、仕様、進捗などを作成・更新するときに使う。対象を調査し、読み手と目的に合う構成を決め、文書全体の整合性と Progressive Disclosure をレビューして反映する。 +--- + +# Documenter スキル + +## 目的 + +読者が必要な情報を最短で理解し、次の行動を迷わず選べる技術文書を作成する。 + +## 併用するスキル + +文書の配置、優先順位、構成、記述スタイルは `documenting` に従う。 + +## 作業手順 + +1. 既存のコード、設定、文書、履歴などから、ドキュメントする内容を調査する。 +2. 読み手、目的、前提知識、情報の利用場面を明確にし、文書の配置と構成を決定する。 +3. 調査結果を根拠として内容を作成・更新する。 +4. 必ず対象ドキュメント全体を読み、冗長さ、重複、文章全体の整合性、情報の過不足をレビューする。 +5. Progressive Disclosure を念頭に、入口と詳細の分割や参照関係が必要か確認する。 +6. レビュー結果を反映する。必要であれば部分修正に留めず、構成から再検討して全体を再構築する。 +7. リンク、見出し、例、コマンドなど、文書の種類に応じた検証を行う。 + +## ロール境界 + +- Documenter は情報を調査・整理し、文書として作成・更新する。 +- Scouter は実装判断や文書作成を伴わない事実調査を担当する。 +- Planner は実装前のゴール、スコープ、タスク、Definition of Done を整理する。 +- Implementer はコードや設定を変更する。 +- Reviewer は実装済み差分の品質とリスクを検証する。 + +文書化に必要な範囲を超えて、コードや設定の振る舞いを変更しない。 + +## 判断基準 + +- 推測で事実を補わず、根拠を確認する。 +- 読み手が最初に必要とする結論や手順を先に示す。 +- コードの逐語説明や、すぐ陳腐化する詳細を避ける。 +- 既存文書と責務が重なる場合は、重複させず正本を決めて参照する。 +- 既存の用語、表記、見出し構造、文体に合わせる。 +- 文書間で矛盾を見つけた場合は、黙って一方を正しいと決めず、根拠を確認する。 + +## 完了条件 + +- 調査結果が文書の内容に反映されている。 +- 読み手と目的に合う構成になっている。 +- 対象ドキュメント全体をレビューし、冗長さ、重複、不整合を解消している。 +- Progressive Disclosure の観点で文書の配置と分割を確認している。 +- 文書の種類に応じた検証が完了している。 diff --git a/codex/skills/internal/role-documenter-playbook/evals/evals.json b/codex/skills/internal/role-documenter-playbook/evals/evals.json new file mode 100644 index 0000000..128f259 --- /dev/null +++ b/codex/skills/internal/role-documenter-playbook/evals/evals.json @@ -0,0 +1,19 @@ +{ + "skill_name": "role-documenter-playbook", + "evals": [ + { + "id": 1, + "prompt": "既存コードと設定を確認し、新規参加者向けの開発環境セットアップガイドを作成して。", + "expected_output": "role-documenter-playbook が発火し、調査、読者と目的に応じた構成、文書作成、文書全体のレビュー、Progressive Disclosure の確認、レビュー反映、検証まで行うこと。", + "files": [], + "should_fire": true + }, + { + "id": 2, + "prompt": "既存の Runbook を更新して。重複した障害対応手順を整理し、必要なら文書構成も組み直して。", + "expected_output": "文書全体を確認し、冗長さ、重複、整合性、分割の必要性をレビューしたうえで、必要に応じて全体を再構築すること。", + "files": [], + "should_fire": true + } + ] +} diff --git a/codex/skills/internal/role-documenter/SKILL.md b/codex/skills/internal/role-documenter/SKILL.md new file mode 100644 index 0000000..e9a90bc --- /dev/null +++ b/codex/skills/internal/role-documenter/SKILL.md @@ -0,0 +1,6 @@ +--- +name: role-documenter +description: 技術文書の作成・更新を Documenter agent に委譲するときに使う。README、ADR、Runbook、API Docs、開発者向け文書、ガイド、仕様、進捗などを調査し、構成を決め、読み手に伝わる文書として作成・レビューする必要があるときに使う。コード実装、事実調査だけの依頼、実装計画、技術判断、実装済み差分のレビューだけが目的なら使わない。 +--- + +`documenter` のエージェントを使って、作業を進めてください。 diff --git a/codex/skills/internal/role-documenter/evals/evals.json b/codex/skills/internal/role-documenter/evals/evals.json new file mode 100644 index 0000000..e7603ac --- /dev/null +++ b/codex/skills/internal/role-documenter/evals/evals.json @@ -0,0 +1,26 @@ +{ + "skill_name": "role-documenter", + "evals": [ + { + "id": 1, + "prompt": "このプロジェクトのセットアップ手順を調査して、開発者向け README を作成して。", + "expected_output": "role-documenter が発火し、調査、構成決定、作成、全体レビューを含む文書化を Documenter agent へ委譲すること。", + "files": [], + "should_fire": true + }, + { + "id": 2, + "prompt": "認証処理の呼び出し経路だけを調査して、根拠付きで報告して。", + "expected_output": "文書作成ではなく事実調査だけの依頼なので role-documenter は発火せず、role-scouter を優先すること。", + "files": [], + "should_fire": false + }, + { + "id": 3, + "prompt": "仕様と計画に沿って認証 API を実装して。", + "expected_output": "文書作成ではなく実装依頼なので role-documenter は発火せず、role-implementer を優先すること。", + "files": [], + "should_fire": false + } + ] +} diff --git a/docs/skill-dependency-map.md b/docs/skill-dependency-map.md index bf4a916..152a686 100644 --- a/docs/skill-dependency-map.md +++ b/docs/skill-dependency-map.md @@ -27,6 +27,8 @@ internal skills │ ├── code-test │ └── cmd-create-pr ├── role +│ ├── role-documenter-playbook +│ │ └── documenting │ ├── role-reviewer-playbook │ │ └── code-review │ ├── role-refactor-playbook @@ -102,6 +104,7 @@ internal skills | Skill | 依存先 | 関係 | |---|---|---| +| `role-documenter-playbook` | `documenting` | Documenter agent が文書の配置、優先順位、構成、記述スタイルを判断するときに使う。 | | `role-reviewer-playbook` | `code-review` | Reviewer agent が検証するとき、通常レビュー観点も併せて参照する。 | | `role-refactor-playbook` | `code-refactor` | Modification Design の根拠となる改善シグナルと既存の振る舞いを分析する。 | | `role-refactor-playbook` | `modification-design` | Refactor agent が変更後の責務、境界、依存方向を設計するときに併用する。 | @@ -188,6 +191,7 @@ graph TD ci_fix --> code_test["code-test"] ci_fix --> cmd_create_pr + role_documenter_playbook["role-documenter-playbook"] --> documenting 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"] diff --git a/docs/skill-library.md b/docs/skill-library.md index 2723a9b..e51f62c 100644 --- a/docs/skill-library.md +++ b/docs/skill-library.md @@ -42,6 +42,8 @@ skill 間の明示的な併用・優先関係は [docs/skill-dependency-map.md]( |---|---|---| | `role-advisor` | `advisor` agent へ技術助言を委譲する。 | 技術判断や設計相談が必要なとき。 | | `role-advisor-playbook` | Advisor agent の助言方針を定義する。 | `advisor` agent が技術助言を行うとき。 | +| `role-documenter` | `documenter` agent へ技術文書の作成・更新を委譲する。 | 調査から構成、作成、文書全体のレビューまで一貫した文書化が必要なとき。 | +| `role-documenter-playbook` | Documenter agent の文書化手順と判断基準を定義する。 | `documenter` agent が技術文書を作成・更新するとき。 | | `role-gardener` | `gardener` agent へ Git / GitHub 操作を委譲する。 | 内容の解釈を伴わない repository、branch、worktree、PR、Issue の操作が必要なとき。 | | `role-gardener-playbook` | Gardener agent の Git / GitHub 操作方針と責務境界を定義する。 | `gardener` agent が Git / GitHub の機械操作を行うとき。 | | `role-implementer` | `implementer` agent へ実装を委譲する。 | 計画に沿ったコード実装が必要なとき。 |