docs: Opus 5 の挙動を踏まえ出力量の規律と委譲判断を規約化

[fumtas1k]

目的

公式ガイド Prompting Claude Opus 5 と本リポジトリの規約（CLAUDE.md / .agents/rules/ / .claude/rules/ / vendor skills）を突き合わせ、規約が欠落していた 2 点を .agents/rules/common.md に追加する。

変更内容

1. 1.1 出力量の規律（新設）

現行世代モデルは会話応答も生成ドキュメントも既定で長く、長さは effort / thinking 設定では制御できない（思考量を変えるだけで可視出力の長さは縮まない）。従来の規約に長さ規定は 11 章の「この doc では肥大化させない」1 箇所しかなかった。

PR 本文 / plan・spec / agent-lessons.md / 会話応答それぞれの基準を明示し、長い Markdown が format:check 失敗確率を上げる点（3 章・PR #753 の事例と同根）も併記した。

2. 6.9 に「委譲するかどうかの判断」小節を追加

従来の 6.9 は委譲後の品質ルール（完了報告フォーマット・lock 同期・PR 本文は親）のみで、いつ委譲しないかが未定義だった。現行世代モデルは委譲に積極的なため、非委譲条件を明文化した。

• 親が数回の tool 呼び出しで完結できる作業
• 検証・ダブルチェック目的の subagent（検証は親のループ内 = 3 章の必須チェック）
• 1 体で足りる作業への複数体並列投入

あわせて reviewer subagent（requesting-code-review）の適用範囲を「複数ファイルにまたがる機能追加 / セキュリティ関連変更」に限定した。skill 側は「major feature 後 / merge 前は mandatory」だが、solo dev 体制（6.7 節）で人間レビューが無いため全廃はせず、既定で回すのもやめる方針。vendor skill 本体は skills-lock.json 管理のため触っていない。

「仕様は最初のプロンプトで完結させる」指針も追加（既存の「矛盾する設計指示を混ぜない」と同根の問題）。

適用しなかった項目（意図的）

突き合わせで挙がったが今回スコープ外にしたもの:

項目	判断
会話応答の冗長さ抑制（"Keep responses concise" 系の指示） / 自己訂正ナレーション抑制	Claude Code の system prompt に同等の指示が既にあり、common.md に書くと二重定義になる
verification-before-completion skill と 3 章の重複整理	skill は「claim 前に実コマンド出力を読む」= 事実報告の正確性であり over-verification の主因ではないため保持。重複注記は未実施
検証指示の区別の明文化	下記「注意」参照。今回は書いていない
docs/decisions.md への記録	4 章の対象（設計上の決断）に当たる可能性あり。出典リンクは common.md 内に埋め込んだが、decisions.md への追記は未実施

補足（レビュー指摘 1）: 1.1 節にも 会話応答 の bullet があるが、そちらは**「結論を先に置く」「過圧縮を避ける」という構成の指針であり、上表で除外した「短くせよ」という冗長さ抑制の指示**とは別物。同じ語が並ぶため紛らわしいが矛盾ではない。

⚠️ 将来のセッション向けの注意（本 PR では未記載）

Opus 5 ガイドの「検証指示を削除せよ」はモデルに自己再確認を促す prompt scaffolding（"double-check your answer" 等）が対象であり、3 章の npm run test / astro check / format:check / test:e2e は実コマンドを走らせる tooling gate なので削除対象ではない。この区別を規約に明文化しておかないと「Opus 5 の推奨だから」と 3 章を緩める事故が起きうる。必要なら別 PR で追記する。

検証

チェック	結果
npm run format:check	✅ pass
npm run test	✅ 148 files / 2716 passed, 1 skipped
node_modules/.bin/astro check	✅ 0 errors / 0 warnings / 0 hints
npm run test:e2e	⏭️ 未実行

E2E 未実行の理由: diff は .agents/rules/common.md のみ（git diff --name-only で確認済み、src/ tests/ に変更なし）で、E2E が検証する実行時挙動に影響しない。CI を最終ゲートとする。

🤖 Generated with Claude Code

---

レビュー対応（2026-07-27）

