From f11969f54dc1bfa81578e02c7c955fe034db3fcd Mon Sep 17 00:00:00 2001 From: fumtas1k Date: Mon, 27 Jul 2026 20:43:13 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20Opus=205=20=E3=81=AE=E6=8C=99=E5=8B=95?= =?UTF-8?q?=E3=82=92=E8=B8=8F=E3=81=BE=E3=81=88=E5=87=BA=E5=8A=9B=E9=87=8F?= =?UTF-8?q?=E3=81=AE=E8=A6=8F=E5=BE=8B=E3=81=A8=E5=A7=94=E8=AD=B2=E5=88=A4?= =?UTF-8?q?=E6=96=AD=E3=82=92=E8=A6=8F=E7=B4=84=E5=8C=96?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 公式ガイド Prompting Claude Opus 5 との突き合わせで判明した 2 点の 規約欠落を `.agents/rules/common.md` に追加する。 - 1.1 出力量の規律（新設）: 現行世代モデルは会話応答も生成ドキュメント も既定で長い。長さは effort / thinking では制御できないため、PR 本文 / plan・spec / agent-lessons / 会話応答それぞれの長さ基準を明示した。 長い Markdown が format:check 失敗の確率を上げる点も併記。 - 6.9 に「委譲するかどうかの判断」小節を追加: 従来の 6.9 は委譲後の品質 ルールのみで、いつ委譲しないかが未定義だった。親が数ツールコールで 完結できる作業・検証目的の subagent・1 体で足りる作業への並列投入を 非委譲条件として明文化し、reviewer subagent の適用範囲を複数ファイル 機能追加とセキュリティ変更に限定した（solo dev 体制のため全廃はしない）。 仕様を初回プロンプトで完結させる指針も追加。 Co-Authored-By: Claude Opus 5 (1M context) --- .agents/rules/common.md | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/.agents/rules/common.md b/.agents/rules/common.md index 46a3fd62..211f2165 100644 --- a/.agents/rules/common.md +++ b/.agents/rules/common.md @@ -15,6 +15,19 @@ - **コード内コメント**: 日本語を基本とする。 +### 1.1 出力量の規律 + +現行世代のモデル（Claude Opus 5 等）は既定で会話応答も生成ドキュメントも長くなる。**長さは effort / thinking 設定では制御できない**（それらは思考量を変えるだけで可視出力の長さを縮めない）ため、規約で明示する。 + +- **PR 本文**: 変更点・検証結果・スコープ外を簡潔に。同じ内容を「概要」と「詳細」で二度書かない。定型見出しを埋めるための水増し節を作らない +- **plan / spec（`docs/superpowers/plans/` `specs/`）**: 判断と実装に必要な情報のみ。読み手が次に取る行動を変えない記述は落とす +- **`docs/agent-lessons.md`**: 1 エントリは「現象 / 根本原因 / 対処 / 関連」に収める。試行錯誤の全経過ではなく、次回繰り返さないために必要な事実だけを残す（効かなかった対策は「効かない対策」として列挙するに留める） +- **会話応答**: 結論を最初の 1 文に置き、根拠は後に置く。短さより読みやすさを優先し、削るなら情報の選別で削る（矢印連結・省略語・断片文への圧縮では削らない） + +**長い Markdown は `npm run format:check` の失敗確率も上げる**（3 章参照）。水増しを避けることは CI 赤の予防でもある。 + +出典 → [Prompting Claude Opus 5](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-opus-5) + --- ## 2. コマンドリファレンス @@ -167,6 +180,20 @@ VRT が小さい pixel diff (例: 0.07%) を検出しても「微小だから ba ### 6.9 サブエージェント運用の補足 +#### 委譲するかどうかの判断（委譲前） + +現行世代のモデルは subagent 委譲に積極的で、小さい作業でも委譲しがちである。委譲には「context の再構築 → 作業 → 報告 → 親が報告を再読」の往復コストが必ず乗るため、**次のケースでは委譲しない**: + +- 親が数回の tool 呼び出しで完結できる作業（数ファイルの read、単純な検索、単一ファイルの軽微な修正） +- **検証・ダブルチェック目的の subagent**。検証は親のループ内で行う（3 章の必須チェックを親が実行する） +- 1 体で足りる作業に複数体を並列投入すること。並列は「独立していて、かつそれぞれ相応の規模がある」トラックに限る + +**reviewer subagent（`requesting-code-review` skill）の適用範囲**: 本リポジトリでは **複数ファイルにまたがる機能追加 / セキュリティ関連の変更** に限定する。単一ファイルの修正・docs のみの変更・リファクタの小変更では使わない（skill 側の記述は「major feature 後 / merge 前は mandatory」だが、本リポジトリの適用方針はこちらが優先）。solo dev 体制（6.7 節）で人間レビューが存在しないため全廃はしないが、既定で回すものでもない。 + +**仕様は最初のプロンプトで完結させる**: 追加指示を小出しに送るより、初回プロンプトに目的・制約・完了条件・スコープ外を全部書いたほうが精度と token 効率がともに良い（下記「矛盾する設計指示を混ぜない」と同根の問題）。 + +#### 委譲後の運用 + - **完了報告は項目別ステータス必須**: 親プロンプトのスコープ箇条書きを subagent が一部のみで「完了」と返すケースがあるため、完了報告フォーマットに「項目ごとに 実装 / 既存で十分 / スキップ理由 を明示する」チェックリスト形式を要求する。親側でも依頼項目数 vs 実装項目数の機械的突き合わせを行う（過去事例: PR #218 で 3 件依頼中 1 件のみ実装で完了報告された）。 - **`package.json` 変更時は `package-lock.json` 同期確認**: subagent が deps を追加・更新した場合、`git diff origin/develop --name-only` に `package.json` が含まれる場合は必ず `package-lock.json` も含まれているか確認する。漏れていれば親で `npm install --package-lock-only --cache "$TMPDIR/npm-cache" --no-audit --no-fund` を実行し別コミットで lock 同期を push する（過去事例: PR #181 で lock 不整合のまま push される寸前で発覚）。 - **PR 本文の更新は親で実行**: `gh pr edit --body-file` は `permissions.ask` のため subagent から非対話 deny される。subagent は完了報告に「PR 本文更新が必要」と明記し、親 (司令塔) が `gh pr edit` で引き取る（過去事例: PR #189 で subagent から呼べず指摘事項対応が止まった）。