アーキテクチャコンパイラ: アーキテクチャレベルAIハーネス

言語: English | 简体中文

注: 英語ドキュメントが正規の情報源です。翻訳に差異がある場合は英語版に従ってください。

ArchCompilerは制約と非機能要件（NFR）を、明確なトレードオフとコスト影響を伴う、明示的でレビュー可能なアーキテクチャ決定にコンパイルします。

これは3つの部分から構成されるアーキテクチャレベルAIハーネスです: 決定論的コンパイラ、キュレーションされたパターンレジストリ、エージェント向けワークフロースキル。これらが連携して要件をコンパイルされたアーキテクチャに変換し、アーキテクチャ決定が変更された場合に承認と再承認のルートを通し、明示的なアーキテクチャ契約に基づいて実装を導きます。

コンパイラ自体は意図的にシンプルに設計されています: LLM推論なし、隠れたデフォルトなし、ブラックボックス選択ロジックなし。アーキテクチャの知能はレジストリと、以下のワークフローディシプリンにあります:

using-arch-compiler
compiling-architecture
implementing-architecture

タグ: architecture-as-code, architecture-harness, agent-harness, deterministic-compiler, pattern-registry, nfr-enforcement, ai-governance

コア哲学

パターンが知識ベースです。 すべてのアーキテクチャロジックは patterns/ 以下のパターンファイルにあります。コンパイラは意図的にシンプルです。
インクルードベースのフィルタリング。 パターンは supports_constraints と supports_nfr ルールを介して、どのスペック条件をサポートするかを宣言します。パターンのすべてのルールがスペックと一致した場合に選択されます。
スキーマファースト。 schemas/canonical-schema.yaml がスペック契約を定義し、schemas/pattern-schema.yaml がパターン契約を定義します。両方が情報源です。

クイックスタート

システムで python が利用できない場合は、以下のコマンドで python3 に置き換えてください。

# 必要に応じてpipxをインストール（Python CLIアプリに推奨）
brew install pipx

# 現在のリポジトリからCLIをインストール
pipx install .

# 実際のサンプルスペックをコンパイル（標準出力に出力）
archcompiler tests/fixtures/no-advisory-success.yaml

# コンパイルして成果物をディレクトリに書き込み
archcompiler tests/fixtures/no-advisory-success.yaml -o compiled_output/

# 詳細モード — インラインパターンコメント + rejected-patternsファイル
archcompiler tests/fixtures/no-advisory-success.yaml -v
archcompiler tests/fixtures/no-advisory-success.yaml -o compiled_output/ -v

# 出力ファイル名にUTCタイムスタンプを追加
archcompiler tests/fixtures/no-advisory-success.yaml -o compiled_output/ -v -t

開発環境のセットアップ

# 仮想環境を作成して有効化
python3 -m venv .venv
source .venv/bin/activate

# ローカル開発用にリポジトリ依存関係をインストール
python -m pip install -r tools/requirements.txt
python -m pip install -e .

# ソースツリーからコンパイラを実行
python tools/archcompiler.py tests/fixtures/no-advisory-success.yaml

開発コマンドは arch-compiler/ リポジトリルートから実行してください。一部のテストは tools/archcompiler.py をカレントワーキングディレクトリからの相対パスで呼び出すため、親ディレクトリから実行すると失敗します。

エージェントスキルのインストール

このリポジトリにはインストール可能なエージェントスキルも含まれています。

Codex

Codexに以下のように指示します:

https://raw.githubusercontent.com/inetgas/arch-compiler/refs/heads/main/.codex/INSTALL.md から指示を取得して従ってください。

またはネイティブインストール手順を直接実行:

git clone https://github.com/inetgas/arch-compiler.git ~/.codex/arch-compiler
mkdir -p ~/.agents/skills
ln -s ~/.codex/arch-compiler/skills ~/.agents/skills/arch-compiler

インストール後、Codexを再起動してください。

重要: スキルファイルだけでは不十分です。ワークフローはリポジトリ全体が安定したローカルパスで利用可能であることに依存しており、エージェントは再クローンや /tmp/ への依存なしにコンパイラ、パターンレジストリ、スキーマ、アダプタにアクセスできます。