指摘	対応
指摘 1（clarity）: 表と 1.1 節で 会話応答 の語が衝突し混乱しうる	✅ 対応。上表の該当行に「冗長さ抑制」と明示し、1.1 節の bullet が「構成の指針」で別物である旨の補足を追加
指摘 2（discoverability）: skill 側の "mandatory" と方針が食い違う旨を一行足す	✅ すでに diff に含まれている（下記）

指摘 2 について、.agents/rules/common.md の該当行に既に注記が入っています。

**reviewer subagent（`requesting-code-review` skill）の適用範囲**: … 使わない（skill 側の記述は
「major feature 後 / merge 前は mandatory」だが、本リポジトリの適用方針はこちらが優先）。

ご指摘の「skill と方針が異なる旨を一行」はこの括弧書きが担っているため、追加の変更はしていません。skill 本体を読むだけのセッションが気づけないという構造的な課題は残りますが、skills-lock.json 管理下のため vendor skill 側は変更しない方針です。

コード変更なし（指摘 1 は PR 本文のみの修正、指摘 2 は対応済みのため）。

[github-actions]

🖼️ Visual Regression Test 結果

• Status: ✅ 全 74 件 pass
• Workflow run: 30263152077
• Artifact (diff 画像 / playwright-report): 上記 workflow run の Artifacts セクションから download

diff が 意図的な visual 変更の場合: Update Visual Regression Baseline workflow を本 PR ブランチで workflow_dispatch trigger して baseline を更新。
diff が 意図しない regression の場合: 該当変更を fix。
本 check は required ではないため fail のままでも merge は可能（reviewer 判断）。

[fumtas1k]

レビュー: PR #758（多角的観点）

docs 単独変更（.agents/rules/common.md のみ / +27 行）。src/ tests/ に影響なく、E2E 未実行の判断は妥当。観点別に評価する。

セキュリティ

影響なし。むしろ「検証・ダブルチェック目的の subagent は委譲しない」と reviewer subagent の適用範囲限定を追加しつつ、セキュリティ関連変更は reviewer subagent の適用対象として明示残している carve-out は適切で、レビュー厳格性を落とさない設計になっている。

フロントエンド / スタイル

UI 変更なし。Markdown 記法（表・見出し・コードスパン）は既存 doc の様式に沿っており format:check pass 済み。末尾空白の混入もなし（9.3 章準拠）。

ロジック / 整合性

相互参照（3 章 / 6.7 節 / 「矛盾する設計指示を混ぜない」）はいずれも実在し正しい。1.1 / 6.9 の小節番号付けも既存パターン（6.2.1 7.1）と整合。「長い Markdown は format:check 失敗確率を上げる（PR #753 と同根）」の因果も既存 3 章の記述と一致している。

アーキテクチャ（規約構造）

6.9 を「委譲前の判断 / 委譲後の運用」に二分した構成は、従来「委譲後」しか無かった穴を埋めており読みやすさも向上。common.md を SoT として skill 記述より優先すると明記した点も 11 章の SoT 方針と整合。

テスト

docs 変更のため実行時テスト対象外。meta テスト（tests/meta/）は tool 追加・icon・VRT ページの整合を見るもので本 diff とは無関係。検証欄の記載（format:check / test / astro check pass、E2E skip 理由）も妥当。

---

指摘 1（clarity・要検討 / inline 参照）

PR 本文の「適用しなかった項目」表では『会話応答の簡潔さ … は二重定義になるので入れない』としているが、1.1 に 会話応答 bullet が入っており、表と突き合わせた読み手が混乱しうる。内容は「簡潔さ」ではなく「結論先出し + 過圧縮防止」で別物のため矛盾ではないが、同じ語で衝突するので一言の補足を推奨。

指摘 2（discoverability・任意 / スコープ外可）

reviewer subagent を「複数ファイル機能追加 / セキュリティ変更」に限定する方針は、vendored skill 側の "mandatory" と食い違う。common.md 優先と明記済で運用は成立するが、skill だけ読む将来セッションは気づけない。skills-lock 管理で skill 本体は触れないため、対応するなら現記述に「skill と方針が異なる」旨を一行足す程度で十分。

