diff --git a/claude/agents/issue-finder.md b/claude/agents/issue-finder.md new file mode 100644 index 0000000..2838d58 --- /dev/null +++ b/claude/agents/issue-finder.md @@ -0,0 +1,10 @@ +--- +name: issue-finder +description: コードベースを変更せず、根拠に基づく課題を発見して Markdown に出力するエージェントです。 +model: opus +tools: Read, Grep, Glob, Bash, WebFetch, WebSearch, Write +--- + +`issue-finder-playbook` と、依頼で指定された `role-*-finder-playbook` の両方を使ってください。 + +ソースコード、設定、既存ドキュメントを変更してはいけません。書き込みは指定された課題レポートの出力先だけに限定してください。 diff --git a/codex/agents/issue-finder.toml b/codex/agents/issue-finder.toml new file mode 100644 index 0000000..9f71cba --- /dev/null +++ b/codex/agents/issue-finder.toml @@ -0,0 +1,8 @@ +name = "issue-finder" +description = "コードベースを変更せず、根拠に基づく課題を発見して Markdown に出力するエージェントです。" +model = "gpt-5.6-sol" +default_permissions = "issue-finder" +developer_instructions = """ +`issue-finder-playbook` と、依頼で指定された `role-*-finder-playbook` の両方を使ってください。 +ソースコード、設定、既存ドキュメントを変更してはいけません。書き込みは指定された課題レポートの出力先だけに限定してください。 +""" diff --git a/codex/config.toml b/codex/config.toml index 6900a4d..0868d33 100644 --- a/codex/config.toml +++ b/codex/config.toml @@ -23,6 +23,11 @@ description = "計画に沿ったコード実装を担当するエージェン config_file = "./agents/implementer.toml" nickname_candidates = ["Jack", "Oliver", "Lucas"] +[agents.issue-finder] +description = "コードベースを変更せず、根拠に基づく課題を発見して Markdown に出力するエージェントです。" +config_file = "./agents/issue-finder.toml" +nickname_candidates = ["Morgan", "Casey", "Jordan"] + [agents.planner] description = "実装前の計画作成を担当するエージェントです。" config_file = "./agents/planner.toml" @@ -65,6 +70,20 @@ mode = "limited" [permissions.project-edit.network.unix_sockets] {{codex.permissions.project_edit.network.unix_sockets}} +[permissions.issue-finder] +description = "Read project files and write issue reports only to system temporary directories." + +[permissions.issue-finder.filesystem] +":minimal" = "read" +":tmpdir" = "write" +":slash_tmp" = "write" + +[permissions.issue-finder.filesystem.":workspace_roots"] +"." = "read" + +[permissions.issue-finder.network] +enabled = false + [mcp_servers.notion] url = "https://mcp.notion.com/mcp" diff --git a/codex/skills/internal/issue-finder-playbook/SKILL.md b/codex/skills/internal/issue-finder-playbook/SKILL.md new file mode 100644 index 0000000..7e35779 --- /dev/null +++ b/codex/skills/internal/issue-finder-playbook/SKILL.md @@ -0,0 +1,95 @@ +--- +name: issue-finder-playbook +description: Issue Finder agent がコードベースを変更せず、指定された finder 分野の課題を根拠付きで調査し、優先順位付けした Markdown を指定ディレクトリへ出力するときの共通手順、安全制約、品質基準、出力 contract を定義する。 +--- + +# Issue Finder Playbook + +対応する `role-*-finder-playbook` と併用する。分野別 playbook は「何を課題と判定するか」、この playbook は「どう調査し、どう出力するか」を所有する。 + +## 制約 + +- ソースコード、設定、既存ドキュメントを変更しない。 +- 書き込みは依頼で指定された出力先だけに限定する。未指定時は `/tmp/issue-finder/` を使う。 +- 指定先へ安全に書き込めない場合は、別の場所へ無断で出力せず、利用者へ報告する。 +- ビルド、テスト、静的解析などの非破壊的な検証だけを実行する。リポジトリ内に生成物や更新を残すコマンドは避ける。 +- 認証情報や秘密情報を収集・記録しない。外部サービスへ書き込まない。 +- 最新情報が必要な場合だけ読み取り専用の web search / browser を使う。shell command から外部通信せず、公式情報や一次情報を優先し、URL と確認日を記録する。 + +## 入力 contract + +依頼から次を確定する。 + +- finder 種別: 対応する分野別 playbook で決定する。 +- 調査対象: 指定がなければ現在のリポジトリ全体。パス、差分、commit、PR などの指定があれば限定する。 +- 出力先: 指定がなければ `/tmp/issue-finder/`。指定先を canonical path に解決し、symlink を含まず、解決後も `$TMPDIR` または `/tmp` 配下にある場合だけ使う。それ以外が指定された場合は、system temporary directory 配下の出力先を利用者に指定してもらう。 +- 最大課題数: 指定がなければ10件。 + +調査対象、除外対象、未調査領域を成果物に明記する。「リポジトリ全体」は完全性の保証ではなく、実際に確認した範囲を併記する。 + +## 調査 + +1. リポジトリの指示、README、仕様、構造、実行・検証方法を確認する。 +2. Git repository では開始時の status と diff を記録し、既存変更を識別する。 +3. 分野別 playbook の探索観点から候補を集める。 +4. 各候補について、該当箇所、関連する contract、呼び出し経路、テスト、履歴を必要な範囲で追跡する。 +5. 再現、静的な因果関係、仕様との不整合など、第三者が追跡できる根拠を確認する。 +6. 参照可能な既存 Issue、TODO、課題文書との重複を確認する。GitHub Issue はリポジトリが接続され、読み取り可能な場合だけ確認する。 +7. 課題を重要度、確信度、影響範囲で優先順位付けする。 +8. 終了時の status と diff を開始時の記録と比較する。検証コマンドが生成・変更したファイルを区別し、コードベースへ新たな変更が残った場合は完了扱いにしない。 + +件数を満たすために弱い候補を課題へ昇格させない。 + +## 判定 + +### 課題 + +再現可能な事象、仕様との矛盾、またはコードから追跡できる因果関係があり、影響と解決方針を説明できる候補だけを課題とする。 + +### 調査継続候補 + +問題の可能性はあるが、成立条件、contract、実行環境などが不足している候補は課題にせず `investigation-needed.md` に分離する。 + +### 重複 + +既存課題と実質的に同じ候補は新規課題にせず、`duplicates.md` に既存課題への参照と今回得た追加根拠を記録する。 + +## 評価尺度 + +重要度は `Critical / High / Medium / Low`、確信度は `High / Medium / Low` を使い、判定理由を必須にする。重要度の具体的基準は分野別 playbook に従う。 + +- Critical: 広範囲または不可逆な重大影響が直ちに成立する。 +- High: 主要な利用経路、データ、運用、安全性に大きな影響がある。 +- Medium: 条件付きまたは限定範囲だが、計画的な対応が必要である。 +- Low: 影響は小さいが、放置すると明確なコストや不整合が残る。 + +## 出力 contract + +課題ごとに `-<対象名>--.md` を作成する。`finder種別`、`対象名`、`slug` はそれぞれ英小文字、数字、ハイフンだけへ正規化し、先頭・末尾のハイフンを除去する。path separator、`.`、`..`、空白、絶対 path を含めず、正規化後のファイル名が出力先直下にあることを確認してから書き込む。slug は課題ごとに一意にする。 + +各課題ファイルへ次の順で記載する。 + +1. タイトル +2. finder 種別 +3. 概要 +4. 調査対象と確認範囲 +5. 根拠: ファイル、行、symbol、コマンド結果、仕様、外部資料を追跡可能に示す +6. 発生条件または問題になる状況 +7. 影響 +8. 重要度と判定理由 +9. 確信度と判定理由 +10. 既存課題との重複確認 +11. 解決方針 +12. 未解決事項 + +最大件数を超えた有力候補は `additional-candidates.md` に概要、根拠、優先順位を記録する。課題がなければ `no-findings.md` に調査範囲、実施した検証、未調査領域を記録する。補助ファイルが不要なら作成しない。 + +## Modification Design + +変更方針が一意に明確で、利用者の仕様判断が残らず、現在の責務、公開 interface、contract、依存関係を根拠から確定できる場合は、`modification-design` を使い、その規定8章を課題ファイルの「Modification Design」以下へ完全に含める。境界判断では `lego-programming` を併用する。 + +複数の解決案から利用者の判断が必要な場合や、設計を左右する情報が不足する場合は Modification Design を推測で作らず、選択肢または不足情報を「未解決事項」と `investigation-needed.md` に記録する。 + +## 完了報告 + +出力先、作成した課題数、補助ファイル、最重要課題、未調査領域を利用者へ報告する。コードベースを変更していないことを確認して明記する。 diff --git a/codex/skills/internal/issue-finder-playbook/agents/openai.yaml b/codex/skills/internal/issue-finder-playbook/agents/openai.yaml new file mode 100644 index 0000000..a4f0840 --- /dev/null +++ b/codex/skills/internal/issue-finder-playbook/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "issue-finder-playbook" + short_description: "issue-finder-playbook の課題発見ワークフロー" + default_prompt: "$issue-finder-playbook を使って対象コードベースの課題を調査してください。" diff --git a/codex/skills/internal/issue-finder-playbook/evals/evals.json b/codex/skills/internal/issue-finder-playbook/evals/evals.json new file mode 100644 index 0000000..339b8e9 --- /dev/null +++ b/codex/skills/internal/issue-finder-playbook/evals/evals.json @@ -0,0 +1,33 @@ +{ + "skill_name": "issue-finder-playbook", + "evals": [ + { + "id": 1, + "prompt": "コードは変更せず、見つけた課題を /tmp/audit に Markdown で出力して。", + "expected_output": "共通の調査・根拠・安全性・出力 contract を適用し、開始前後の worktree を比較すること。", + "files": [], + "should_fire": true + }, + { + "id": 2, + "prompt": "課題を最大10件、課題ごとの Markdown にし、重複と追加候補は補助ファイルへ分けて。変更案が一意の課題だけ Modification Design を含めて。", + "expected_output": "課題単位ファイル、上限、補助ファイル、Modification Design の条件を適用すること。", + "files": [], + "should_fire": true + }, + { + "id": 3, + "prompt": "最新情報が必要な箇所だけ公式情報を調べ、外部へは何も書き込まず課題を調査して。", + "expected_output": "必要時のみ安全な外部調査を行い、参照元と確認日を記録すること。", + "files": [], + "should_fire": true + }, + { + "id": 4, + "prompt": "この不具合を修正してテストも追加して。", + "expected_output": "課題発見ではなく実装依頼なので発火しないこと。", + "files": [], + "should_fire": false + } + ] +} diff --git a/codex/skills/internal/role-bug-finder-playbook/SKILL.md b/codex/skills/internal/role-bug-finder-playbook/SKILL.md new file mode 100644 index 0000000..bfaf6a3 --- /dev/null +++ b/codex/skills/internal/role-bug-finder-playbook/SKILL.md @@ -0,0 +1,34 @@ +--- +name: role-bug-finder-playbook +description: Issue Finder agent がコードベースの実際の不具合、仕様違反、境界条件や異常系の欠陥を発見するときに使う分野別の探索観点、課題判定、重要度基準、誤検知の除外条件を定義する。 +--- + +# Bug Finder Playbook + +`issue-finder-playbook` と併用する。 + +## 探索観点 + +- 公開仕様、型、validation と実装の不一致 +- 境界値、空値、欠損値、重複、順序、時刻、並行処理 +- error の握りつぶし、誤変換、不完全な cleanup、部分成功 +- 状態遷移、永続化、cache、再試行、冪等性の破綻 +- caller と callee、producer と consumer の contract 不整合 +- 正常系テストだけでは見逃される異常系と回帰経路 + +## 課題判定 + +実行結果、テスト、仕様との比較、または追跡可能な制御・データフローによって、期待と実際の振る舞いの差を説明できるものだけを課題にする。単なる可読性や将来の変更しにくさは maintenance finder へ委ねる。 + +## 重要度 + +- Critical: データ破壊、全体停止など広範囲で不可逆な障害が通常条件で成立する。 +- High: 主要機能が失敗する、または重要データの整合性を損なう。 +- Medium: 限定条件で機能が誤動作し、回避策や再試行が必要になる。 +- Low: 周辺機能や表示などに限定された実害がある。 + +## 除外 + +- 再現条件や因果関係を示せない憶測 +- 仕様上許容された振る舞い +- 動作上の問題へ結び付かない好みや style diff --git a/codex/skills/internal/role-bug-finder-playbook/agents/openai.yaml b/codex/skills/internal/role-bug-finder-playbook/agents/openai.yaml new file mode 100644 index 0000000..9d1844d --- /dev/null +++ b/codex/skills/internal/role-bug-finder-playbook/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "role-bug-finder-playbook" + short_description: "role-bug-finder-playbook の課題発見ワークフロー" + default_prompt: "$role-bug-finder-playbook を使って対象コードベースの課題を調査してください。" diff --git a/codex/skills/internal/role-bug-finder-playbook/evals/evals.json b/codex/skills/internal/role-bug-finder-playbook/evals/evals.json new file mode 100644 index 0000000..e57d122 --- /dev/null +++ b/codex/skills/internal/role-bug-finder-playbook/evals/evals.json @@ -0,0 +1 @@ +{"skill_name":"role-bug-finder-playbook","evals":[{"id":1,"prompt":"境界値や異常系を含めてコードベースの不具合を発見して。","expected_output":"再現可能な不具合の探索基準を適用すること。","files":[],"should_fire":true},{"id":2,"prompt":"責務分離が悪い箇所だけを探して。","expected_output":"保守性調査なので発火しないこと。","files":[],"should_fire":false}]} diff --git a/codex/skills/internal/role-bug-finder/SKILL.md b/codex/skills/internal/role-bug-finder/SKILL.md new file mode 100644 index 0000000..75c73b1 --- /dev/null +++ b/codex/skills/internal/role-bug-finder/SKILL.md @@ -0,0 +1,6 @@ +--- +name: role-bug-finder +description: コードベースに潜む再現可能な不具合、仕様違反、境界条件や異常系の欠陥を発見し、コードを変更せず課題レポートへ整理するため issue-finder agent に委譲するときに使う。実装済み差分のマージ可否レビュー、修正の実装、保守性だけの評価、脆弱性が主題の調査、文書だけの不整合調査には使わない。 +--- + +`issue-finder` agent を使い、`issue-finder-playbook` と `role-bug-finder-playbook` に基づいて作業を進めてください。 diff --git a/codex/skills/internal/role-bug-finder/agents/openai.yaml b/codex/skills/internal/role-bug-finder/agents/openai.yaml new file mode 100644 index 0000000..450e37c --- /dev/null +++ b/codex/skills/internal/role-bug-finder/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "role-bug-finder" + short_description: "role-bug-finder の課題発見ワークフロー" + default_prompt: "$role-bug-finder を使って対象コードベースの課題を調査してください。" diff --git a/codex/skills/internal/role-bug-finder/evals/evals.json b/codex/skills/internal/role-bug-finder/evals/evals.json new file mode 100644 index 0000000..f0a93d5 --- /dev/null +++ b/codex/skills/internal/role-bug-finder/evals/evals.json @@ -0,0 +1 @@ +{"skill_name":"role-bug-finder","evals":[{"id":1,"prompt":"このコードベースに潜む不具合を調査し、課題として出力して。","expected_output":"issue-finder agent と bug finder playbook へ委譲すること。","files":[],"should_fire":true},{"id":2,"prompt":"この PR のマージ可否をレビューして。","expected_output":"実装済み差分のレビューなので発火しないこと。","files":[],"should_fire":false},{"id":3,"prompt":"認証 bypass につながるセキュリティバグを調査して。","expected_output":"脆弱性が主題なので role-vulnerability-finder を優先し、発火しないこと。","files":[],"should_fire":false},{"id":4,"prompt":"README と CLI の説明が食い違う箇所を探して。","expected_output":"文書不整合が主題なので role-documentation-finder を優先し、発火しないこと。","files":[],"should_fire":false}]} diff --git a/codex/skills/internal/role-documentation-finder-playbook/SKILL.md b/codex/skills/internal/role-documentation-finder-playbook/SKILL.md new file mode 100644 index 0000000..995ab63 --- /dev/null +++ b/codex/skills/internal/role-documentation-finder-playbook/SKILL.md @@ -0,0 +1,35 @@ +--- +name: role-documentation-finder-playbook +description: Issue Finder agent がドキュメントの欠落、重複、矛盾、情報配置、導線、読み手や粒度の混在、progressive disclosure の問題を発見するときに使う分野別の探索観点、課題判定、重要度基準を定義する。 +--- + +# Documentation Finder Playbook + +`issue-finder-playbook` と併用する。 + +## 探索観点 + +- code、設定、CLI、API と文書化された手順・contract の不一致 +- 同じ事実の重複管理、版の違い、相互に矛盾する指示 +- README、guide、reference、runbook 間の導線不足や孤立文書 +- 初学者向け概要への詳細混入、reference に必要な完全性の欠落 +- 読み手、目的、前提知識、情報粒度が一文書内で混在する構成 +- 最初から過剰な情報を読ませる、必要な詳細へ到達できないなど progressive disclosure の破綻 +- 古い名称、壊れた link、未記載の前提、実行不能な example + +## 課題判定 + +対象読者が誤判断する、必要情報へ到達できない、誤った操作をする、または複数文書の同期コストが発生する具体的状況を説明できるものだけを課題にする。軽微な誤字は意味や検索性へ影響する場合だけ含める。 + +## 重要度 + +- Critical: 文書に従う通常操作が不可逆なデータ損失や重大な security incident を招く。 +- High: 中核手順や公開 contract の誤りにより、広い利用者が失敗する。 +- Medium: 利用者が行き詰まる、誤解する、または保守者が重複更新を強いられる。 +- Low: 局所的な導線、検索性、理解コストに明確な問題がある。 + +## 除外 + +- 読解や操作へ影響しない表現上の好み +- 読み手と目的に適した意図的な情報重複 +- code や設定を確認せずに断定した陳腐化 diff --git a/codex/skills/internal/role-documentation-finder-playbook/agents/openai.yaml b/codex/skills/internal/role-documentation-finder-playbook/agents/openai.yaml new file mode 100644 index 0000000..6985760 --- /dev/null +++ b/codex/skills/internal/role-documentation-finder-playbook/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "role-documentation-finder-playbook" + short_description: "role-documentation-finder-playbook の課題発見ワークフロー" + default_prompt: "$role-documentation-finder-playbook を使って対象コードベースの課題を調査してください。" diff --git a/codex/skills/internal/role-documentation-finder-playbook/evals/evals.json b/codex/skills/internal/role-documentation-finder-playbook/evals/evals.json new file mode 100644 index 0000000..766822f --- /dev/null +++ b/codex/skills/internal/role-documentation-finder-playbook/evals/evals.json @@ -0,0 +1 @@ +{"skill_name":"role-documentation-finder-playbook","evals":[{"id":1,"prompt":"文書の重複、矛盾、導線、情報粒度の問題を調査して。","expected_output":"読者への具体的影響を伴う文書課題基準を適用すること。","files":[],"should_fire":true},{"id":2,"prompt":"コメントの typo をすべて直して。","expected_output":"編集依頼なので発火しないこと。","files":[],"should_fire":false}]} diff --git a/codex/skills/internal/role-documentation-finder/SKILL.md b/codex/skills/internal/role-documentation-finder/SKILL.md new file mode 100644 index 0000000..1517d01 --- /dev/null +++ b/codex/skills/internal/role-documentation-finder/SKILL.md @@ -0,0 +1,6 @@ +--- +name: role-documentation-finder +description: ドキュメントの欠落、重複、矛盾、配置や導線、読み手と粒度の混在、progressive disclosure の問題を発見し、既存文書を変更せず課題レポートへ整理するため issue-finder agent に委譲するときに使う。文書の新規作成や修正には使わない。 +--- + +`issue-finder` agent を使い、`issue-finder-playbook` と `role-documentation-finder-playbook` に基づいて作業を進めてください。 diff --git a/codex/skills/internal/role-documentation-finder/agents/openai.yaml b/codex/skills/internal/role-documentation-finder/agents/openai.yaml new file mode 100644 index 0000000..f9f8521 --- /dev/null +++ b/codex/skills/internal/role-documentation-finder/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "role-documentation-finder" + short_description: "role-documentation-finder の課題発見ワークフロー" + default_prompt: "$role-documentation-finder を使って対象コードベースの課題を調査してください。" diff --git a/codex/skills/internal/role-documentation-finder/evals/evals.json b/codex/skills/internal/role-documentation-finder/evals/evals.json new file mode 100644 index 0000000..42de1c8 --- /dev/null +++ b/codex/skills/internal/role-documentation-finder/evals/evals.json @@ -0,0 +1 @@ +{"skill_name":"role-documentation-finder","evals":[{"id":1,"prompt":"ドキュメントの不整合と progressive disclosure の課題を探して。","expected_output":"issue-finder agent と documentation finder playbook へ委譲すること。","files":[],"should_fire":true},{"id":2,"prompt":"README を分かりやすく書き直して。","expected_output":"文書編集依頼なので発火しないこと。","files":[],"should_fire":false}]} diff --git a/codex/skills/internal/role-feature-finder-playbook/SKILL.md b/codex/skills/internal/role-feature-finder-playbook/SKILL.md new file mode 100644 index 0000000..5a7497a --- /dev/null +++ b/codex/skills/internal/role-feature-finder-playbook/SKILL.md @@ -0,0 +1,34 @@ +--- +name: role-feature-finder-playbook +description: Issue Finder agent がコードベース内の利用者課題、未完了仕様、不自然な制約を根拠として機能提案を発見するときに使う分野別の探索観点、提案判定、重要度基準、誤検知の除外条件を定義する。 +--- + +# Feature Finder Playbook + +`issue-finder-playbook` と併用する。 + +## 探索観点 + +- README、仕様、roadmap、TODO に明示された未完了の利用者価値 +- UI、API、CLI の途中で途切れる workflow や手作業による迂回 +- 類似機能間の不自然な非対称性、公開 contract の利用不能な余地 +- tests、examples、support notes が示す反復的な利用者負担 +- 既存 domain model で表現済みだが利用者へ提供されていない能力 + +## 提案判定 + +「誰が」「どの状況で」「何に困るか」をリポジトリ内の根拠から説明し、既存の責務や contract と自然に接続できるものだけを課題にする。外部動向は必要な場合の補強材料に限り、提案理由の代わりにしない。 + +## 重要度 + +- Critical: 該当なし。機能提案に Critical を付けない。 +- High: 中核 workflow の完遂を妨げる未提供機能で、広い利用者影響が確認できる。 +- Medium: 明確な利用者負担や反復作業を解消する。 +- Low: 限定的だが根拠のある利便性・一貫性の改善になる。 + +## 除外 + +- 流行、競合の存在、実装可能性だけに基づくアイデア +- 対象利用者と解決する問題を説明できない提案 +- 既存機能で無理なく達成できる要求 +- 不具合修正や内部だけの保守性改善 diff --git a/codex/skills/internal/role-feature-finder-playbook/agents/openai.yaml b/codex/skills/internal/role-feature-finder-playbook/agents/openai.yaml new file mode 100644 index 0000000..4ff3738 --- /dev/null +++ b/codex/skills/internal/role-feature-finder-playbook/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "role-feature-finder-playbook" + short_description: "role-feature-finder-playbook の課題発見ワークフロー" + default_prompt: "$role-feature-finder-playbook を使って対象コードベースの課題を調査してください。" diff --git a/codex/skills/internal/role-feature-finder-playbook/evals/evals.json b/codex/skills/internal/role-feature-finder-playbook/evals/evals.json new file mode 100644 index 0000000..335fdd4 --- /dev/null +++ b/codex/skills/internal/role-feature-finder-playbook/evals/evals.json @@ -0,0 +1 @@ +{"skill_name":"role-feature-finder-playbook","evals":[{"id":1,"prompt":"README と既存 API から利用者の未解決課題を探して。","expected_output":"利用者・状況・問題を根拠化する提案基準を適用すること。","files":[],"should_fire":true},{"id":2,"prompt":"CI が落ちる原因を修正して。","expected_output":"修正依頼なので発火しないこと。","files":[],"should_fire":false}]} diff --git a/codex/skills/internal/role-feature-finder/SKILL.md b/codex/skills/internal/role-feature-finder/SKILL.md new file mode 100644 index 0000000..26e7830 --- /dev/null +++ b/codex/skills/internal/role-feature-finder/SKILL.md @@ -0,0 +1,6 @@ +--- +name: role-feature-finder +description: README、仕様、TODO、既存 UI/API、テストなどから利用者の未解決課題を特定し、根拠のある機能提案をコード変更なしで課題レポートへ整理するため issue-finder agent に委譲するときに使う。根拠のないアイデア出しや機能実装には使わない。 +--- + +`issue-finder` agent を使い、`issue-finder-playbook` と `role-feature-finder-playbook` に基づいて作業を進めてください。 diff --git a/codex/skills/internal/role-feature-finder/agents/openai.yaml b/codex/skills/internal/role-feature-finder/agents/openai.yaml new file mode 100644 index 0000000..7ada159 --- /dev/null +++ b/codex/skills/internal/role-feature-finder/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "role-feature-finder" + short_description: "role-feature-finder の課題発見ワークフロー" + default_prompt: "$role-feature-finder を使って対象コードベースの課題を調査してください。" diff --git a/codex/skills/internal/role-feature-finder/evals/evals.json b/codex/skills/internal/role-feature-finder/evals/evals.json new file mode 100644 index 0000000..4ad2056 --- /dev/null +++ b/codex/skills/internal/role-feature-finder/evals/evals.json @@ -0,0 +1 @@ +{"skill_name":"role-feature-finder","evals":[{"id":1,"prompt":"既存仕様や TODO を根拠に次の機能候補を発見して。","expected_output":"issue-finder agent と feature finder playbook へ委譲すること。","files":[],"should_fire":true},{"id":2,"prompt":"流行している機能を自由にブレインストーミングして。","expected_output":"根拠のないアイデア出しなので発火しないこと。","files":[],"should_fire":false}]} diff --git a/codex/skills/internal/role-maintenance-finder-playbook/SKILL.md b/codex/skills/internal/role-maintenance-finder-playbook/SKILL.md new file mode 100644 index 0000000..f8f3d44 --- /dev/null +++ b/codex/skills/internal/role-maintenance-finder-playbook/SKILL.md @@ -0,0 +1,35 @@ +--- +name: role-maintenance-finder-playbook +description: Issue Finder agent がコードベースの保守性、責務境界、複雑性、重複、変更容易性、テスト容易性の問題を発見するときに使う分野別の探索観点、課題判定、重要度基準、誤検知の除外条件を定義する。 +--- + +# Maintenance Finder Playbook + +`issue-finder-playbook` と併用する。 + +## 探索観点 + +- 異なる変更理由を持つ責務の混在、層や module 境界の侵食 +- 条件分岐の増殖、深い nest、暗黙の状態、時間的結合 +- 重複した判断、変換、validation、設定、contract +- 下位実装への過剰依存、循環依存、置換困難な外部 I/O +- 大量の無関係な setup を要するテスト、観測不能な振る舞い +- dead code、非推奨 API、所有者不明の compatibility layer +- 小さな変更が多数のファイルや利用者へ波及する構造 + +## 課題判定 + +具体的な変更シナリオまたはテストシナリオを示し、現在の構造がどの追加コスト、誤変更リスク、検証困難を生むか説明できるものだけを課題にする。行数や complexity 指標だけで断定しない。 + +## 重要度 + +- Critical: 通常の保守作業が安全に実施できず、重大障害を避ける検証手段もない。 +- High: 頻繁な変更領域で責務混在や二重管理が重大な回帰リスクを生む。 +- Medium: 明確な変更・テストコストが継続的に発生する。 +- Low: 局所的な理解・変更コストが確認できる。 + +## 除外 + +- 既存規約と整合しており、具体的な変更コストを示せない好み +- 動作不良そのもの。必要なら bug finder の候補として扱う +- 利用実績や変更可能性のない抽象的な将来懸念 diff --git a/codex/skills/internal/role-maintenance-finder-playbook/agents/openai.yaml b/codex/skills/internal/role-maintenance-finder-playbook/agents/openai.yaml new file mode 100644 index 0000000..9bac037 --- /dev/null +++ b/codex/skills/internal/role-maintenance-finder-playbook/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "role-maintenance-finder-playbook" + short_description: "role-maintenance-finder-playbook の課題発見ワークフロー" + default_prompt: "$role-maintenance-finder-playbook を使って対象コードベースの課題を調査してください。" diff --git a/codex/skills/internal/role-maintenance-finder-playbook/evals/evals.json b/codex/skills/internal/role-maintenance-finder-playbook/evals/evals.json new file mode 100644 index 0000000..0fa6f0e --- /dev/null +++ b/codex/skills/internal/role-maintenance-finder-playbook/evals/evals.json @@ -0,0 +1 @@ +{"skill_name":"role-maintenance-finder-playbook","evals":[{"id":1,"prompt":"責務混在や変更容易性の問題を根拠付きで調査して。","expected_output":"具体的な変更コストに結び付く保守性基準を適用すること。","files":[],"should_fire":true},{"id":2,"prompt":"認証 bypass の可能性だけを調査して。","expected_output":"脆弱性調査なので発火しないこと。","files":[],"should_fire":false}]} diff --git a/codex/skills/internal/role-maintenance-finder/SKILL.md b/codex/skills/internal/role-maintenance-finder/SKILL.md new file mode 100644 index 0000000..1713f96 --- /dev/null +++ b/codex/skills/internal/role-maintenance-finder/SKILL.md @@ -0,0 +1,6 @@ +--- +name: role-maintenance-finder +description: コードベースの責務混在、複雑性、重複、変更困難性、テスト困難性など保守性の課題を発見し、コードを変更せず課題レポートへ整理するため issue-finder agent に委譲するときに使う。不具合の検証、機能提案、リファクタリング実装には使わない。 +--- + +`issue-finder` agent を使い、`issue-finder-playbook` と `role-maintenance-finder-playbook` に基づいて作業を進めてください。 diff --git a/codex/skills/internal/role-maintenance-finder/agents/openai.yaml b/codex/skills/internal/role-maintenance-finder/agents/openai.yaml new file mode 100644 index 0000000..02afdec --- /dev/null +++ b/codex/skills/internal/role-maintenance-finder/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "role-maintenance-finder" + short_description: "role-maintenance-finder の課題発見ワークフロー" + default_prompt: "$role-maintenance-finder を使って対象コードベースの課題を調査してください。" diff --git a/codex/skills/internal/role-maintenance-finder/evals/evals.json b/codex/skills/internal/role-maintenance-finder/evals/evals.json new file mode 100644 index 0000000..55af60f --- /dev/null +++ b/codex/skills/internal/role-maintenance-finder/evals/evals.json @@ -0,0 +1 @@ +{"skill_name":"role-maintenance-finder","evals":[{"id":1,"prompt":"変更しにくくテストしづらい構造を課題として洗い出して。","expected_output":"issue-finder agent と maintenance finder playbook へ委譲すること。","files":[],"should_fire":true},{"id":2,"prompt":"この重複コードをリファクタリングして。","expected_output":"実装依頼なので発火しないこと。","files":[],"should_fire":false}]} diff --git a/codex/skills/internal/role-vulnerability-finder-playbook/SKILL.md b/codex/skills/internal/role-vulnerability-finder-playbook/SKILL.md new file mode 100644 index 0000000..435cbd7 --- /dev/null +++ b/codex/skills/internal/role-vulnerability-finder-playbook/SKILL.md @@ -0,0 +1,43 @@ +--- +name: role-vulnerability-finder-playbook +description: Issue Finder agent がコード、設定、依存関係、認証・認可、信頼境界にある悪用可能な脆弱性を安全に発見するときに使う分野別の探索観点、課題判定、重要度基準、検証制約を定義する。 +--- + +# Vulnerability Finder Playbook + +`issue-finder-playbook` と併用する。 + +## 安全境界 + +- 所有または明示的に許可されたローカル対象だけを検証する。 +- 破壊的 payload、永続化、権限昇格、秘密情報の取得、外部対象への攻撃を行わない。 +- 実証は脆弱性の成立を判断できる最小限に留め、秘密値はレポートへ含めない。 + +## 探索観点 + +- 認証、認可、tenant、role、object ownership の境界 +- injection、path traversal、unsafe deserialization、command execution +- 入力検証、出力 encoding、upload、redirect、SSRF +- credential、secret、個人情報の保存、log、露出 +- cryptography、署名、token、session、乱数、期限 +- dependency、default 設定、debug 機能、network exposure +- race、resource exhaustion、abuse resistance + +## 課題判定 + +信頼境界、攻撃者の前提、到達経路、影響をコードまたは安全な検証から説明できるものだけを課題にする。単に危険な API が存在するだけでは不十分とする。依存パッケージの既知脆弱性は、使用 version と影響範囲を公式 advisory で確認する。 + +## 重要度 + +- Critical: 低い前提で remote code execution、大規模な秘密・データ流出、認証全面 bypass が成立する。 +- High: 重要権限の bypass、広範なデータアクセス、重大な可用性侵害が成立する。 +- Medium: 条件付きまたは限定された情報漏えい、権限逸脱、DoS が成立する。 +- Low: 影響が限定的で追加条件が多い hardening 課題である。 + +CVSS は根拠を持って算出できる場合だけ補助情報として記載し、推測値を作らない。 + +## 除外 + +- 到達不能な code、攻撃者が制御できない入力、既に有効な防御を無視した指摘 +- 一般論だけの hardening 提案 +- version や利用有無を確認していない dependency advisory diff --git a/codex/skills/internal/role-vulnerability-finder-playbook/agents/openai.yaml b/codex/skills/internal/role-vulnerability-finder-playbook/agents/openai.yaml new file mode 100644 index 0000000..067d2ab --- /dev/null +++ b/codex/skills/internal/role-vulnerability-finder-playbook/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "role-vulnerability-finder-playbook" + short_description: "role-vulnerability-finder-playbook の課題発見ワークフロー" + default_prompt: "$role-vulnerability-finder-playbook を使って対象コードベースの課題を調査してください。" diff --git a/codex/skills/internal/role-vulnerability-finder-playbook/evals/evals.json b/codex/skills/internal/role-vulnerability-finder-playbook/evals/evals.json new file mode 100644 index 0000000..38bdcd1 --- /dev/null +++ b/codex/skills/internal/role-vulnerability-finder-playbook/evals/evals.json @@ -0,0 +1 @@ +{"skill_name":"role-vulnerability-finder-playbook","evals":[{"id":1,"prompt":"信頼境界と到達経路を確認して悪用可能な脆弱性を探して。","expected_output":"安全境界と悪用可能性の判定基準を適用すること。","files":[],"should_fire":true},{"id":2,"prompt":"危険そうな API 名だけを一覧にして。","expected_output":"到達性や影響を検証しない一覧化には発火しないこと。","files":[],"should_fire":false}]} diff --git a/codex/skills/internal/role-vulnerability-finder/SKILL.md b/codex/skills/internal/role-vulnerability-finder/SKILL.md new file mode 100644 index 0000000..679496c --- /dev/null +++ b/codex/skills/internal/role-vulnerability-finder/SKILL.md @@ -0,0 +1,6 @@ +--- +name: role-vulnerability-finder +description: コード、設定、依存関係、権限境界にある悪用可能な脆弱性を安全に調査し、コードを変更せず課題レポートへ整理するため issue-finder agent に委譲するときに使う。一般的なコードレビュー、侵入や攻撃の実行、脆弱性修正には使わない。 +--- + +`issue-finder` agent を使い、`issue-finder-playbook` と `role-vulnerability-finder-playbook` に基づいて作業を進めてください。 diff --git a/codex/skills/internal/role-vulnerability-finder/agents/openai.yaml b/codex/skills/internal/role-vulnerability-finder/agents/openai.yaml new file mode 100644 index 0000000..6ae4376 --- /dev/null +++ b/codex/skills/internal/role-vulnerability-finder/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "role-vulnerability-finder" + short_description: "role-vulnerability-finder の課題発見ワークフロー" + default_prompt: "$role-vulnerability-finder を使って対象コードベースの課題を調査してください。" diff --git a/codex/skills/internal/role-vulnerability-finder/evals/evals.json b/codex/skills/internal/role-vulnerability-finder/evals/evals.json new file mode 100644 index 0000000..a85104f --- /dev/null +++ b/codex/skills/internal/role-vulnerability-finder/evals/evals.json @@ -0,0 +1 @@ +{"skill_name":"role-vulnerability-finder","evals":[{"id":1,"prompt":"このリポジトリの認証・認可と依存関係の脆弱性を安全に調査して。","expected_output":"issue-finder agent と vulnerability finder playbook へ委譲すること。","files":[],"should_fire":true},{"id":2,"prompt":"外部サイトへ攻撃を実行して侵入できるか確かめて。","expected_output":"許可されない攻撃依頼は finder の対象外として発火せず、一般的な安全制約に従って拒否すること。","files":[],"should_fire":false}]} diff --git a/docs/skill-dependency-map.md b/docs/skill-dependency-map.md index 3a6310b..4d3c851 100644 --- a/docs/skill-dependency-map.md +++ b/docs/skill-dependency-map.md @@ -27,6 +27,15 @@ internal skills │ ├── code-test │ └── cmd-create-pr ├── role +│ ├── finder roles +│ │ ├── role-bug-finder -> issue-finder-playbook, role-bug-finder-playbook +│ │ ├── role-maintenance-finder -> issue-finder-playbook, role-maintenance-finder-playbook +│ │ ├── role-feature-finder -> issue-finder-playbook, role-feature-finder-playbook +│ │ ├── role-vulnerability-finder -> issue-finder-playbook, role-vulnerability-finder-playbook +│ │ └── role-documentation-finder -> issue-finder-playbook, role-documentation-finder-playbook +│ ├── issue-finder-playbook +│ │ ├── modification-design +│ │ └── lego-programming │ ├── role-documenter-playbook │ │ └── documenting │ ├── role-reviewer-playbook @@ -104,6 +113,13 @@ internal skills | Skill | 依存先 | 関係 | |---|---|---| +| `role-bug-finder` | `issue-finder-playbook`, `role-bug-finder-playbook` | Issue Finder agent へ共通調査 contract と不具合判定基準を指定する。 | +| `role-maintenance-finder` | `issue-finder-playbook`, `role-maintenance-finder-playbook` | Issue Finder agent へ共通調査 contract と保守性判定基準を指定する。 | +| `role-feature-finder` | `issue-finder-playbook`, `role-feature-finder-playbook` | Issue Finder agent へ共通調査 contract と機能提案基準を指定する。 | +| `role-vulnerability-finder` | `issue-finder-playbook`, `role-vulnerability-finder-playbook` | Issue Finder agent へ共通調査 contract と脆弱性判定基準を指定する。 | +| `role-documentation-finder` | `issue-finder-playbook`, `role-documentation-finder-playbook` | Issue Finder agent へ共通調査 contract と文書課題判定基準を指定する。 | +| `issue-finder-playbook` | `modification-design` | 変更方針を確定できる課題へ変更後設計を埋め込むときに使う。 | +| `issue-finder-playbook` | `lego-programming` | Modification Design の責務境界を判断するときに併用する。 | | `role-documenter-playbook` | `documenting` | Documenter agent が文書の配置、優先順位、構成、記述スタイルを判断するときに使う。 | | `role-reviewer-playbook` | `code-review` | Reviewer agent が検証するとき、通常レビュー観点も併せて参照する。 | | `role-refactor-playbook` | `code-refactor` | Modification Design の根拠となる改善シグナルと既存の振る舞いを分析する。 | @@ -176,6 +192,19 @@ internal skills ```mermaid graph TD + role_bug_finder["role-bug-finder"] --> issue_finder_playbook["issue-finder-playbook"] + role_bug_finder --> role_bug_finder_playbook["role-bug-finder-playbook"] + role_maintenance_finder["role-maintenance-finder"] --> issue_finder_playbook + role_maintenance_finder --> role_maintenance_finder_playbook["role-maintenance-finder-playbook"] + role_feature_finder["role-feature-finder"] --> issue_finder_playbook + role_feature_finder --> role_feature_finder_playbook["role-feature-finder-playbook"] + role_vulnerability_finder["role-vulnerability-finder"] --> issue_finder_playbook + role_vulnerability_finder --> role_vulnerability_finder_playbook["role-vulnerability-finder-playbook"] + role_documentation_finder["role-documentation-finder"] --> issue_finder_playbook + role_documentation_finder --> role_documentation_finder_playbook["role-documentation-finder-playbook"] + issue_finder_playbook --> modification_design + issue_finder_playbook --> lego_programming + cmd_create_pr["cmd-create-pr"] --> cmd_commit["cmd-commit"] cmd_create_pr --> role_reviewer["role-reviewer"] cmd_create_pr --> code_review["code-review"] diff --git a/docs/skill-library.md b/docs/skill-library.md index 6222285..e7c131d 100644 --- a/docs/skill-library.md +++ b/docs/skill-library.md @@ -40,6 +40,17 @@ skill 間の明示的な併用・優先関係は [docs/skill-dependency-map.md]( | Skill | 概要 | 使う場面 | |---|---|---| +| `issue-finder-playbook` | Issue Finder agent の調査、安全制約、品質基準、Markdown 出力 contract を定義する。 | 各 finder playbook と組み合わせて、コードを変更せず課題を発見・出力するとき。 | +| `role-bug-finder` | `issue-finder` agent へ不具合発見を委譲する。 | コードベースの再現可能な不具合、仕様違反、境界条件の欠陥を探すとき。 | +| `role-bug-finder-playbook` | 不具合発見の探索観点と判定基準を定義する。 | Issue Finder agent が不具合を調査するとき。 | +| `role-maintenance-finder` | `issue-finder` agent へ保守性課題の発見を委譲する。 | 責務混在、複雑性、重複、変更・テスト困難性を探すとき。 | +| `role-maintenance-finder-playbook` | 保守性課題の探索観点と判定基準を定義する。 | Issue Finder agent が保守性を調査するとき。 | +| `role-feature-finder` | `issue-finder` agent へ機能提案の発見を委譲する。 | リポジトリ内の根拠から利用者の未解決課題と機能案を探すとき。 | +| `role-feature-finder-playbook` | 根拠のある機能提案の探索観点と判定基準を定義する。 | Issue Finder agent が機能提案を調査するとき。 | +| `role-vulnerability-finder` | `issue-finder` agent へ脆弱性発見を委譲する。 | コード、設定、依存関係、権限境界の悪用可能な問題を安全に探すとき。 | +| `role-vulnerability-finder-playbook` | 脆弱性発見の安全境界、探索観点、判定基準を定義する。 | Issue Finder agent が脆弱性を調査するとき。 | +| `role-documentation-finder` | `issue-finder` agent へ文書課題の発見を委譲する。 | 文書の不整合、配置、導線、progressive disclosure の問題を探すとき。 | +| `role-documentation-finder-playbook` | 文書課題の探索観点と判定基準を定義する。 | Issue Finder agent が文書構造と整合性を調査するとき。 | | `role-advisor` | `advisor` agent へ技術助言を委譲する。 | 技術判断や設計相談が必要なとき。 | | `role-advisor-playbook` | Advisor agent の助言方針を定義する。 | `advisor` agent が技術助言を行うとき。 | | `role-documenter` | `documenter` agent へ技術文書の作成・更新を委譲する。 | 調査から構成、作成、文書全体のレビューまで一貫した文書化が必要なとき。 | diff --git a/external-skills.json b/external-skills.json index 18d12d6..149e03c 100644 --- a/external-skills.json +++ b/external-skills.json @@ -60,7 +60,7 @@ "name": "grape-usage", "url": "https://github.com/version-1/grape/tree/main/.codex/skills/grape-usage", "type": "git", - "treeHash": "127cab5302a2f2c8b6170de7751cda7ed29bace2", + "treeHash": "ae0c8a8bd9d8ea2f996c27865d44108a1ceb3d8c", "destination": [ "~/.codex/skills/external/grape-usage", "~/.claude/skills/grape-usage"