または、公開リポジトリから3つのスキルを直接インストール:

python3 ~/.codex/skills/.system/skill-installer/scripts/install-skill-from-github.py \
  --repo inetgas/arch-compiler \
  --path skills/using-arch-compiler skills/compiling-architecture skills/implementing-architecture

Codexインストーラの注意: このリポジトリから複数のスキルをインストールする場合、すべてのスキルパスを単一の --path 引数の後に渡してください。--path は繰り返さないでください。現在のインストーラでは最後に繰り返された値のみが保持されます。

インストール後、3つのディレクトリが存在することを確認:

ls ~/.codex/skills | rg 'using-arch-compiler|compiling-architecture|implementing-architecture'

スキルエントリポイント

skills/using-arch-compiler = 正しいワークフローを選択し、アーキテクチャが変更された場合にコンパイルに戻る
skills/compiling-architecture = アーキテクチャをコンパイルして確定する
skills/implementing-architecture = 承認されたアーキテクチャを実装する

エージェントワークフロープリフライト

アプリ向けのアーキテクチャコンパイルまたは実装ワークフローの前に、共有のプリフライトヘルパーを実行してください。これはワークフローがCodex、Claude Code、または他のエージェントラッパーによって駆動されているかどうかにかかわらず適用されます。

# CLIとしてパッケージをインストールした場合:
archcompiler-preflight --app-repo /path/to/app-repo --mode compile

# または、安定したローカルリポジトリパスからヘルパーを直接実行:
python3 ~/.codex/arch-compiler/tools/archcompiler_preflight.py --app-repo /path/to/app-repo --mode compile
python3 ~/.claude/arch-compiler/tools/archcompiler_preflight.py --app-repo /path/to/app-repo --mode compile

ワークフローが承認された docs/architecture/ フォルダからコードを書き込もうとしている場合は --mode implement を使用します。

Claude Code

Claude CodeはCodexのネイティブスキルディスカバリを使用しませんが、このリポジトリには adapters/claude-code/commands/ にすぐにコピーして使えるコマンドアダプタ（ルーターエントリポイントを含む）が含まれています。

セッション間でコンパイラ、パターン、スキーマに一貫してアクセスできるよう、リポジトリ全体を ~/.claude/arch-compiler のような安定したローカルパスに保持してください。

利用可能なコマンドアダプタ:

using-arch-compiler.md
compile-architecture.md
implement-architecture.md

スペック形式

入力スペックは schemas/canonical-schema.yaml に対して検証されるYAMLファイルです。例:

# ─── サンプルスペック ───
# これは基本構造を示す最小限のスペックです。
# 要件が明確になるにつれてフィールドを段階的に追加します。
# より完全な例とエッジケースについては test-specs/ を参照してください。
project:
  name: My Service
  domain: ecommerce
functional:
  summary: REST API for product catalogue
constraints:
  cloud: azure
  language: python
  platform: api
nfr:
  availability:
    target: 0.999
  latency:
    p95Milliseconds: 100
    p99Milliseconds: 200
  security:
    auth: jwt

提供されていないすべてのフィールドは config/defaults.yaml から埋められ、出力の assumptions セクションに記録されます。

選択されるはずのパターンを明示的に除外するには（例: スコープに対して複雑すぎる場合）、トップレベルの disallowed-patterns リストを追加します:

disallowed-patterns:
  - ops-low-cost-observability
  - ops-slo-error-budgets

除外されたパターンは phase: phase_2_5_disallowed_patterns とともに rejected-patterns.yaml に表示されます。レジストリに見つからないIDについては警告が発行されます。

エッジケース、プラットフォームの組み合わせ、コンプライアンス要件などをカバーする包括的なサンプルスペックについては test-specs/ を参照してください。

コンパイラ出力

stdout

コンパイラは常にコンパイルされたスペックを標準出力に出力します — すべてのデフォルトが適用され、インラインパターンコメント（詳細モードの場合）が含まれたマージ済みスペックです。成功時は終了コード 0、検証エラー時は 1 を返します。

