AI ネイティブチームのための Architecture Intelligence

この半年で、何かが変わりました。AI エージェントは関数を書く段階から、サービス全体を書く段階へと進化しました。Claude Code、Cursor、Codex — もはやアシスタントではありません。チームメンバーです。PR を作成し、コードをレビューし、フィーチャーをリリースします。

しかし、私が夜眠れない理由がここにあります：これらのエージェントはアーキテクチャがどうなっているか全く把握していないのです。

エージェントは10分で完璧にクリーンな Go サービスを書くことができます。しかし、チームが3ヶ月前にすべてのサービス間通信を Kafka 経由にすると決めたことを知りません。ペイメントサービスへの直接データベースアクセスが禁止されていることを知りません。前四半期に Python がテクノロジーレーダーで「ホールド」に移されたことを知りません。

その結果は？マシンスピードでのアーキテクチャドリフトです。

私たちはこの問題を解決するために Archyl を構築しました。そして本日、ローンチ以来最大のアップデートをリリースします：Architecture Intelligence — Archyl を AI ネイティブ開発の神経系にする完全なエコシステムです。

問題：エージェントは高速にコーディングするが、盲目的にコーディングする

人間の開発者がチームに参加すると、数日かけてドキュメントを読み、質問をし、システムのメンタルモデルを構築します。ルールを学びます — 明文化されたものも、暗黙のものも。境界を理解します。

AI エージェントはこのすべてをスキップします。タスクを受け取り、コードを書き、PR を作成します。レビューでアーキテクチャ違反を誰も発見できなければ、そのままリリースされます。これを10のエージェントが3つのチームにまたがる10のサービスで作業していると考えてください。慎重に設計されたアーキテクチャが数週間で侵食されます。

私たちはこれが実際に起こるのを見てきました。1月に完璧な C4 モデルを持っていたチームが、3月にはドリフトスコア40%になっていました。関心がなくなったからではありません — エージェントがアーキテクチャの存在を知らなかったからです。

解決策：インフラストラクチャとしてのアーキテクチャ

アーキテクチャドキュメントは、メンテナンスするものであるべきではありません。自らメンテナンスするもの — そしてすべてのエージェントが一行のコードを書く前に参照するものであるべきです。

それが私たちの構築したものです。本日リリースする内容をご紹介します。

10のエージェントスキル

オリジナルの archyl-developer スキルは、エージェントに200以上の MCP ツールへのアクセスを提供していました。しかし、ワークフローのないツールボックスでした。本日、開発ライフサイクル全体をカバーする9つの特化スキルを追加します：

コーディング前

archyl-preflight — フィーチャーを実装する前に実行してください。計画されたアプローチを C4 モデル、コンフォーマンスルール、テクノロジーレーダー、API コントラクトに照らして検証します。一行のコードを書く前に、明確な PASS / WARN / FAIL の判定を得ることができます。

> ユーザーサービスに Redis キャッシュを追加しようとしています。問題ありませんか？

プリフライトチェック: WARNING
- Redis はテクノロジーレーダーで承認済み ✓
- ユーザーサービスは C4 モデルに存在 ✓
- ⚠ ドキュメント化されたキャッシュコンテナなし — 作成を推奨
- ⚠ "No Direct DB Access from Handlers" ルールが適用されます — キャッシュがサービスレイヤーを通じてアクセスされることを確認してください

リリース後

archyl-postship — リリース後に実行してください。構築したものを分析し、C4 モデルを更新し、アーキテクチャ上の決定に対して ADR を作成し、アーキテクトのレビュー用に Change Request を作成します。ドキュメントが作業の副産物として自動的に更新されます。

レビュー中

archyl-review — アーキテクチャレビューボットです。PR の diff をドキュメント化されたアーキテクチャに照らしてチェックし、構造化されたフィードバックを提供します：コンフォーマンス違反、境界越え、未承認のテクノロジー、欠落した API コントラクト。ESLint のようなものですが、アーキテクチャ向けです。

可視性のために

archyl-changelog — すべてのアーキテクチャ変更の読みやすいタイムラインを生成します：新しいサービス、変更された関係、ADR の決定、ドリフトの推移。アーキテクチャレビューミーティングに最適です。

archyl-dora — DORA メトリクスとアーキテクチャ変更を相関させます。マイクロサービスの分解でリードタイムは改善されましたか？ドリフトの急増がチェンジフェイルレートの上昇に先行しましたか？今やデータがあります。

archyl-roi — アーキテクチャ上の決定の財務的影響を定量化します。「コンフォーマンスルールへの投資により、リワークの削減で前四半期に推定23,000ドルを節約しました。」これがアーキテクチャの予算承認を得るためのデータです。

予防のために

archyl-predict — アーキテクチャリスクが顕在化する前に予測します。「現在のペースでは、ドリフトスコアは5月までに50%を超えるでしょう。PaymentService には12のインバウンド依存関係があります — 分解を検討してください。」

archyl-autofix — ドリフトが検出された場合、具体的な修正を提案します。ドキュメントをコードに合わせて更新するか、アーキテクチャに再整合するためのコード変更を提案します。人間のレビュー用に Change Request を作成します。

調整のために

