アーキテクチャドキュメントは嘘をつきます。意図的にではありません。コードが変更された瞬間に、真実でなくなるのです。本日、Architecture Drift Scoreをリリースします。C4 modelが実際のコードベースをどれだけ正確に反映しているかを示す単一の数値です。数秒で計算され、時系列で追跡でき、CIで適用可能です。

Architecture Drift Score: あなたのドキュメントは真実を語っていますか？

ソフトウェアアーキテクチャには不都合な真実があります。ほとんどのドキュメントは間違っているということです。

「エラーを含んでいる」という意味で間違っているのではありません。「もう存在しないシステムを記述している」という意味で間違っているのです。ダイアグラムは6ヶ月前に別のサービスに統合されたマイクロサービスを表示しています。C4 modelは週末のインシデント中にMemcachedに置き換えられたRedisキャッシュをリストしています。コンポーネント図は、アーキテクトに誰も知らせなかったリファクタリングでBillingServiceにリネームされたPaymentGatewayを参照しています。

これは規律の問題ではありません。構造的な問題です。コードは継続的に変化します。ドキュメントは誰かが思い出した時に変更されます。現実とドキュメントの間のギャップ——私たちがアーキテクチャドリフトと呼ぶもの——は、壁に掛けられたダイアグラムが本番のシステムと全く似ていなくなるまで静かに拡大します。

私たちはこのギャップを可視化し、測定可能にし、対処可能にするためにDrift Scoreを構築しました。

単一の数値: 0から100

Architecture Drift Scoreは一つの質問に答えます: ドキュメント化されたアーキテクチャのうち、実際にコードベースに存在するのは何パーセントですか？

Archylで任意のプロジェクトを開き、ヘッダーのハートビートアイコンをクリックして、「Compute Drift Score」を押してください。数秒で、0から100の間の数値が表示されます:

90-100% — 優秀。ドキュメントはコードベースと正確に一致しています。
70-89% — 良好。ほぼ正確ですが、いくつかのギャップがあります。
50-69% — 普通。重大なドリフトが検出されました。更新の時期です。
50%未満 — あなたのドキュメントはフィクションです。

以上です。長いレポートを読む必要はありません。主観的な評価もありません。追跡し、トレンド分析し、強制できる一つの数値です。

実際に何をチェックするのか

ドリフト分析は設計上軽量です——gitプロバイダーへの単一のAPI呼び出しのみで、AIなし、ファイル内容の取得なし。5つの次元でアーキテクチャを検証します:

Systems — リポジトリ名がドキュメント化されたシステムと一致するか？AIディスカバリーパイプラインと同じPascalCase命名規則を使用し、ファジーマッチングによりEkoAuthzがauthzという名前のリポジトリと一致します。

Containers — リポジトリのトップレベルディレクトリがドキュメント化されたContainersに対応するか？frontend/はFrontendWebAppに一致します。backend/はBackendApiServerに一致します。ソースディレクトリを持たないインフラストラクチャContainer（データベース、キュー、モニタリング）は正しく除外されます——これらは外部サービスの有効なドキュメントであり、ドリフトではありません。

Components — 各Container配下のコンポーネントはまだ有効か？親Containerのディレクトリが存在すれば、そのコンポーネントは有効とみなされます。Containerディレクトリが消えた場合、そのすべてのコンポーネントがフラグ付けされます。

Code Elements — これが最も精密なチェックです。C4 model内のすべてのコード要素にはfilePathがあります。各ファイルがリポジトリ内にまだ存在するかを検証します。ファイルがリネームされた？クラスが削除された？モジュールが移動された？Drift Scoreは即座に検出します。

Relationships — リレーションシップは、ソースとターゲットの両方の要素が検証を通過した場合に有効です。どちらかのエンドポイントがドリフトした場合、そのリレーションシップはフラグ付けされます。

結果は要素ごとの内訳で、何が一致し、何が欠けており、何が新しいかを正確に示します——不透明なスコアではなく、対処可能なレポートです。

なぜ軽量であることが重要なのか

ドリフト検出に完全なAIディスカバリーパイプラインを実行しないことを意図的に選択しました。その理由は以下の通りです:

スピード。 AI分析は大規模なリポジトリでは数分かかります。ドリフトスコアリングは数秒です。パイプラインを遅くすることなく、すべてのpushで実行できます。

決定論性。 AIはモデルの温度、プロンプトの変動、トークン制限に応じて、同じコードベースで異なる結果を生成する可能性があります。ファイルパスの存在はバイナリです——ファイルがあるかないかです。スコアは再現可能です。

コスト。 AIトークンの消費なし。APIレート制限に抵触しません。必要なら1日100回実行してください。

シンプルさ。 アルゴリズムは監査可能です。ファイルパスの確認、ディレクトリ名のマッチング、リレーションシップの検証。ブラックボックスはありません。

スナップショットではなくトレンドを追跡する

単一のスコアは有用です。トレンドは強力です。

すべてのドリフト計算は完全な内訳とともに保存されます。Overviewタブにはスコアの時系列バーチャートが表示されます。任意のバーをクリックして、その履歴レポートを読み込み、何が変わったかを正確に確認できます。

これにより、ドリフトスコアリングは一度きりの監査から継続的なヘルスメトリクスに変わります。以下が確認できます:

先週のリファクタリングはドキュメントの正確性を向上させたか、それとも悪化させたか？
ドリフトは時間とともに悪化しているか？（ネタバレ: 自動化なしでは常に悪化します。）
どのスプリントで最も多くの未ドキュメント化された変更が導入されたか？

CIで強制する