`-o` で書き込まれるファイル

ファイル	モード	説明
`compiled-spec.yaml`	常時	仮定を含む完全マージ済みスペック。再入力として再利用可能
`selected-patterns.yaml`	常時	一致スコアと採用ルールを含む選択済みパターン
`rejected-patterns.yaml`	`-v` のみ	理由とフィルタフェーズを含む拒否されたパターン
`compiled-spec-<timestamp>.yaml`	`-t`	UTCタイムスタンプ付きの同じファイル（例: `compiled-spec-2026-03-17T19:36:31Z.yaml`）

詳細モードのインラインコメント

-v を使用すると、コンパイルされたスペックは各フィールドに、それをトリガーしたパターンを注釈します:

constraints:
  platform: api  # arch-serverless--aws, db-managed-postgres, api-rest-resource-oriented, ... (あと13個)
  cloud: aws     # arch-serverless--aws, db-managed-postgres, api-rest-resource-oriented, ... (あと13個)
nfr:
  availability:
    target: 0.999  # arch-serverless--aws, db-managed-postgres, api-rest-resource-oriented, ... (あと14個)

これにより、スペック値と選択されたパターンの関係がすぐに可視化されます。

パターン選択の仕組み

フェーズ	処理内容
1. 解析と検証	スペックをロードし、スキーマを検証し、意味的な一貫性をチェック
2. デフォルトのマージ	欠落フィールドを `config/defaults.yaml` から埋め、`assumptions` に記録
2.5 禁止フィルタ	`disallowed-patterns` にリストされたパターンを削除。不明なIDについては警告
3.1 制約フィルタ	`supports_constraints` ルールがすべてスペックに一致するパターンを保持
3.2 NFRフィルタ	`supports_nfr` ルールがすべてスペックに一致するパターンを保持
3.3 競合解決	競合するパターンを削除。勝者は最高一致スコア、次に意図に基づく最低コスト
3.4 設定マージ	パターンの `defaultConfig` を `assumptions.patterns` にマージ
3.5 コーディングフィルタ	`--include-coding-patterns` が設定されていない限り、コーディングレベルのパターンを除外
4. コスト実現可能性	総コストを `cost.ceilings` に対してチェック。アドバイザリ警告を発行
5. 出力	コンパイルされたスペックを標準出力に出力。`-o` が指定されていれば成果物ファイルを書き込み

コーディングパターン

デフォルトでは、タイプが coding（GoF、DI、テスト戦略、開発ワークフローなど）のパターンは除外されます — AIコーディングエージェントの時代では、これらは要求に応じて処理できます。それらを含めるには --include-coding-patterns を使用します。

段階的リファインメント

コンパイラは反復的で段階的な使用を想定して設計されています。最初から完全なスペックを用意する必要はありません — 最小限から始めて、理解が深まるにつれて制約を段階的に追加します。

サンプルワークフロー

最小限から開始 → コンパイル → 仮定をレビュー → 制約を追加 → 再コンパイル → ...

ステップ1: 基本のみから始める

constraints:
  cloud: aws
  language: javascript
  platform: api
nfr:
  availability:
    target: 0.999

コンパイラを実行します。出力の assumptions セクションには、適用されたすべてのデフォルトが表示されます — これらはコンパイラが代わりに行った決定です。それらをレビューして、コンパイラが何を想定したかを理解します。

ステップ2: NFR制約を発見次第追加

nfr:
  availability:
    target: 0.999
  latency:           # ← レイテンシ目標がわかったら追加
    p95Milliseconds: 50
    p99Milliseconds: 100

新しい制約ごとにパターン選択が絞り込まれます。以前は選択されなかったパターンが拒否される場合があります — コンパイラは rejected-patterns.yaml ファイル（-v モード）でその理由を教えてくれます。