archyl-orchestrate — 複数のエージェントが異なるサービスで同時に作業する場合、このスキルが API コントラクトの交渉、依存関係の競合解決、クロスチーム変更がアーキテクチャを破壊しないことの保証を行います。

6つの GitHub Actions

アーキテクチャガバナンスは CI に属します。すべての PR とマージで自動的に実行される6つの GitHub Actions をリリースします：

推奨セットアップは1つのファイルです：

name: Architecture
on:
  pull_request:
    branches: [main]
  push:
    branches: [main]

jobs:
  pr-checks:
    if: github.event_name == 'pull_request'
    uses: archyl-com/actions/.github/workflows/archyl-pr.yml@v1
    with:
      organization-id: ${{ vars.ARCHYL_ORG_ID }}
      project-id: ${{ vars.ARCHYL_PROJECT_ID }}
      drift-threshold: 70
    secrets:
      api-key: ${{ secrets.ARCHYL_API_KEY }}

  main-update:
    if: github.event_name == 'push'
    uses: archyl-com/actions/.github/workflows/archyl-main.yml@v1
    with:
      organization-id: ${{ vars.ARCHYL_ORG_ID }}
      project-id: ${{ vars.ARCHYL_PROJECT_ID }}
    secrets:
      api-key: ${{ secrets.ARCHYL_API_KEY }}

GitHub をお使いでない場合は、GitLab CI と Bitbucket Pipelines 向けのテンプレートも提供しています。

コンフォーマンスルールパック

アーキテクチャガバナンスをゼロから設定するのは面倒です。そこで、数秒でインストールできる5つのプリビルトルールパックを構築しました：

エージェントスキル経由でインストール：「microservices コンフォーマンスルールパックをインストールしてください。」 完了です。

SDK

カスタムインテグレーションを構築するチーム向けに、公式 SDK を公開します：

npm install @archyl/sdk    # Node.js 18+、依存関係ゼロ
pip install archyl-sdk     # Python 3.10+

const archyl = new ArchylClient({ apiKey: 'arch_...', organizationId: 'uuid' });
const drift = await archyl.governance.computeDrift(projectId);
const predictions = await archyl.projects.getPredictions(projectId);

3つの新しい AI 搭載 API

内部的に、3つの新しいバックエンド機能をリリースします：

Predictive Analytics (GET /projects/:id/predict) — 本格的な統計分析です。ドリフトスコアの線形回帰、DORA メトリクスの軌跡、コンフォーマンス減衰率、ファンイン/ファンアウト結合分析によるコンプレキシティホットスポットの検出。感覚ではなく — 数学です。

Architecture Diff Analysis (POST /projects/:id/architecture-diff) — git diff を送信すると、構造化された C4 モデルのデルタが返されます。新しいサービス、変更された依存関係、アーキテクチャ上の決定を検出する AI 搭載分析です。重要な決定が検出された場合、ADR を提案します。

ROI Computation (GET /projects/:id/roi) — アーキテクチャ投資のリターンを定量化します。DORA メトリクスを前後で分割し、生産性の向上（節約時間 × 時給コスト）、信頼性の向上（回避されたインシデント × インシデントコスト）を計算し、ADR を財務的影響でランク付けします。

3つすべてが MCP ツールとして利用可能なため、すべてのエージェントスキルから直接呼び出すことができます。

フルループ

すべてがどのように連携するかを示します：

エージェントがタスクを受け取る
       │
       ▼
  archyl-preflight ──── アーキテクチャに対してアプローチを検証
       │
       ▼
  エージェントがコードを書く
       │
       ▼
  archyl-review ──────── C4 モデルに対して PR をレビュー
       │
       ▼
  CI: conformance-check ─ 違反をブロック
  CI: drift-score ──────── 整合性を強制
       │
       ▼
  main にマージ
       │
       ▼
  CI: auto-cr ──────────── Change Request を作成
  CI: generate-context ─── archyl.txt を更新
       │
       ▼
  archyl-postship ──────── C4 モデル + ADR を更新
       │
       ▼
  次のエージェントが archyl.txt を読む ← サイクルが繰り返される

アーキテクチャはメンテナンスされるものではありません。自らメンテナンスするものです。

はじめに

1. スキルをインストール：

/plugin marketplace add archyl-com/agent-skills
/plugin install archyl-preflight@archyl-com-agent-skills

2. GitHub Actions を追加： 上記のワークフローを .github/workflows/architecture.yml にコピーしてください。

3. 最初の archyl.txt を生成： generate-context アクションを実行するか、エージェントに聞いてください：「このプロジェクトのアーキテクチャコンテキストファイルを生成してください。」

4. コーディングを開始。 エージェントはアーキテクチャを理解しています。

今後の展望

これは基盤です。予測と ROI のフロントエンドダッシュボード、より多くのコーディングエージェントとの深い統合、コンフォーマンスルールパックのコミュニティマーケットプレイスに取り組んでいます。

アーキテクチャドキュメントは、チームがやろうと思いつつも実行できなかったものでした。エージェントがコードを書く時代において、アーキテクチャは人間が所有すべき唯一のものになります。Archyl は、それを一人で行う必要がないようにします。

本日リリースしたすべてはオープンソースです。皆さまのフィードバックをお待ちしています。