強制しないメトリクスは無視されるメトリクスです。だからこそGitHub Actionを構築しました。

on:
  push:
    branches: [main]

jobs:
  drift:
    runs-on: ubuntu-latest
    steps:
      - uses: archyl-com/actions/drift-score@v1
        with:
          api-key: ${{ secrets.ARCHYL_API_KEY }}
          organization-id: ${{ secrets.ARCHYL_ORG_ID }}
          project-id: 'your-project-uuid'
          threshold: '70'

threshold: '70'を設定すると、アーキテクチャドキュメントの正確性が70%を下回った場合にアクションが失敗します。ジョブサマリーには完全な内訳を含むフォーマット済みテーブルが表示されます——PRのチェックで直接確認できます。

スコアをPRコメントとして投稿することもできます:

- uses: archyl-com/actions/drift-score@v1
  id: drift
  with:
    api-key: ${{ secrets.ARCHYL_API_KEY }}
    organization-id: ${{ secrets.ARCHYL_ORG_ID }}
    project-id: 'your-project-uuid'

- uses: actions/github-script@v7
  if: github.event_name == 'pull_request'
  with:
    script: |
      github.rest.issues.createComment({
        issue_number: context.issue.number,
        owner: context.repo.owner,
        repo: context.repo.repo,
        body: '## Architecture Drift: ' +
              '${{ steps.drift.outputs.score }}%\n' +
              'Matched: ${{ steps.drift.outputs.matched-count }}' +
              ' / ${{ steps.drift.outputs.total-elements }}'
      })

すべての開発者がマージ前に自分の変更によるドリフトの影響を確認できます。アーキテクチャドキュメントは、テスト、リンティング、セキュリティスキャンと並んで、CIパイプラインのファーストクラスシチズンになります。

MCP: 自身の正確性を知るAIエージェント

Claude Code、Cursor、またはArchylのMCPサーバーを使用するMCP互換のAIエージェントを利用している場合、ドリフトスコアリングはツールとして利用可能です:

compute_drift_score({ projectId: "..." })
get_drift_score({ projectId: "..." })
get_drift_history({ projectId: "..." })
get_drift_details({ scoreId: "..." })

これは、AIエージェントが作業を開始する前にドキュメントの正確性を確認できることを意味します。get_agent_contextツールは既に完全なC4 model、ADR、適合ルールを提供しています。今では、そのドキュメントがどれだけ信頼できるかも確認できます。

45%のドリフトスコアを見たエージェントは、受け取ったアーキテクチャコンテキストに対して慎重になるべきだと理解します。95%を見たエージェントは、ドキュメント化された構造を確信を持って信頼できます。これは、ドキュメント品質に基づいて行動を調整する自己認識型AIエージェントの基盤です。

Webhookアラート: ドリフト発生時に通知を受ける

2つの新しいWebhookイベントにより、ダッシュボードを確認せずに情報を得られます:

drift.score_computed — ドリフトスコアの計算が完了するたびに発火します。Slackチャンネルに送信して可視性を高めましょう。
drift.score_degraded — 前回の計算から10ポイント以上スコアが低下した場合に発火します。これは早期警告システムです——アーキテクチャが急速にドリフトしています。

ArchylのWebhook設定でこれらを構成してください。Slack、Microsoft Teams、Discord、および任意のジェネリックHTTPエンドポイントで動作します。

REST API

完全なプログラマティック制御を望むチーム向け:

# 計算をトリガー
curl -X POST https://api.archyl.com/api/v1/drift/compute \
  -H "X-API-Key: $API_KEY" \
  -H "X-Organization-ID: $ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{"projectId": "your-project-uuid"}'

# 最新スコアを取得
curl https://api.archyl.com/api/v1/drift/latest?projectId=...

# スコア履歴を取得
curl https://api.archyl.com/api/v1/drift/history?projectId=...&limit=20

計算は非同期です——POSTはスコアIDと共に即座に返り、statusがcompletedになるまでポーリングします。GitHub Actionはこれを自動的に処理します。

エージェント時代における意味

AIエージェントが本番コードの重要な部分を書く時代に入りつつあります。これらのエージェントは高速で有能ですが、コンテキストに対してブラインドです。AuthServiceが先月IdentityServiceとAccessControlに分割されたことを知りません。frontend/ディレクトリがweb/にリネームされたことも知りません。

ドリフトスコアはフィードバックループを作ります:

AIエージェントがコードを書く前にMCP経由でC4 modelを読み取る。
コード変更が発生する（人間またはエージェントによって）。
ドリフトスコアがドキュメントと現実のギャップを検出する。
CIゲートがギャップが閾値を超えて拡大するのを防ぐ。
Webhookがドリフトが加速した時にチームに警告する。
チームがドキュメントを更新する（またはディスカバリーを実行して自動更新する）。
AIエージェントが更新されたモデルを読み取る。ループが閉じる。

ステップ3がなければ、ループは開いたままです。ドキュメントはドリフトします。エージェントは古いコンテキストに依存します。悪い意思決定が蓄積されます。

ドリフトスコアがループを閉じます。

はじめに

Archylで任意のプロジェクトを開く
ヘッダーツールバーのハートビートアイコンをクリック
「Compute Drift Score」をクリック
継続的モニタリングのためにGitHub Actionをセットアップ
drift.score_degradedアラート用にSlack Webhookを設定

あなたのアーキテクチャドキュメントは現実を反映しているか、していないかのどちらかです。今、どちらなのかを教えてくれる数値があります。

Architecture Drift Score: あなたのドキュメントは真実を語っていますか？ - Archyl Blog