場合によっては、スペック自体が拒否されることもあります: ハードなNFR目標（例えば非常に厳しいレイテンシや高い可用性要件）を満たすパターンが利用可能な場合に存在しない場合、コンパイラはコード 1 で終了し、何が失敗したかを説明します。これは有用なシグナルです — つまり、制約が矛盾しているか、レジストリにまだ存在しないパターンが必要であることを意味します。

ステップ3: 機能に明示的にオプトイン

constraints:
  features:
    caching: true       # ← キャッシュアサイドと関連パターンをトリガー

機能フラグは constraints.features の下にあり、nfr の下ではありません。これらはパフォーマンス目標ではなく、オプトイン機能を表します。

パターンが一致すると、コンパイラは warn_nfr アドバイザリを発行する場合があります — 選択されたパターンが現在のNFR値に対して過小活用されているという警告です。例えば、スループットNFRなしでキャッシュを有効にすると、次のような出力が生成される可能性があります:

⚠️  cache-aside: ピーク読み取りQPSは5 req/sです（<10 req/s）。この規模ではキャッシュのオーバーヘッド
    （インフラ、無効化、シリアライゼーション）が利点を上回る可能性があります。

これは、パターンが選択されているが効果が期待できないことをコンパイラが伝えているものです — より具体的なNFRデータを提供するか、機能フラグを再検討するよう促します。

ステップ4: スループットデータを提供して warn_nfr アドバイザリを解決

キャッシュ（または他のスループット依存パターン）を有効にした後に warn_nfr アドバイザリが表示された場合、実際のピークQPSを追加します:

nfr:
  throughput:
    peak_query_per_second_read: 20    # ← コンパイラがキャッシュの利点を再評価
    peak_query_per_second_write: 10

実際のスループット数値があれば、コンパイラは確定的な判断を下せます — アドバイザリが消えるか（キャッシュが正当化される）、より具体的な理由とともに残ります。どちらの結果も、暗中模索でパターンが選択されるよりも有用です。

ステップ5: コストと運用モデルを気にするときに明示的に指定

cost:
  intent:
    priority: optimize-tco   # デフォルトはminimize-opex、別のオプションはminimize-capex
  ceilings:
    monthly_operational_usd: 500
    one_time_setup_usd: 1000
operating_model:
  ops_team_size: 2                    # 専任運用エンジニアの人数
  single_resource_monthly_ops_usd: 10000  # エンジニア一人あたりの月額フルロードコスト
  on_call: true                       # 運用チームコストに1.5倍の乗数を追加
  deploy_freq: daily                  # 運用オーバーヘッドに影響（daily = 1.0×、weekly = 0.8×、on-demand = 1.2×）
  amortization_months: 24             # CapExを償却する期間

inetgas/arch-compiler

arch-compiler とは？

お気に入りのAIに質問する

プレビュー

ドキュメント

アーキテクチャコンパイラ: アーキテクチャレベルAIハーネス

コア哲学

クイックスタート

開発環境のセットアップ

エージェントスキルのインストール

Codex

スキルエントリポイント

エージェントワークフロープリフライト

Claude Code

スペック形式

コンパイラ出力

stdout

`-o` で書き込まれるファイル

詳細モードのインラインコメント

パターン選択の仕組み

コーディングパターン

段階的リファインメント

サンプルワークフロー

関連スキル

steipete/video-frames

steipete/summarize

openclaw/openclaw

obra/superpowers

affaan-m/ECC

affaan-m/everything-claude-code

お気に入りのAIに質問する

プレビュー

ドキュメント

アーキテクチャコンパイラ: アーキテクチャレベルAIハーネス

コア哲学

クイックスタート

開発環境のセットアップ

エージェントスキルのインストール

Codex

スキルエントリポイント

エージェントワークフロープリフライト

Claude Code

スペック形式

コンパイラ出力

stdout

-o で書き込まれるファイル

詳細モードのインラインコメント

パターン選択の仕組み

コーディングパターン

段階的リファインメント

サンプルワークフロー

関連スキル

steipete/video-frames

steipete/summarize

openclaw/openclaw

obra/superpowers

affaan-m/ECC

affaan-m/everything-claude-code

`-o` で書き込まれるファイル