design-invariants

Design Invariants Skill

設計提案または差分を、Exarchos 固有のアーキテクチャ不変条件に照らして監査します。プロジェクトスコープの不変条件であり、Exarchos プラグインの利用者には適用されません。

このスキルは、Issue #1118（原則の明文化）および #1109（横断的な制約）を実務に適用するものです。参照コンテンツは、v2.11.0 の #1275（MCP Resources）サーフェスと、 #1260 の機械可読な不変条件ジェネレーターを支える候補でもあります。各不変条件には、安定した ID と構造化された形式が付与されています。

使用する場面

• /exarchos:ideate または /exarchos:plan の実行中、設計を確定する前。
• /exarchos:review の実行中、/axiom:audit と併せて。
• イベントストア、MCP サーフェス、ランタイム YAML、または複合ツールレジストリに関わる PR をレビューするとき。

使用しない場面

• 一般的なバックエンド品質の確認には使用しません。/axiom:* スキルを使用してください（以下の補完関係マトリクスを参照）。
• TDD / 仕様への準拠確認には使用しません。/exarchos:review または spec-review スキルを使用してください。
• 文章表現や AI が書いたような箇所の確認には使用しません。/axiom:humanize を使用してください。

呼び出し方法

1. レビュー対象の成果物（設計ファイルのパス、差分の範囲、または PR の URL）を指定します。
2. INV-1..INV-5 を順番に確認し、各不変条件について HIGH / MEDIUM / LOW の指摘を記録します。
3. INV-5 では、4 つのサブ領域すべて（5a 入力の使いやすさ、5b 出力コントラクト、5c Aspire の動詞、5d アクション識別子）を確認します。
4. 重複する公理の指摘があれば相互リンクします（例：INV-1 のトポロジーに関する問題は、DIM-1 にも該当する場合があります）。
5. axiom と同じ指摘形式（重大度 + 次元 + ファイル:行 + 説明 + required_fix）で出力します。

不変条件の参照先

• INV-1 → references/INV-1-event-sourcing.md
• INV-2 → references/INV-2-facade-equivalence.md
• INV-3 → references/INV-3-basileus-forward.md
• INV-4 → references/INV-4-platform-agnosticity.md
• INV-5a → references/INV-5a-input-ergonomics.md
• INV-5b → references/INV-5b-output-contract.md
• INV-5c → references/INV-5c-aspire-verbs.md
• INV-5d → references/INV-5d-action-discriminator.md
• 決定論的チェック → references/deterministic-checks.md

指摘形式

レビュー担当者が文脈を切り替えずに済むよう、axiom と同じ用語（HIGH / MEDIUM / LOW）を使用します。

{
  "verdict": "pass | conditional | fail",
  "findings": [
    {
      "invariant": "INV-1",
      "severity": "HIGH",
      "file": "servers/exarchos-mcp/src/projections/foo.ts",
      "line": 42,
      "description": "Reducer mutates state in place inside the apply switch",
      "required_fix": "Return a new state object via spread; deep-freeze input via assertReducerImmutable in tests",
      "axiom_overlap": "DIM-1"
    }
  ]
}

axiom との組み合わせ — 相補性マトリクス

境界は次のとおりです。axiom が「このコードは適切に設計されているか？」と問うのに対し、このスキルは「この設計は Exarchos の重要な不変条件を守っているか？」と問います。設計が axiom の基準を満たしていても、イベントソーシングの整合性に違反することがあります（イベントを出力せずに状態を直接変更する、型が完全に正しいハンドラーなど）。

検出事項	Axiom の次元	設計上の不変条件
劣化した EventStore を作成する遅延フォールバック	DIM-1 トポロジー	INV-1（イベント整合性の暗黙的な喪失）
skills-src にハードコードされた Skill({...})	—	INV-4
projection の適用時に console.log のみを行う catch	DIM-2 可観測性	INV-1（fold が例外をスロー → reducer-throw 劣化パスを必ず実行）
MCP に同等のものがない新しい CLI 動詞	—	INV-2
projection 状態用の、アダプター内の可変キャッシュ	DIM-1 トポロジー	INV-1 + INV-2（TaskStore をサイドデータベースとして使うアンチパターン）
実行時に読み取られる runtimes/claude.yaml のフィールド	—	INV-3
「使用しないでください」のガイダンスがないツールの説明	—	INV-5a
next_actions を含まない成功時の ToolResult	—	INV-5b
v2.11.0 以降で NDJSON を使用する長時間実行オペレーション	—	INV-5b（Tasks SEP-1686 を使用すべき）
exarchos_workflow に対するアクションにすべき、新しいトップレベルツール	—	INV-5d
削除されたのに依然として読み取られるスキーマフィールド	DIM-3 コントラクト	イベントフィールドの場合は INV-1

このスキルが axiom の担当領域とし、対象外とする懸念事項：

懸念事項	担当
一般的な SOLID、結合度、依存関係の方向（DIM-6）	axiom:critique
一般的なエラー処理、暗黙的なフォールバック（DIM-2、DIM-7）	axiom:harden
一般的なスキーマと実行時の乖離、型アサーションの安全性（DIM-3）	axiom:scan、axiom:critique
一般的なテストの忠実性、モックの過剰使用（DIM-4）	axiom:verify
一般的なデッドコード、形骸化したパターン（DIM-5）	axiom:distill
AI が書いた文章に見える特徴（DIM-8）	axiom:humanize

ソース

調査レポート：docs/research/2026-05-07-design-invariants-skill.md。#1118 に基づく原則ドキュメントが docs/architecture/principles.md に反映されたら、このスキルを改訂してください。このスキルは原則を再記述するものではなく、そのドキュメントを運用に適用するものになります。