---

総評: 規約追加として妥当で内部整合も取れており、ブロッカーはない。指摘 1 のみ一言の補足を推奨（指摘 2 は任意）。

---

Generated by Claude Code

[fumtas1k]

PR 本文の「適用しなかった項目」表では『会話応答の簡潔さ … は system prompt と二重定義になるので入れない』としているが、この bullet で 会話応答 を扱っているため、表と突き合わせた読み手が「除外したはずでは？」と混乱しうる。

内容自体は「簡潔さ」ではなく「結論先出し + 過圧縮の禁止（短さより読みやすさを優先）」で、除外対象とは別物なので矛盾はしていない。ただ両者が同じ「会話応答」語で衝突するため、ここに「＝簡潔さの指示ではなく構造・過圧縮防止の規律」と一言添えるか、PR 本文表側に但し書きを足すと誤読を防げる。

セクション見出しが「出力量の規律」なのに対しこの bullet だけ「短さより読みやすさを優先」と逆方向を向いている点も、意図（過圧縮への歯止め）が伝わりにくい一因。

---

Generated by Claude Code

[fumtas1k]

レビューありがとうございます。2 件の指摘を確認しました。

指摘 1（clarity）→ 対応しました

ご指摘のとおり、PR 本文の表現が不正確でした。表側を「会話応答の冗長さ抑制（"Keep responses concise" 系の指示）」に改め、1.1 節の 会話応答 bullet が**「結論を先に置く」「過圧縮を避ける」という構成の指針**で別物である旨の補足を表の直後に追加しました。

common.md 側は変更していません。1.1 節の bullet 自体は「結論を最初の 1 文に置く」「削るなら情報の選別で削る（矢印連結・省略語・断片文への圧縮では削らない）」と書いており、"簡潔にせよ" とは読めない表現になっているためです。混乱の原因は PR 本文の側にあったと判断しました。

指摘 2（discoverability）→ すでに diff に含まれています

「skill と方針が異なる旨を一行足す」については、.agents/rules/common.md の該当行に既に括弧書きで入っています。

**reviewer subagent（`requesting-code-review` skill）の適用範囲**: 本リポジトリでは 複数ファイルにまたがる
機能追加 / セキュリティ関連の変更 に限定する。単一ファイルの修正・docs のみの変更・リファクタの小変更では
使わない（skill 側の記述は「major feature 後 / merge 前は mandatory」だが、本リポジトリの適用方針はこちらが優先）。

そのため追加の変更はしていません。「skill 本体だけ読むセッションは気づけない」という構造的な課題自体は残りますが、skills-lock.json 管理下のため vendor skill 側は触らない方針です（.agents/skills/README.md の運用に従う）。

---

本 diff への変更はありません（指摘 1 は PR 本文のみ、指摘 2 は対応済み）。検証結果も変わらず format:check / test / astro check すべて pass のままです。

Generated by Claude Code

[fumtas1k]

再レビュー: 修正確認

コード diff（.agents/rules/common.md、+27 行）は前回から不変で、修正は PR 本文のみ。以下のとおり確認した。

指摘	対応	判定
1（clarity）: 表と 1.1 節で 会話応答 の語が衝突し混乱しうる	表の該当行を「冗長さ抑制（"Keep responses concise" 系）」と限定し、1.1 の bullet は「構成の指針（結論先出し / 過圧縮防止）」で別物である旨の補足を追加	✅ 解消
2（discoverability）: skill 側 "mandatory" と方針が食い違う旨の明示	既存の括弧書き（「skill 側は mandatory だが本リポジトリの適用方針が優先」）が担っている旨を明示	✅ 妥当（対応済）

指摘 1 は「表 vs diff の読み手混乱」が主眼だったため、PR 本文側での語の限定で過不足なく解消している（doc 単体には除外表が無いため矛盾は生じない）。指摘 2 も既存記述で意図は成立しており、skill 単独読者が気づけない構造的課題は skills-lock.json 管理制約として妥当に切り分けられている。

新規の問題は検出なし。ブロッカーなし・merge 可。format:check / test / astro check の緑も PR 本文で確認済み。

---

Generated by Claude Code