--- name: quality-architecture description: "Design NEW or PROPOSED architecture using the ISO/IEC 25010:2023 product quality model: prioritize quality attributes from requirements, compare design options, define non-functional requirements, or run ATAM-style trade-off analysis. Japanese triggers: 「アーキテクチャを設計して」「非機能要件を洗い出して」「ATAM でトレードオフ分析して」「設計案を比較して」. For reviewing EXISTING code, a diff, a PR, or a repository — INCLUDING assessing whether the existing design itself is sound (design review) — use `quality-review` instead. This skill is for design that does not yet exist; review of an existing design is `quality-review`'s job." --- # 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.）` ラベルで扱う（§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.）` ラベル付き（実測判定にしない・§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.）` 形式で引く**。設計時の検討手順・チェックリストは **`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）。