diff --git a/.claude/skills/auto-audit/SKILL.md b/.claude/skills/auto-audit/SKILL.md index 702dea8..f486cc0 100644 --- a/.claude/skills/auto-audit/SKILL.md +++ b/.claude/skills/auto-audit/SKILL.md @@ -59,6 +59,16 @@ 11. **疑わしきは報告に落とす**：判断に迷う・裏取りで確信が持てない・再現テストが書けない・影響が追い切れない・テストコマンドが特定できない場合は，**無理に直さず報告のみ**にする（報告台帳へ）．修正よりも「新規バグを埋め込まないこと」を優先する． 12. **仕様・意図を推測で塗り替えない**：「これは仕様かバグか」の判断が要るものは自動修正しない．コードのコメントやドキュメントが示す意図に明確に反している場合のみ「バグ」と扱い，判断が割れるものは報告に回す． +## advisor への相談（`/consult`）— 上限付きで許可 + +不変条件 11・12 で「報告に落とす」と判断する前に，**項目オーケストレータ**は `/consult`（advisor エージェント・Fable）に相談してよい．無人で Fable が回り続けるのを防ぐため以下を厳守する． + +- **上限**: 1 ループ実行（`/auto-audit` の 1 起動）あたり **3 回まで**，かつ **1 指摘につき 1 回まで**．メインは相談回数を台帳に記録し，3 回に達したら以降の指摘は相談せずに従来どおり報告に落とす +- **相談してよい論点**: 「仕様かバグか」の判定，修正案が複数あって影響範囲の広さで迷う場合，のみ．裏取り（ゲート①）や調査の代わりには使わない +- **結論の扱い**: advisor の確信度が**高**のときだけ，その結論に従って修正に進んでよい（4 ゲートはそのまま通す）．確信度が中・低なら報告に落とし，advisor の結論・根拠を報告行に添える（人間の判断材料にする） +- advisor の助言は不変条件・除外リストを上書きしない（除外領域は相談しても触らない） +- 相談した指摘は台帳に「advisor 相談済み」と記す（次回の再相談を防ぐ） + ## 対象外の領域（除外リスト） — 修正対象に選ばない 以下は無人で触ると事故りやすい，あるいは本コマンドの責務外のため，**自動修正の対象に選ばない**．発見フェーズで指摘が出ても，修正はせず（重大なら報告のみに落とし）スキップする． diff --git a/.claude/skills/auto-refactor/SKILL.md b/.claude/skills/auto-refactor/SKILL.md index 63f9253..f154b52 100644 --- a/.claude/skills/auto-refactor/SKILL.md +++ b/.claude/skills/auto-refactor/SKILL.md @@ -59,6 +59,16 @@ 11. **ドキュメントリファクタは「意味保存」が絶対条件**：自動で行ってよいのは**意味・情報を保ったままの品質改善**だけ．具体的には ①無損失整形（表記揺れの統一・書式/見出し/表の整形・リンクや参照の修正・明らかなタイポ）と，②**意味を保った簡潔化・重複の集約**（冗長な言い回しを短くする，同一内容の重複を1か所に集約して他はリンクする）．**消してはいけないもの**＝事実・決定事項・設計判断（なぜその案にしたか）・失敗パターン・具体的な制約や閾値．これらが落ちる「陳腐化記述の削除」や「大規模な再編」は自動で行わず，要確認リストに**提案として記録**する．意味保存を自動検証する手段は無いため，迷ったら削らない（残す側に倒す）． 12. **テストリファクタは「検証力を落とさない」が絶対条件**：テストの整理では「検証スイートが緑」は安全網にならない（削除・弱体化したテストも緑のまま）．そこで**ミューテーションテストの差分**を安全網にする — リファクタ前に対象テストが守る本番コード範囲で「殺せるミュータント集合」を基準として取り，リファクタ後も**その全てを殺せたまま**なら検証力は保たれた＝安全（削除・統合・簡略化も可）．1つでも生存に転じたら検証力低下なので破棄する．ミューテーションテストが**走らせられない**場合（対応ツールが無い／恒久的な依存追加が必要／コスト非現実的）は，**構造改善（extract・共通化・命名・AAA 整理など検証を減らさないもの）のみ自動**とし，**テストの削除・アサーション弱体化・統合は提案として記録**する．テストコードへの自動編集はこのテストリファクタ処理（T）でのみ行う（コードリファクタ R はテストを触らない）． +## advisor への相談（`/consult`）— 上限付きで許可 + +不変条件 9 で「停止／skipped」と判断する前に，**項目オーケストレータ**は `/consult`（advisor エージェント・Fable）に相談してよい．無人で Fable が回り続けるのを防ぐため以下を厳守する． + +- **上限**: 1 ループ実行（`/auto-refactor` の 1 起動）あたり **3 回まで**，かつ **1 項目につき 1 回まで**．メインは相談回数を記録し，3 回に達したら以降の項目は相談せずに従来どおり skipped／提案記録に落とす +- **相談してよい論点**: リファクタ案が複数あり設計方針で迷う場合，ドキュメント簡潔化で「意味保存か情報損失か」の線引きに迷う場合，のみ．調査や候補探索の代わりには使わない +- **結論の扱い**: advisor の確信度が**高**のときだけ，その結論に従って作業に進んでよい（安全網＝テスト緑・ミューテーション差分はそのまま必須）．確信度が中・低なら作業せず，advisor の結論・根拠を要確認リストの `[提案]` 行に添える +- advisor の助言は不変条件・除外リストを上書きしない（矛盾の自動書き換え・除外領域への編集は相談しても行わない） +- 相談した項目は要確認リスト等に「advisor 相談済み」と記す（次回の再相談を防ぐ） + ## 対象外の領域（除外リスト） — コードリファクタの対象に選ばない 以下は無人で触ると事故りやすく，かつリファクタの価値が薄いため，**コードリファクタの対象に選ばない**．発見・選定時に必ず除外する． diff --git a/.claude/skills/consult/SKILL.md b/.claude/skills/consult/SKILL.md index 44a5fab..3e75619 100644 --- a/.claude/skills/consult/SKILL.md +++ b/.claude/skills/consult/SKILL.md @@ -1,9 +1,8 @@ --- name: consult model: inherit -description: "重要な価値判断・設計判断を最上位モデル（Fable）に相談する．メインのモデルは切り替えず，advisor エージェント（Fable）を新規の小さいコンテキストで起動するため，プロンプトキャッシュを壊さず低コストで判断力だけを借りられる．" +description: "重要な価値判断・設計判断を最上位モデル（Fable）に相談する．メインのモデルは切り替えず，advisor エージェント（Fable）を新規の小さいコンテキストで起動するため，プロンプトキャッシュを壊さず低コストで判断力だけを借りられる．Claude が自発的に使ってよいのは (a) 不可逆な設計判断（アーキテクチャ・スキーマ・外部サービス・公開 API の形）の直前，(b) 同じ失敗が 2 回続き次の方針に自信が無いとき，(c) ユーザーの明示指示，のいずれかに限る．1 タスクあたり 2 回まで．ルールで既に決まっている事項・すぐ決まる二択・単なる調査には使わない．" argument-hint: "<相談したい論点（省略時はセッションの文脈から構成する）>" -disable-model-invocation: true --- あなたは相談の司令塔です．価値判断そのものは **advisor エージェント**（Fable）に委ね，あなたは**ブリーフの作成**と**結果の中継**を行います．メインループのモデルは切り替えない（会話全体の再読込が発生するため）．advisor は新規の小さいコンテキストで動くので，Fable の単価でもコストはブリーフ＋参照ファイル＋思考分だけに収まる． @@ -31,8 +30,37 @@ - 自分の暫定意見と advisor の結論が食い違う場合は，その旨と自分の見解を明示する（隠さない） - 最終決定はユーザーが行う．advisor の結論を自動で実行に移さない +## 自発的に呼ぶ基準 (Auto-Invocation Criteria) + +Claude はユーザー指示が無くても，以下の**いずれか**に該当するときは本スキルを自発的に使ってよい．組み込みの `/advisor`（会話全体を上位モデルに読ませる）ではなく本スキルを使うのは，ブリーフ＋参照ファイル分のコンテキストだけで済ませてコストを抑えるため． + +**呼ぶ** + +| トリガー | 判定の目安 | +| --- | --- | +| 不可逆な設計判断 | アーキテクチャ・DB スキーマ・外部サービス選定・公開 API の形など，後から変えるとコードの広範囲に波及するものを決める直前 | +| 行き詰まり | 同じ失敗（テスト失敗・エラー）が **2 回**続き，3 回目の方針に自信が無い | +| ユーザー指示 | 「advisor に聞いて」「相談して」等の明示 | + +**呼ばない** + +- `.claude/rules/` や docs で既に決まっている事項（ルールに従えばよい） +- 数分で決まる二択，命名，小さなリファクタ +- 単なる調査・情報収集（advisor は判断役であって検索役ではない．調査は Explore 等を使う） +- 同じ論点で既に advisor の回答を得ている（再相談は前提が変わったときだけ） +- 大きなタスクの完了前チェック（人間の動作確認で代替する．自動では呼ばない） + +## 暴走の歯止め (Cost Guardrails) + +Fable の呼び出しは相対的に高コストのため，自発的に呼ぶときは以下を守る． + +- **上限**: 1 タスク（ユーザーからの 1 回の依頼）につき**自発的な呼び出しは 2 回まで**．3 回目が必要だと感じたら，呼ばずにユーザーへ「advisor に相談してよいか」を確認する +- **再委譲**: 前提の補足によるやり直しは **1 回まで**．それでも噛み合わなければ得られた回答をそのまま報告し，判断を人間に戻す +- **参照ファイル**: ブリーフに列挙するのは **5 ファイル程度**を目安に絞る（advisor の読み込み分がコストの主因） +- **可視化**: 呼ぶ前に必ず「advisor に相談します: <論点 1 行>」と表示する（黙って呼ばない） +- **無人ループ**: `/auto-refactor`・`/auto-audit` の中から呼ぶ場合は，各 skill に定める上限（1 ループ実行あたり 3 回・1 項目 1 回）に従う + ## 注意事項 (Notes) -- 本スキルはユーザーが明示的に起動した時のみ実行する（Fable の呼び出しはコストが相対的に高いため，Claude が自発的に呼ばない） - ブリーフに書かれていない事情は判断に反映されない．「advisor は会話を知らない」前提で書くこと - 軽い相談（すぐ決められる二択等）に使う必要はない．アーキテクチャ選定・不可逆な決定・トレードオフが深い論点に使う diff --git "a/docs/01_GUIDE/GUIDE_02_\343\202\250\343\203\274\343\202\270\343\202\247\343\203\263\343\203\210\351\201\213\347\224\250\343\203\253\343\203\274\343\203\253.md" "b/docs/01_GUIDE/GUIDE_02_\343\202\250\343\203\274\343\202\270\343\202\247\343\203\263\343\203\210\351\201\213\347\224\250\343\203\253\343\203\274\343\203\253.md" index 72d1c09..429b73d 100644 --- "a/docs/01_GUIDE/GUIDE_02_\343\202\250\343\203\274\343\202\270\343\202\247\343\203\263\343\203\210\351\201\213\347\224\250\343\203\253\343\203\274\343\203\253.md" +++ "b/docs/01_GUIDE/GUIDE_02_\343\202\250\343\203\274\343\202\270\343\202\247\343\203\263\343\203\210\351\201\213\347\224\250\343\203\253\343\203\274\343\203\253.md" @@ -27,7 +27,7 @@ | --- | --- | --- | | `ops-runner` | git・gh・検証コマンドの機械的な実行（手順書に忠実に従い，判断が要る事態では停止して報告する） | `/commit`・`/task-create`・`/task-start`・`/task-handoff`・`/deps-update` | | `deps-analyst` | 依存更新 1 件の影響分析（破壊的変更の抽出・利用箇所の突き合わせ・推奨対応） | `/deps-update` | -| `advisor` | 重要な価値判断・設計判断の相談役（Fable による熟考・助言．実装はしない） | `/consult` | +| `advisor` | 重要な価値判断・設計判断の相談役（Fable による熟考・助言．実装はしない）．Claude が自発的に呼んでよい基準（不可逆な設計判断の直前・同じ失敗が 2 回続いたとき）と上限（1 タスク 2 回，無人ループは 1 起動 3 回）は `/consult` skill に定める | `/consult`（`/auto-refactor`・`/auto-audit` からも上限付きで使用） | ## パイプラインの流れと人間の役割 (Pipeline & Human's Role)