From 18f005e9f2673387b1557375a46c4fcdba6839f0 Mon Sep 17 00:00:00 2001 From: 9uiLe Date: Thu, 2 Jul 2026 05:59:22 +0900 Subject: [PATCH] =?UTF-8?q?feat:=20quality-architect=20=E5=89=8A=E6=B8=9B?= =?UTF-8?q?=E3=82=A2=E3=82=AF=E3=82=B7=E3=83=A7=E3=83=B3=E5=BF=85=E9=A0=88?= =?UTF-8?q?=E5=8C=96=20/=20model-strategy=20Fable=205=E3=83=BBCodex=20?= =?UTF-8?q?=E5=AF=BE=E5=BF=9C?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit quality-architect (v0.1.4): - 07a §6.3.1 削減アクション・カタログを新設し、結合・複雑性指摘に Strength/Distance/Volatility の削減手順の併記を必須化（severity には非影響） - 両 SKILL.md の Khononov 禁則 verbatim 重複を 07a §9 参照に単一ソース化 model-strategy (v0.1.1): - Fable 5 の実効コスト誤記載を訂正（トークナイザは Opus 4.8 と同一、約 2 倍） - サブスク提供条件（〜2026-07-07 週次上限 50% 同梱 → 従量クレジット）を 00-pricing §4 に追加し、01/02/03/SKILL.md をフェーズ別判断に更新 - Codex CLI 対応: references/07-codex.md 新設（GPT 系価格・reasoning effort・ マルチエージェント委譲・キャッシュ）、SKILL.md に実行環境判定 §0.5 を追加 - Sonnet 5 を価格表に追加 Co-Authored-By: Claude Fable 5 --- .claude-plugin/marketplace.json | 4 +- CHANGELOG.md | 14 +++++ .../model-strategy/.claude-plugin/plugin.json | 2 +- .../model-strategy/.codex-plugin/plugin.json | 2 +- plugins/model-strategy/README.md | 3 +- .../model-strategy/references/00-pricing.md | 35 ++++++++--- .../references/01-effort-levels.md | 6 ++ .../references/02-decision-matrix.md | 17 +++-- .../references/03-cost-levers.md | 3 +- plugins/model-strategy/references/07-codex.md | 63 +++++++++++++++++++ .../skills/model-effort-guide/SKILL.md | 14 +++++ .../.claude-plugin/plugin.json | 2 +- .../.codex-plugin/plugin.json | 2 +- plugins/quality-architect/README.md | 2 +- .../references/07a-coupling-deep-dive.md | 22 ++++++- .../skills/quality-architecture/SKILL.md | 5 +- .../skills/quality-review/SKILL.md | 7 ++- 17 files changed, 177 insertions(+), 26 deletions(-) create mode 100644 plugins/model-strategy/references/07-codex.md diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 2a4ee16..6902305 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -27,7 +27,7 @@ "name": "quality-architect", "source": "./plugins/quality-architect", "description": "Design and review software architecture against the ISO/IEC 25010:2023 product quality model (9 characteristics, 40 subcharacteristics), with a reference library of verified academic and official citations.", - "version": "0.1.3", + "version": "0.1.4", "category": "development", "tags": [ "iso-25010", @@ -41,7 +41,7 @@ "name": "model-strategy", "source": "./plugins/model-strategy", "description": "Cost-effective model and effort selection for Claude Code: a task-classification skill that recommends the optimal model (Fable/Opus/Sonnet/Haiku) and effort level, plus pre-configured Sonnet/Haiku subagents for cheap delegation, backed by official pricing references.", - "version": "0.1.0", + "version": "0.1.1", "category": "development", "tags": [ "model-selection", diff --git a/CHANGELOG.md b/CHANGELOG.md index 82fac26..45ffd8d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,20 @@ ## [Unreleased] +### Added + +- **quality-architect** (v0.1.4): 結合・凝集・複雑度・モジュール境界に関する指摘への「削減アクション」必須化。`references/07a-coupling-deep-dive.md` に §6.3.1「削減アクション・カタログ」（検出状況 → 下げる軸 → 具体的手順の対応表と提示書式）を追加し、`quality-review`（step 5・指摘テンプレ・§5）と `quality-architecture`（章 4'・§4）が BALANCE = FALSE の結合・複雑性を検出した際に Khononov のリバランス 3 軸（Strength↓ / Distance↓ / Volatility 隔離）に基づく具体的な削減手順の併記を要求するように。アクションは severity / verdict に影響しない（H9 維持）。 +- **model-strategy** (v0.1.1): Codex CLI 対応。`SKILL.md` に実行環境判定（§0.5）と Codex での委譲代替手順（`/model`・`codex exec -m`・低 reasoning effort の別実行）、`references/07-codex.md`（GPT 系モデル価格・reasoning effort・サブスク制限の決定基準）を追加。 +- **model-strategy** (v0.1.1): Fable 5 のサブスクリプション提供条件（〜2026-07-07 は週次上限 50% キャップで同梱、以降は API 単価の従量クレジット、セーフガードによる Opus 4.8 自動フォールバック）を `00-pricing.md` §4 に追加し、`01`/`02`/`03`/`SKILL.md` の判断基準を提供フェーズ別に更新。 + +### Changed + +- **quality-architect** (v0.1.4): 両 SKILL.md に verbatim 重複していた Khononov 引用禁則（Pain 式の 2 留保・Instability 代理禁止・H9 片方向）を `07a §9` への単一ソース参照に置換し、規律の二重管理を解消。 + +### Fixed + +- **model-strategy** (v0.1.1): `00-pricing.md` の「Fable 5 は新トークナイザで Opus 系比 30% 増 → 実効 2.6 倍」という誤記載を訂正。Fable 5 のトークナイザは Opus 4.8 と同一で、実効コストは名目通り約 2 倍（30% 増は Opus 4.7 系トークナイザ vs 旧世代モデルの比較）。 + ## [0.1.5] - 2026-06-15 ### Changed diff --git a/plugins/model-strategy/.claude-plugin/plugin.json b/plugins/model-strategy/.claude-plugin/plugin.json index f956426..ddaf8d7 100644 --- a/plugins/model-strategy/.claude-plugin/plugin.json +++ b/plugins/model-strategy/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "model-strategy", - "version": "0.1.0", + "version": "0.1.1", "description": "Cost-effective model and effort selection for Claude Code. Provides a task-classification skill (model-effort-guide) that recommends the optimal model (Fable/Opus/Sonnet/Haiku) and effort level per task, plus pre-configured subagents (sonnet-implementer / haiku-scout) for cheap delegation. Backed by a reference library with official pricing and effort documentation.", "author": { "name": "9uiLe" diff --git a/plugins/model-strategy/.codex-plugin/plugin.json b/plugins/model-strategy/.codex-plugin/plugin.json index 788ebb3..88259ee 100644 --- a/plugins/model-strategy/.codex-plugin/plugin.json +++ b/plugins/model-strategy/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "model-strategy", - "version": "0.1.0", + "version": "0.1.1", "description": "Cost-effective model and effort selection for Claude Code workflows.", "author": { "name": "9uiLe", diff --git a/plugins/model-strategy/README.md b/plugins/model-strategy/README.md index 79ba6ef..9684f48 100644 --- a/plugins/model-strategy/README.md +++ b/plugins/model-strategy/README.md @@ -32,6 +32,7 @@ Claude Code を従量課金前提でコスパよく運用するための、Claud | [04-large-codebase.md](./references/04-large-codebase.md) | 大規模コードベースの量制御・常駐コンテキストを平坦に保つ規定 | | [05-repo-index.md](./references/05-repo-index.md) | ナビゲーション索引 (pull 優先)・外部 queryable 索引を第一に薄い CLAUDE.md 地図はフォールバック | | [06-context-monitor.md](./references/06-context-monitor.md) | コンテキスト量を statusLine で可視化する同梱スクリプトと配線手順 | +| [07-codex.md](./references/07-codex.md) | Codex CLI (GPT 系モデル) の価格・reasoning effort・委譲代替の決定基準 | ## 戦略の要約 @@ -43,7 +44,7 @@ Claude Code を従量課金前提でコスパよく運用するための、Claud | 探索・調査・定型作業 | haiku-scout | — | | 大量の機械的一括処理 | Batches API (API 直叩き、50% off) | — | -Fable 5 は新トークナイザにより実効コストが Opus 4.8 の約 2.6 倍のため、長時間自律実行や Opus で失敗を繰り返すタスクに限定します。 +Fable 5 は Opus 4.8 比で約 2 倍のコスト（トークナイザは同一）。サブスク同梱期間（〜2026-07-07・週次上限の 50% キャップ）は最難関の判断タスクに集中投下し、以降は従量クレジット（$10/$50）前提で「長時間自律実行」「Opus で失敗を繰り返すタスク」に限定します（詳細: [00-pricing.md §4](./references/00-pricing.md)）。 ## インストール diff --git a/plugins/model-strategy/references/00-pricing.md b/plugins/model-strategy/references/00-pricing.md index 080a949..ba6b533 100644 --- a/plugins/model-strategy/references/00-pricing.md +++ b/plugins/model-strategy/references/00-pricing.md @@ -1,8 +1,8 @@ # モデル価格とコスト構造 -> **典拠**: platform.claude.com — Models Overview / Pricing (claude-api skill 経由、2026-06-04 時点キャッシュ)。最新値は `https://platform.claude.com/docs/en/pricing.md` を参照すること。 +> **典拠**: platform.claude.com — Models Overview / Pricing (claude-api skill 経由、2026-06-24 時点キャッシュ) + Anthropic 公式発表 (2026-07-02 確認)。最新値は `https://platform.claude.com/docs/en/pricing.md` を参照すること。 > -> **前提に関する注記**: 「Claude Code がサブスクリプションから従量課金制に移行する」という点について、本書執筆時点で公式発表の確認は取れていない(=未確認の前提)。本書は API 従量課金の価格体系をベースに「移行した場合でも合理的な運用」を設計するものである。 +> **サブスクリプションとの関係**: Claude Code のサブスク利用でも、Fable 5 は §4 の通り **期間限定の同梱枠 → 従量課金クレジット** に移行することが公式に確定した。他モデルは引き続きサブスク枠内。本書の API 価格は「クレジット消費の単価」および「委譲でどれだけ枠消費を減らせるか」の基準として読む。 ## §1 価格表 (per 1M tokens) @@ -10,12 +10,15 @@ | --- | --- | --- | --- | --- | --- | | Claude Fable 5 | `claude-fable-5` | 1M | $10.00 | $50.00 | 10x | | Claude Opus 4.8 | `claude-opus-4-8` | 1M | $5.00 | $25.00 | 5x | +| Claude Sonnet 5 | `claude-sonnet-5` | 1M | $3.00 ($2.00 intro 〜2026-08-31) | $15.00 ($10.00 intro) | 3x | | Claude Sonnet 4.6 | `claude-sonnet-4-6` | 1M | $3.00 | $15.00 | 3x | | Claude Haiku 4.5 | `claude-haiku-4-5` | 200K | $1.00 | $5.00 | 1x | -### Fable 5 の実効コストに関する注意 +### Fable 5 の実効コスト（旧記載の訂正） -Fable 5 は新トークナイザを採用しており、**同一コンテンツが Opus 系比で約 30% 多くトークン化される**(典拠: Model Migration Guide「Migrating to Claude Fable 5 — New tokenizer」)。名目 $10/$50 だが、Opus 系と同じ仕事量で比較すると実効 **約 $13/$65 相当**。Opus 4.8 比で実効 **約 2.6 倍**のコストになる。 +**Fable 5 のトークナイザは Opus 4.8 と同一**（Opus 4.7 で導入されたもの）であり、Opus 4.7/4.8 からの移行でトークン数はほぼ不変。したがって実効コストは名目通り **Opus 4.8 比でちょうど約 2 倍**（$10/$50 vs $5/$25）。 + +> ⚠️ 旧版の本書には「Fable 5 は新トークナイザで Opus 系比 30% 増 → 実効 2.6 倍」という記載があったが、これは **誤り**。「約 30% 増」は Opus 4.7 系トークナイザを **旧世代モデル（Opus 4.6 / Sonnet 4.6 / Haiku）と比較した場合** の話（典拠: Model Migration Guide「Migrating to Claude Fable 5 — Tokenizer」）。なお **Sonnet 5 は新トークナイザ採用で Sonnet 4.6 比 約 30% 多く**トークン化される（単価は同じでも同一作業のコストは増える。intro 価格が相殺）。 ## §2 コスト構造の直感 @@ -29,9 +32,9 @@ Fable 5 は新トークナイザを採用しており、**同一コンテンツ | 担当 | コスト | | --- | --- | -| Fable 5 (実効) | 約 $65 | +| Fable 5 | $50 | | Opus 4.8 | $25 | -| Sonnet 4.6 | $15 | +| Sonnet 5 / 4.6 | $15 (Sonnet 5 intro: $10) | | Haiku 4.5 | $5 | ## §3 キャッシュ・バッチの価格 (典拠: Prompt Caching / Batch docs) @@ -41,4 +44,22 @@ Fable 5 は新トークナイザを採用しており、**同一コンテンツ | キャッシュ読み取り | base input の約 0.1 倍 | | キャッシュ書き込み (5分 TTL) | base input の 1.25 倍 | | キャッシュ書き込み (1時間 TTL) | base input の 2 倍 | -| Batches API | 全トークン 50% off (非対話・最大24h、API 直叩きのみ) | +| Batches API | 全トークン 50% off (非対話・最大24h、API 直叩きのみ。Fable 5 なら $5/$25 相当) | + +## §4 Fable 5 のサブスクリプション提供条件 (2026-07-02 確認・時限情報) + +Fable 5 はサブスクリプション（Pro / Max / Team / Enterprise Premium シート）での扱いが他モデルと異なる: + +| 項目 | 内容 | +| --- | --- | +| 同梱期間 | **2026-07-07 まで**、週次使用上限の **50% を上限** に追加費用なしで利用可（2026-07-01 の再提供以降） | +| 50% キャップの性質 | 保証枠ではなく上限。ヘビーユースなら 7/7 より前に使い切る | +| 2026-07-08 以降 | **usage credits（従量課金クレジット）** に移行。単価は API と同じ **$10/$50 per 1M tokens**（Batch 50% off） | +| Enterprise Standard シート | 同梱枠なし。当初から credits 必須 | +| クォータ消費 | Fable 5 は思考・出力トークンが多く、**週次上限を他モデルより速く消費する** | +| セーフガード | 安全クラシファイアが一部リクエストを拒否し、**自動で Opus 4.8 にフォールバック** することがある（ルーチンなコーディングでも誤検知あり） | +| 経緯 | 2026-06-09 提供開始 → 06-12 一時停止（輸出規制対応）→ 07-01 セーフガード付きで再提供 | + +**運用への含意**（詳細は `02-decision-matrix.md` §2）: 同梱期間中は「Fable 5 でしか差が出ない判断タスク」に 50% 枠を集中投下し、定型・実装は Opus/Sonnet に退避して枠を温存する。7/8 以降は credits = API 単価なので、本書のコスト比較がそのまま適用される。 + +> ⏰ 本節は時限情報。7/7 経過後・Anthropic の追加発表後は要更新。 diff --git a/plugins/model-strategy/references/01-effort-levels.md b/plugins/model-strategy/references/01-effort-levels.md index 09cd869..79a65d8 100644 --- a/plugins/model-strategy/references/01-effort-levels.md +++ b/plugins/model-strategy/references/01-effort-levels.md @@ -30,6 +30,12 @@ ### Fable 5 - **`low` でも従来モデルの `xhigh`〜`max` を超える品質が出ることが多い**(公式記載)。Fable 5 を使うときほど effort を下げる余地がある - 高 effort ではルーチン作業に対して過剰なコンテキスト収集・熟考をしがち。正しく完了するのに時間がかかりすぎる場合は effort を下げる +- **thinking は常時オン**(オフにできない)。思考トークンも output 課金されるため、同じタスクでも他モデルよりトークン消費が多くなりやすい。サブスク同梱枠(`00-pricing.md` §4)は週次上限を共有しているので、**枠温存の観点でも既定を `high` ではなく `medium`〜`high` に置き、`xhigh`/`max` は最難関のみに限定**するのが効率的 +- 単発の難問なら「Fable 5 (low〜medium)」が「Opus 4.8 (xhigh)」より安く良い結果になるケースがある。迷ったら両者を同一タスクで比較して経路を固定する + +### Sonnet 5 +- Sonnet 帯で初めて `xhigh` に対応。`medium` ≈ Sonnet 4.6 の `high`、`high` ≈ Sonnet 4.6 の `max` に相当(公式マッピング) +- adaptive thinking がデフォルトでオン(4.6 はオフ)。thinking 分の output 課金が増えるので、定型用途は `thinking: disabled` か effort `low` を明示する ### Sonnet 4.6 - デフォルトが `high` なので、チャット的・定型的な用途では明示的に `low`/`medium` に下げないと過剰消費する diff --git a/plugins/model-strategy/references/02-decision-matrix.md b/plugins/model-strategy/references/02-decision-matrix.md index 1818fc5..ce0e739 100644 --- a/plugins/model-strategy/references/02-decision-matrix.md +++ b/plugins/model-strategy/references/02-decision-matrix.md @@ -21,10 +21,19 @@ ### メインセッションを Fable 5 にすべきか? -Fable 5 は実効コストが Opus 4.8 の約 2.6 倍 (`00-pricing.md` §1)。次の場合のみ Fable 5 を使う: - -- 長時間の自律実行(夜間ラン・大規模マイグレーション)で、失敗・やり直しのコストがモデル差額を上回る -- Opus 4.8 で 2 回失敗したタスク(やり直し 2 回 > 差額) +Fable 5 のコストは Opus 4.8 の約 2 倍(トークナイザは同一。`00-pricing.md` §1)。ただし判断はサブスク提供フェーズ(`00-pricing.md` §4)で変わる: + +**同梱期間中(〜2026-07-07・週次上限の 50% キャップ)** +- 追加費用ゼロで使える一方、**週次クォータを他モデルより速く消費**し、キャップに達すると期限前でも使えなくなる +- → 50% 枠は「Fable 5 でしか差が出ないタスク」に集中投下する: アーキテクチャ設計・最難関のデバッグ/実装・大規模マイグレーションの計画 +- 定型実装・探索・レビューの検証 fan-out は従来通り Opus/Sonnet/Haiku に流し、枠を温存する +- effort は `medium`〜`high` 起点(`01-effort-levels.md`: Fable 5 は low でも従来の xhigh 級)。`xhigh`/`max` 常用は枠の浪費 +- セーフガードにより一部リクエストは **Opus 4.8 に自動フォールバック**される。Fable 前提のワークフローを組まない + +**従量クレジット期(2026-07-08 以降、または Enterprise Standard)** +- credits は API 単価($10/$50)なので純粋なコスト判断に戻る。次の場合のみ Fable 5: + - 長時間の自律実行(夜間ラン・大規模マイグレーション)で、失敗・やり直しのコストがモデル差額を上回る + - Opus 4.8 で 2 回失敗したタスク(やり直し 2 回 > 差額) - それ以外の日常開発は **Opus 4.8 (high) で十分** ### Sonnet に委譲できる実装の判定基準 diff --git a/plugins/model-strategy/references/03-cost-levers.md b/plugins/model-strategy/references/03-cost-levers.md index 2fe9d80..6f88300 100644 --- a/plugins/model-strategy/references/03-cost-levers.md +++ b/plugins/model-strategy/references/03-cost-levers.md @@ -36,7 +36,8 @@ Opus 4.8 / Fable 5 は「最初のターンで完全な仕様を渡して高 eff | アンチパターン | 何が起きるか | | --- | --- | | 全部メインセッション(高性能モデル)でやる | 探索・定型まで最高単価で課金 | -| Fable 5 を常用する | Opus 4.8 比で実効約 2.6 倍。差が出るタスクは限られる | +| Fable 5 を常用する | Opus 4.8 比で約 2 倍 + 思考常時オンで週次クォータを速く消費(`00-pricing.md` §4)。差が出るタスクは限られる | +| Fable 5 で effort xhigh/max を常用する | low〜medium でも従来モデルの xhigh 級。枠・クレジットの浪費 | | effort max を常用する | 過剰思考で収穫逓減(公式記載)。コストだけ増える | | サブエージェントに小出しで指示する | 往復ごとにコンテキスト再送 | | 探索結果の生ログをメインに持ち帰る | 以後毎ターンの input 課金が膨らむ | diff --git a/plugins/model-strategy/references/07-codex.md b/plugins/model-strategy/references/07-codex.md new file mode 100644 index 0000000..572af3e --- /dev/null +++ b/plugins/model-strategy/references/07-codex.md @@ -0,0 +1,63 @@ +# Codex CLI (GPT 系モデル) のコスト最適化 + +> **典拠**: developers.openai.com — Codex Models / Codex Pricing / API Pricing / Prompt Caching / Config Reference、github.com/openai/codex（いずれも 2026-07-02 確認）。最新値は https://developers.openai.com/codex/models および https://developers.openai.com/api/docs/pricing を参照すること。 +> +> 本書は `00`〜`04` の原則（高価なモデルは「判断」に、安価なモデルは「作業量」に。単価最適化と量制御は別レバー）を Codex CLI に写像する。原則そのものは環境非依存。 + +## §1 モデルと価格 (per 1M tokens, API 従量課金時) + +| Model | 位置づけ | Input | Cached input | Output | +| --- | --- | --- | --- | --- | +| `gpt-5.5` | 公式推奨デフォルト（最難関・リサーチ） | $5.00 | $0.50 | $30.00 | +| `gpt-5.5` (long context) | 長大コンテキスト時 | $10.00 | $1.00 | $45.00 | +| `gpt-5.4` | プロフェッショナル用途のフラッグシップ | $2.50 | $0.25 | $15.00 | +| `gpt-5.4-mini` | **軽量タスク・サブエージェント用（公式推奨）** | $0.75 | $0.075 | $4.50 | +| `gpt-5.4-nano` | 最安・定型変換 | $0.20 | $0.02 | $1.25 | +| `gpt-5.3-codex-spark` | リアルタイム反復（research preview, Pro 限定） | — | — | — | + +- gpt-5.2 / gpt-5.3-codex / gpt-5.1 系は ChatGPT サインインでは非推奨・段階廃止（API キーでは一部残存） +- **Claude 系との対応**（役割ベースの目安）: gpt-5.5 ≈ Opus/Fable 帯（判断）、gpt-5.4 ≈ Sonnet 帯（実装）、gpt-5.4-mini/nano ≈ Haiku 帯（探索・定型） + +## §2 reasoning effort + +`model_reasoning_effort` = `minimal | low | medium | high | xhigh`（config.toml / `/model` で設定。`xhigh` はモデル依存）。 + +- **デフォルトは全モデル `medium`**（Claude Code の `high`/`xhigh` デフォルトとは異なる。上げ忘れより下げ忘れに注意） +- 使い分けは `01-effort-levels.md` の考え方がそのまま通用する: 設計・監査は `high`〜`xhigh`、日常タスクは `medium`、探索・定型は `low` +- `xhigh` は「難問専用」であってデフォルト格上げ用ではない（レイテンシ非依存の難問のみ） + +## §3 実行体制: Codex での委譲 + +Codex CLI にもマルチエージェント機構がある（`features.multi_agent`、デフォルト有効。`spawn_agent` / `wait_agent`、同時 6 スレッド・ネスト深さ 1）。委譲の鉄則（`02-decision-matrix.md` §3）はそのまま適用する。 + +| 手段 | 用途 | +| --- | --- | +| `agents..config_file` + `description` | 役割別エージェント定義。**安いモデル（gpt-5.4-mini）+ 低 effort の探索役／実装役**を定義しておくのが sonnet-implementer / haiku-scout 相当 | +| `/model`（対話中） | メインのモデル・effort を切替（設定は永続化される） | +| `codex exec -m ` | 非対話の一括処理を安いモデルの別実行に切り出す | +| `--profile `（`$CODEX_HOME/.config.toml`） | 「深い作業用 (gpt-5.5 + high)」「定型用 (gpt-5.4-mini + low)」等のプリセット切替 | + +## §4 サブスクリプション制限 (ChatGPT プラン) + +- Plus / Pro / Business / Enterprise の Codex 利用はプラン内クレジット制。**モデルが安いほど同じクレジットで多くこなせる**（例: 同一プランで gpt-5.4-mini は gpt-5.5 の約 4〜5 倍のタスク量） +- Pro は 5x / 20x ティアで枠が拡大。`gpt-5.3-codex-spark` は Pro 限定 +- API キー認証での従量課金も可能（§1 の単価）。枠を使い切った際の逃がし先になる +- **含意**: 枠温存の構図は Claude サブスクと同じ。「gpt-5.5 は判断だけ、作業量は mini/nano へ」で消費速度を数分の一にできる + +## §5 プロンプトキャッシュ + +- cached input は **通常 input の 10%**（90% off）。自動・無料、明示の cache_control は不要 +- 最小キャッシュ対象プレフィックス **1,024 トークン**、**完全プレフィックス一致** +- TTL: インメモリ 5〜10 分（最長 1h）。gpt-5.x / codex 系は `prompt_cache_retention: "24h"` で 24 時間保持（非 ZDR 組織はデフォルト） +- **含意**: `03-cost-levers.md` のキャッシュ温存規律（安定プレフィックスを先頭に・揮発情報を後ろに・ツール定義を不変に）は Codex でも同様に効く。AGENTS.md やシステム設定が安定プレフィックスを構成する + +## §6 決定マトリックス (Codex 版クイックリファレンス) + +| タスク種別 | モデル | reasoning effort | +| --- | --- | --- | +| アーキテクチャ設計・技術選定・監査 | gpt-5.5 | high〜xhigh | +| 最難関実装・大規模リファクタ | gpt-5.5 / gpt-5.4 | high〜xhigh | +| 仕様確定済みの実装 | gpt-5.4（委譲なら gpt-5.4-mini） | medium | +| コード探索・調査・grep 系 | gpt-5.4-mini | low | +| ドキュメント整形・定型変換 | gpt-5.4-mini / gpt-5.4-nano | minimal〜low | +| リアルタイムの高速反復（Pro） | gpt-5.3-codex-spark | — | diff --git a/plugins/model-strategy/skills/model-effort-guide/SKILL.md b/plugins/model-strategy/skills/model-effort-guide/SKILL.md index a8f624e..3f548fe 100644 --- a/plugins/model-strategy/skills/model-effort-guide/SKILL.md +++ b/plugins/model-strategy/skills/model-effort-guide/SKILL.md @@ -7,10 +7,20 @@ description: "Recommend the cost-optimal Claude model (Fable/Opus/Sonnet/Haiku) 与えられたタスクを分類し、コスト最適なモデル・effort・実行体制(メイン実行 or サブエージェント委譲)を決定して実行する。 +この文書で `PLUGIN_ROOT` と書く場合は、Claude Code では `${CLAUDE_PLUGIN_ROOT}`、Codex ではこの `SKILL.md` の 2 階層上にある `model-strategy` プラグインルートを指す。リファレンスはすべて `PLUGIN_ROOT/references/` 配下。 + ## 0. 原則 **高価なモデルは「判断」に、安価なモデルは「作業量」に使う。** メインセッションは設計・監査・レビュー・最難関実装に専念し、それ以外は委譲する。 +## 0.5 実行環境の判定（最初に 1 回だけ） + +- **Claude Code で実行中**: サブエージェント（`sonnet-implementer` / `haiku-scout` / Explore）への委譲が使える。以降の手順をそのまま適用する。 +- **Codex CLI で実行中**: モデル体系（GPT 系）・価格・reasoning effort・委譲手段が異なるため、判断基準は `references/07-codex.md` を読む。原則（§0）と委譲の鉄則（`02-decision-matrix.md` §3）はそのまま適用し、担当モデルだけ読み替える: + 1. **委譲**: Codex のマルチエージェント（`spawn_agent` / `agents.`）で安いモデル（gpt-5.4-mini 等）+ 低 effort の役割へ出す。使えない場合は `codex exec -m ` の別実行で代替 + 2. **モデル/effort 切替**: 対話中は `/model`、プリセットは `--profile` + 3. 本プラグインの `sonnet-implementer` / `haiku-scout` エージェント定義は Claude Code 専用。Codex では同等の役割を `agents.` に定義して使う + ## 1. 判定フロー 1. タスクを分類する: 設計判断 / 実装 / レビュー / 探索・調査 / 定型作業 / 大量一括処理 @@ -29,10 +39,13 @@ description: "Recommend the cost-optimal Claude model (Fable/Opus/Sonnet/Haiku) | --- | --- | --- | | 設計・技術選定・監査 | メインセッション | high〜xhigh | | 最難関実装・大規模リファクタ | メインセッション | xhigh | +| Fable 5 でしか差が出ない最難関の判断 | メイン (Fable 5) | medium〜high (低 effort でも従来 xhigh 級) | | 仕様確定済みの実装 | sonnet-implementer | (委譲) | | 探索・調査・定型作業 | haiku-scout | (委譲) | | レビューの個別検証 fan-out | Sonnet サブエージェント並列 | (委譲) | +**Fable 5 の使いどころはサブスク提供フェーズで変わる**: 同梱期間(〜2026-07-07・週次上限の 50% キャップ)は最難関タスクへの集中投下、以降は従量クレジット($10/$50)前提のコスト判断。詳細は `00-pricing.md` §4 と `02-decision-matrix.md` §2。 + ## 3. リファレンス | ファイル | 内容 | @@ -44,6 +57,7 @@ description: "Recommend the cost-optimal Claude model (Fable/Opus/Sonnet/Haiku) | `references/04-large-codebase.md` | 大規模コードベースの量制御 (常駐コンテキストを平坦に保つ規定) | | `references/05-repo-index.md` | ナビゲーション索引 (pull 優先: 外部 queryable 索引を第一に、薄い CLAUDE.md 地図はフォールバック) | | `references/06-context-monitor.md` | コンテキスト量を statusLine で可視化する同梱スクリプトと配線手順 | +| `references/07-codex.md` | Codex CLI (GPT 系モデル) の価格・reasoning effort・委譲代替の決定基準 | ## 4. 出力形式(推奨のみ求められた場合) diff --git a/plugins/quality-architect/.claude-plugin/plugin.json b/plugins/quality-architect/.claude-plugin/plugin.json index f6d563d..c20f95a 100644 --- a/plugins/quality-architect/.claude-plugin/plugin.json +++ b/plugins/quality-architect/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "quality-architect", - "version": "0.1.3", + "version": "0.1.4", "description": "Design and review software architecture against the ISO/IEC 25010:2023 product quality model (9 characteristics, 40 subcharacteristics). Provides two skills (quality-architecture / quality-review) backed by a per-characteristic reference library with verified academic and official citations.", "author": { "name": "9uiLe" diff --git a/plugins/quality-architect/.codex-plugin/plugin.json b/plugins/quality-architect/.codex-plugin/plugin.json index 640f468..8d12ac5 100644 --- a/plugins/quality-architect/.codex-plugin/plugin.json +++ b/plugins/quality-architect/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "quality-architect", - "version": "0.1.3", + "version": "0.1.4", "description": "Design and review software architecture against the ISO/IEC 25010:2023 product quality model.", "author": { "name": "9uiLe", diff --git a/plugins/quality-architect/README.md b/plugins/quality-architect/README.md index 4529d73..3a899ce 100644 --- a/plugins/quality-architect/README.md +++ b/plugins/quality-architect/README.md @@ -50,7 +50,7 @@ references/ ├── 05-reliability.md 信頼性 ├── 06-security.md セキュリティ ├── 07-maintainability.md 保守性 -├── 07a-coupling-deep-dive.md 結合の深掘り補論（Khononov 2024 — Integration Strength × Distance × Volatility / Connascence / BALANCE） +├── 07a-coupling-deep-dive.md 結合の深掘り補論（Khononov 2024 — Integration Strength × Distance × Volatility / BALANCE / §6.3.1 削減アクション・カタログ） ├── 08-flexibility.md 柔軟性（旧: 移植性） ├── 09-safety.md 安全性（2023 で新設） └── static-evaluation.md 静的評価レイヤーの方法論 diff --git a/plugins/quality-architect/references/07a-coupling-deep-dive.md b/plugins/quality-architect/references/07a-coupling-deep-dive.md index e03481f..27814b6 100644 --- a/plugins/quality-architect/references/07a-coupling-deep-dive.md +++ b/plugins/quality-architect/references/07a-coupling-deep-dive.md @@ -193,6 +193,26 @@ canonical はこの区別を反映する（`COMPLEXITY = NOT MODULARITY` が総 - **Volatility を下げる**: 安定化（API を凍結する、変更頻度の高い部分を抽出する）。 - BALANCE = TRUE になるまで、3 次元のうち最も改修コストの低い軸から調整する。 +#### §6.3.1 削減アクション・カタログ（運用補助・本リポジトリ合成） + +> 位置づけ: §6.3 の 3 軸（Khononov 2024, Ch.11）を「指摘に添える具体的アクション」へ運用化した **本リポジトリ独自の catalog** である（§6.5 と同じく Khononov 2024 の verbatim ではない。出典として引用する場合は 3 軸の考え方のみ Ch.11 に帰属させること）。**severity・PASS/FAIL 判定には一切影響しない**（H9: 本 catalog は推奨の内容であって判定入力ではない）。 + +| 検出状況（例） | 下げる軸 | 具体的アクション例 | +| --- | --- | --- | +| Intrusive Coupling（内部実装への依存、リフレクション、private 相当への到達） | Strength | 依存先の公開 API / 明示コントラクトのみを使うよう書き換え。必要な機能が公開されていなければ依存先に API 追加を提案（Intrusive → Functional 以下へ） | +| Functional Coupling（業務ロジック・業務シーケンスの境界跨ぎ共有、cross-boundary duplicates） | Strength または Distance | 重複ロジックをどちらか一方の境界へ集約し他方はコントラクト経由で呼ぶ。または 2 部品を同一境界内へ移設（Distance 短縮） | +| Model Coupling（ドメインモデル型の境界跨ぎ共有） | Strength | 境界専用の DTO / integration-specific model を導入し、内部モデルを非公開化（Model → Contract） | +| 大域的複雑性（強 Strength × 遠 Distance、§6.1 `S AND D`） | どちらか一方 | XOR を成立させる: 強く結合したままなら同一境界へ寄せる（Distance↓）、遠いまま保つなら Contract 化（Strength↓）。両方同時に着手しない（改修コストの低い軸から） | +| 局所的複雑性（弱 Strength × 近 Distance の部品が過剰分割で散在、§6.1 `NOT S AND NOT D`） | Distance（構成整理） | 過剰分割を統合し境界数を減らす。§6.4 の通り「さらに疎結合化」は逆効果（distributed monolith） | +| 高 Volatility の結合先（Core サブドメイン等）への強依存 | Volatility（隔離） | 変更頻度の高い部分を安定インターフェースの背後に抽出・隔離（accidental volatility のみ削減対象。essential は設計では消えない、§5.2） | + +**アクション提示の書式**（指摘・設計成果物に添える 1〜2 行）: + +``` +削減アクション: <軸: Strength|Distance|Volatility>を下げる — <上表から選んだ具体的手順>（Khononov 2024, Ch.11） +期待効果: BALANCE = (STRENGTH XOR DISTANCE) OR NOT VOLATILITY が +``` + ### §6.4 「Decouple everything は誤り」原則 Khononov 2024 は「decouple everything」アプローチを **明示的に否定** する。過剰な疎結合は distributed monolith を生み、Distance だけが伸びて Strength が下がらない反パターンとなる（出典: coupling.dev/posts/core-concepts/balance/）。 @@ -467,7 +487,7 @@ Khononov 2024 は古典理論を Ch.5 と Ch.6 で取り込み直しており、 - [ ] **Strength 段を1つ選び、共有要素を併記したか**: 境界ごとに目標 Integration Strength 段（Intrusive/Functional/Model/Contract）を選び、`(type: ...) / (contract: ...) / (symbol: ...)` を直近に併記したか（H3）。未併記なら `推測` ラベルに格下げ。 - [ ] **Distance を見積ったか**: 境界の Distance 段（Methods〜Systems）を見積り、変更コスト比例／ライフサイクル結合反比例の含意（§4.2）を踏まえたか。 - [ ] **Volatility を essential/accidental で分けたか**: 結合先の変更圧力を見積り、設計で減らす対象を accidental に限定したか（§5.2）。 -- [ ] **三重苦を避けたか**: 強 Strength × 遠 Distance × 高 Volatility が同時に成立する境界を作っていないか（§6.1 大域的複雑性 + 高 Volatility）。該当すれば §6.3 のどの軸で rebalance するか明記。 +- [ ] **三重苦を避けたか**: 強 Strength × 遠 Distance × 高 Volatility が同時に成立する境界を作っていないか（§6.1 大域的複雑性 + 高 Volatility）。該当すれば §6.3.1 の削減アクション書式（下げる軸 + 具体的手順 + 期待効果）で明記。 - [ ] **XOR を成立させたか**: 各境界で `STRENGTH XOR DISTANCE`（強なら近く / 遠いなら弱く）か、または低 Volatility による緩和（`OR NOT VOLATILITY`）を説明できるか（§6.1）。 - [ ] **decouple everything になっていないか**: 過剰な疎結合で distributed monolith を招いていないか（§6.4）。 - [ ] **canonical 表現を併記したか**: 「pain / balance」表現に canonical `BALANCE = (STRENGTH XOR DISTANCE) OR NOT VOLATILITY` を併記したか（H10）。`Pain = S × D × V` 単独引用や精密メトリクス化をしていないか（H2）。 diff --git a/plugins/quality-architect/skills/quality-architecture/SKILL.md b/plugins/quality-architect/skills/quality-architecture/SKILL.md index 5752f53..b49c12d 100644 --- a/plugins/quality-architect/skills/quality-architecture/SKILL.md +++ b/plugins/quality-architect/skills/quality-architecture/SKILL.md @@ -96,6 +96,7 @@ description: "Design NEW or PROPOSED architecture using the ISO/IEC 25010:2023 p **章 4'（モジュール境界と結合バランス）の書き方**（境界を新規定義する設計の場合のみ出力）: - 境界をまたぐ依存ごとに、評価レベル（`module_unit:`）・目標 Integration Strength 段（共有要素併記）・Distance 段・Volatility 見積りを表で示し、`BALANCE = (STRENGTH XOR DISTANCE) OR NOT VOLATILITY`（07a §6.1 canonical）で評価する。 - 数値・段は `（参考値: Khononov 2024, Ch.）` ラベル付き（実測判定にしない・§3.5）。 +- **BALANCE = FALSE の境界（特に強 Strength × 遠 Distance の大域的複雑性）には、07a §6.3.1 の削減アクション書式（下げる軸 + 具体的手順 + 期待効果）を必ず添える**。低 Volatility による許容（`OR NOT VOLATILITY`）で残す場合はその根拠を 1 行書く。 - 末尾に 07a §11.2 の設計時結合チェックリストを貼り、各項目の充足を示す。 - 詳細手順と禁則は `07a §11`（§11.1 ヒューリスティクス / §11.2 チェックリスト / §11.3 §6.5 との混同禁止）に従う。 @@ -133,5 +134,5 @@ description: "Design NEW or PROPOSED architecture using the ISO/IEC 25010:2023 p - ❌ 過剰設計：要求にない品質特性のための仕組みを足し込まない。 - ❌ 既存コード／差分／PR のレビュー依頼を本スキルで処理する（→ `quality-review` にハンドオフ。§0 参照）。 - ❌ 対象コードに対する判定値として数値しきい値を引用する（V(G) ≤ 10, カバレッジ ≥ 0.70 等）。設計時は `（参考値: ...）` ラベル必須。実測値が必要なら `quality-review` に切り替える。 -- ⚠️ **Khononov の `Pain = Strength × Distance × Volatility` を「精密メトリクス」として本文に書く**。同式は書籍本文 verbatim（Ch.10 §10.2.1, 邦訳 p.182「メンテナンスの労力 ＝ 強度 ＊ 距離 ＊ 変動性」）だが、書籍自身が 2 値スケール前提（高=1/低=0）+「正確な科学ではない」警告（§10.3, p.184）を付している。引用時はこの 2 留保を必ず併記し、連続値の精密指標として提示しない。canonical 第一表現は `references/07a-coupling-deep-dive.md` §6.1 の `BALANCE = (STRENGTH XOR DISTANCE) OR NOT VOLATILITY`（こちらも書籍 verbatim）（07a §9 H2 規律）。 -- ❌ **Robert C. Martin の Instability `I = Ce / (Ce + Ca)` を Khononov Integration Strength の代理として引用する**。Khononov 2024 は依存をカウントするアプローチを名指しで否定している（07a §9 H2 規律）。 +- ❌ BALANCE = FALSE（特に強 Strength × 遠 Distance の大域的複雑性）と評価した境界を、削減アクション（07a §6.3.1 の書式）を添えずに提案に残す。 +- ⚠️ **Khononov（07a）を引用する前に、`references/07a-coupling-deep-dive.md` §9（H1〜H10 禁則）を必ず Read し従う**。同節がカノン。代表例: Pain 式 `Pain = S × D × V` を 2 留保なしに精密メトリクス化しない（H2/H10。canonical 第一表現は §6.1 の BALANCE 論理式）／Martin の Instability を Integration Strength の代理にしない（H2）。 diff --git a/plugins/quality-architect/skills/quality-review/SKILL.md b/plugins/quality-architect/skills/quality-review/SKILL.md index 8badc5d..a9f0696 100644 --- a/plugins/quality-architect/skills/quality-review/SKILL.md +++ b/plugins/quality-architect/skills/quality-review/SKILL.md @@ -99,6 +99,7 @@ LLM の判断は数値化できない残余（考察パート）に閉じ込め - **重大度**: Critical / High / Medium / Low - **箇所**: `path:line` - **問題**と**推奨**（具体的な修正方針） + - **削減アクション**（結合・凝集・複雑度・モジュール境界に関する指摘では**必須**）: `$PLUGIN_ROOT/references/07a-coupling-deep-dive.md` §6.3.1 の catalog から「下げる軸（Strength / Distance / Volatility）」と具体的手順を選び、同節の書式で 1〜2 行併記する。**アクションの有無・内容は severity / verdict に影響しない**（H9 と直交。推奨の中身を具体化するだけ） - **根拠リファレンス**（`0N-*.md` の学術/公式文献を引用） - **design-level の指摘が支配的で、局所修正では解消しない**と判断したら、step 2.5 の前方ハンドオフ（置換アーキの設計は `quality-architecture`）を報告に明記する。 @@ -156,6 +157,7 @@ LLM の判断は数値化できない残余（考察パート）に閉じ込め - 箇所: path:line - 問題: … - 推奨: … +- 削減アクション: （結合・複雑性指摘のみ必須）<軸>を下げる — <具体的手順>（07a §6.3.1 の書式。期待効果 1 文を添える） - 根拠: （ISO/IEC 25010; OWASP ASVS など） - 数値根拠: 決定論パートの行（例: `循環的複雑度(最大)` 行、measured=23）／無ければ「数値根拠なし(推測)」と明記 - （任意）07a 補足: 結合の深掘り (07a) シグナルが attach されている場合のみ。例: `Khononov Distance: cross-service (推測; module_unit=spm-target, --since=6.months)` — 重大度の **下方修正のみ** 可（07a §9 H9）。 @@ -208,6 +210,5 @@ LLM の判断は数値化できない残余（考察パート）に閉じ込め - ❌ §1 step 3 のユーザー確認（決定論パート実行方針の確認）を行わずに静的解析ツールを実行する／LLM 単独レビューを書く。 - ❌ 本文や指摘で数値しきい値（V(G) ≤ 10, カバレッジ ≥ 0.70 等）を引用したのに、§2 決定論パート表に対応行（measured 値または skipped）が存在しない。 - ❌ 全行 skipped の決定論パート表を出しながら、サマリで `inconclusive` を宣言せずに重大度付き指摘を断定的に書く。 -- ⚠️ **Khononov の `Pain = Strength × Distance × Volatility` を「精密メトリクス」として本文に書く**。同式は書籍本文 verbatim（Ch.10 §10.2.1, 邦訳 p.182「メンテナンスの労力 ＝ 強度 ＊ 距離 ＊ 変動性」）だが、書籍自身が 2 値スケール前提（高=1/低=0）+「正確な科学ではない」警告（§10.3, p.184）を付している。引用時はこの 2 留保を必ず併記し、連続値の精密指標として提示しない。canonical 第一表現は `references/07a-coupling-deep-dive.md` §6.1 の `BALANCE = (STRENGTH XOR DISTANCE) OR NOT VOLATILITY`（こちらも書籍 verbatim）（07a §9 H2 規律）。 -- ❌ **Robert C. Martin の Instability `I = Ce / (Ce + Ca)` を Khononov Integration Strength の代理として引用する**。Khononov 2024 は依存をカウントするアプローチを名指しで否定している（07a §9 H2 規律）。 -- ❌ **Khononov 由来の指摘で `07-maintainability.md` / `08-flexibility.md` の既存しきい値・PASS/FAIL 判定を上書きする**。補論が寄与できるのは **重大度の下方修正 (downgrade) のみ**（07a §9 H9 規律）。verdict 反転や severity 上方修正は禁則。 +- ❌ 結合・凝集・複雑度・モジュール境界に関する指摘を、削減アクション（07a §6.3.1: どの軸をどう下げるか + 期待効果）を添えずに問題指摘だけで終える。 +- ⚠️ **Khononov（07a）を引用する指摘を書く前に、`references/07a-coupling-deep-dive.md` §9（H1〜H10 禁則）を必ず Read し従う**。同節がカノン。代表例: Pain 式 `Pain = S × D × V` を 2 留保なしに精密メトリクス化しない（H2/H10。canonical 第一表現は §6.1 の BALANCE 論理式）／Martin の Instability を Integration Strength の代理にしない（H2）／07a シグナルで既存しきい値の verdict 反転・severity 上方修正をしない（H9: 下方修正のみ）。