Quality architecture

quality-architecture — ISO/IEC 25010 でアーキテクチャを設計・評価する

このスキルは ISO/IEC 25010:2023 製品品質モデル（9 特性・40 副特性）を共通言語として、 要件から品質特性を優先付けし、各特性の設計タクティクスでアーキテクチャを構築・評価する。 すべての設計判断・推奨には、リファレンス・ライブラリ中の学術論文／公式文書を引用する。

リファレンス・ライブラリ: プラグインルート相対の references/ （索引は 00-overview.md、各特性は 01〜09、静的評価方法論は static-evaluation.md）

この文書で PLUGIN_ROOT と書く場合は、Claude Code では ${CLAUDE_PLUGIN_ROOT}、Codex ではこの SKILL.md の 2 階層上にある quality-architect プラグインルートを指す。

スキル選択と決定論ファースト原則は 00-overview.md §5.1（プラグイン共通の絶対規律） がカノン。本ファイルの §0 と §3.5 はその反映であり、矛盾があれば §5.1 を優先する。

---

0. このスキルを使ってよいかの判定（必須・最初に実行）

このスキルは 新規／提案中のアーキテクチャ設計 専用である。既存コード／差分／PR／実装のレビューは姉妹スキル quality-review の領域で、決定論ファーストの静的解析手順がそこにのみ定義されている。

よくある誤選択の予防: 「レビューでもまず設計の妥当性を見るべきだから architecture では？」という直感は誤り。既存コードの設計が妥当かを評価する『設計レビュー』も quality-review の責務（同スキル §1 step 2「設計妥当性」）。判別軸は「設計を見るか否か」ではなく 「対象が既に在るか否か」。ただし review が「設計そのものを作り直すべき」と結論し、ユーザが置換アーキの新規設計を望む場合は、本スキルへの前方ハンドオフが正当（§0.1 がブロックするのは“既存コードのレビューを本スキルで処理する”後方向のみ）。

0.1 客観条件（最優先・LLM の主観判断より上位）

次の いずれか に当てはまる場合、本スキルでは出力しない。ユーザに 1 行で通知してから quality-review への切替を提案する:

• ユーザが入力として git diff の差分、特定 PR 番号／URL、既存ファイルパス、既存ディレクトリ、リポジトリ全体のいずれかを 対象として与えている。
• 対象リポジトリに quality-gate-result.json（CI 出力）が存在する。

通知テンプレ:

「対象として既存コードが指定されているため、quality-review スキルでの実行を推奨します。quality-review は静的解析を先に走らせる決定論パートを持ち、再現性が高い結果が出ます。quality-review で進めますか、それともこのまま設計議論として続けますか？」

0.2 補助シグナル（参考・単独ではハンドオフ発火しない）

対象リポジトリに次のファイルがある場合、上記 0.1 と組み合わせて「レビュー領域」を示す補助信号として扱う。これらが存在するだけでは設計タスクを止めない（brownfield の設計依頼を妨げない）:

• .swiftlint.yml / .swift-format / .periphery.yml / Mintfile
• .github/workflows/*quality*.y*ml / scripts/quality-gate-*.sh

これらが存在し、かつユーザ依頼に「レビュー／評価／指摘／監査／見て」が含まれる場合は 0.1 と同じくハンドオフを提案する。

0.3 設計タスクが確定した場合の数値の扱い

本スキルに留まる場合、対象コードに対する 実測数値 を本文に書いてはならない（V(G)・カバレッジ・CBO・LCOM・CVE 件数 など）。文献値を引用するときは必ず （参考値: McCabe 1976） のように 「参考値」と明示 し、対象コードへの判定として書かない。実測判定が必要になった瞬間、それは review 領域であり quality-review に切り替える。詳細は §3.5。

---

1. 進め方（必ずこの順番で）

1. 対象とスコープの確認

   • 設計対象（新規 / 既存改修 / 特定サブシステム）、制約（技術スタック・規制・SLA）、版（2011 版 か 2023 版 か。安全性が要求に絡むなら 2023 版の Safety も併用）を確認する。
   • 既にユーザーが情報を提供していれば二重に質問しない。

2. 品質特性の優先付け（最重要）

   • 9 特性すべてを同等に扱わない。要件・ビジネス文脈から 重点特性を 2〜4 個に絞り、トレードオフ関係を明示する。
   • 優先付けは推測で決めず、不明なら 1 メッセージにまとめて確認する（例: 「可用性とコスト、どちらを優先しますか」）。
   • 代表的トレードオフ: セキュリティ⇄使用性、性能効率性⇄保守性、可用性⇄一貫性(CAP)、移植性⇄性能最適化。

3. 特性ごとのタクティクス導出

   • 優先した各特性について、対応する $PLUGIN_ROOT/references/0N-*.md を実際に Read し、「設計タクティクス/パターン」節から候補を選ぶ。
   • 副特性レベルまで降りる（例: 信頼性 → 障害許容性なら Circuit Breaker / Bulkhead / リトライ+バックオフ）。
   • モジュール／サービス境界を新規に定義する設計の場合は、$PLUGIN_ROOT/references/07a-coupling-deep-dive.md §11（設計時の結合検討）を Read し、境界をまたぐ依存ごとに結合バランスを 定性的に 評価する（§11.1 ヒューリスティクス → §11.2 チェックリスト）。設計時なので実測値は書かず、結合 3 次元（Integration Strength × Distance × Volatility）への言及は （参考値: Khononov 2024, Ch.<n>） ラベルで扱う（§3.5）。SIGNAL ベースの §6.5 hint table は レビュー時専用 なので設計時には使わない（07a §11.3）。

4. トレードオフ分析（ATAM 的に）

   • 候補アーキテクチャを 1〜複数案出し、各案を重点特性の軸で評価する。
   • 感度ポイント（その決定が特定特性を大きく左右する箇所）とトレードオフポイント（複数特性が競合する箇所）を明示する。
   • 比較は表で示し、推奨案を 1 つ明確にする。

5. 成果物の生成

   • アーキテクチャ提案を文章＋図（必要なら Mermaid）で出力する。各設計判断に 根拠リファレンスを併記する。
   • 未決事項（Open Questions）と、検証方法（負荷試験・脅威モデリング等、どの特性をどう測るか）を添える。

6. 報告

   • 重点特性、採用案と理由、主要トレードオフ、未決事項を簡潔に要約する。

---

2. 出力の章立て（目安）

1. コンテキストと制約
2. 品質特性の優先付け（重点特性と根拠、トレードオフ）
3. アーキテクチャ提案（案ごとの構成・図）
4. 特性別の設計タクティクス（副特性 → 採用タクティクス → 根拠リファレンス）
4'. モジュール境界と結合バランス（07a §11）  ← 境界を新規定義する設計の場合のみ
5. トレードオフ分析（感度/トレードオフポイント、比較表、推奨）
6. 検証計画（各特性の測定・評価方法）
7. Open Questions
8. References（本文で引用したものを集約）

章 4'（モジュール境界と結合バランス）の書き方（境界を新規定義する設計の場合のみ出力）:

• 境界をまたぐ依存ごとに、評価レベル（module_unit:）・目標 Integration Strength 段（共有要素併記）・Distance 段・Volatility 見積りを表で示し、BALANCE = (STRENGTH XOR DISTANCE) OR NOT VOLATILITY（07a §6.1 canonical）で評価する。
• 数値・段は （参考値: Khononov 2024, Ch.<n>） ラベル付き（実測判定にしない・§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 との混同禁止）に従う。

---

3. リファレンス引用のルール（厳守）

• 推奨・タクティクスには 必ず出典を併記する。出典は 0N-*.md の「リファレンス」節に載っている学術論文・公式文書のみ。
• ブログ・QA サイト・出典不明の主張を根拠にしない。
• 引用形式は本文中で「（McCabe 1976）」「（ISO/IEC 25010）」のように示し、末尾 References に完全な書誌を集約する。
• リファレンスに無い主張を新たにする場合は、推測である旨を明示する（断定しない）。
• モジュール境界決定でモジュール内結合特性（Khononov Integration Strength × Distance × Volatility）を引用する場合は、補論 references/07a-coupling-deep-dive.md を （参考値: Khononov 2024, Ch.<n>） 形式で引く。設計時の検討手順・チェックリストは 07a §11（設計時の結合検討） が入口（§1 step 3 / §2 章 4'）。07a §10 References と §9 H7 規律に従う（学術・公式のみ、coupling.dev / connascence.io は定義参照のみ可）。

---

3.5 数値しきい値の引用規律（厳守）

本スキルは設計時用のため、対象コードに対する 実測値を本文に書かない。文献値や規格値を引用する場合は次のルールに従う。

• ✅ （参考値: V(G) ≤ 10, McCabe 1976）、（参考値: 分岐カバレッジ ≥ 0.80, ISO/IEC 25023） のように 「参考値」と明示 して使う（要件・SLA・設計目標を議論するため）。
• ❌ この実装は V(G) ≤ 10 を満たすべき (McCabe 1976) のように 対象コードへの判定 として書く。これは review 領域であり、quality-review に切り替える。
• ❌ おそらく V(G) は 15 程度 のように 推測した実測値を断定 する。
• 実測判定が必要になった瞬間 → §0 のルーティングに戻り quality-review に移譲する。

---

4. やってはいけないこと

• ❌ 9 特性を機械的に全部並べただけで優先付けしない（重点を絞る）。
• ❌ トレードオフを示さずに「すべて満たせる」と書く。
• ❌ 根拠リファレンス無しでパターン名だけ列挙する。
• ❌ 版（2011/2023）を曖昧にしたまま Safety の扱いを省略する。
• ❌ 過剰設計：要求にない品質特性のための仕組みを足し込まない。
• ❌ 既存コード／差分／PR のレビュー依頼を本スキルで処理する（→ quality-review にハンドオフ。§0 参照）。
• ❌ 対象コードに対する判定値として数値しきい値を引用する（V(G) ≤ 10, カバレッジ ≥ 0.70 等）。設計時は （参考値: ...） ラベル必須。実測値が必要なら quality-review に切り替える。
• ❌ 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）。