아키텍처 문서는 거짓말을 합니다. 의도적으로가 아닙니다. 코드가 변경되는 순간 사실이 아니게 되는 것입니다. 오늘 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 없이, 파일 내용 가져오기 없이 수행됩니다. 다섯 가지 차원에서 아키텍처를 검증합니다:

Systems — 리포지토리 이름이 문서화된 시스템과 일치합니까? AI 디스커버리 파이프라인과 동일한 PascalCase 명명 규칙을 사용하며, 퍼지 매칭을 통해 EkoAuthz가 authz라는 이름의 리포지토리와 일치합니다.

Containers — 리포지토리의 최상위 디렉토리가 문서화된 Container에 해당합니까? frontend/는 FrontendWebApp과 일치합니다. backend/는 BackendApiServer와 일치합니다. 소스 디렉토리가 없는 인프라 Container(데이터베이스, 큐, 모니터링)는 올바르게 제외됩니다 -- 이것은 외부 서비스의 유효한 문서이지, 드리프트가 아닙니다.

Components — 각 Container 하위의 컴포넌트는 여전히 유효합니까? 상위 Container의 디렉토리가 존재하면 해당 컴포넌트는 유효한 것으로 간주됩니다. Container 디렉토리가 사라졌다면 모든 컴포넌트에 플래그가 지정됩니다.

Code Elements — 이것이 가장 정밀한 검사입니다. C4 model의 모든 코드 요소에는 filePath가 있습니다. 각 파일이 여전히 리포지토리에 존재하는지 확인합니다. 파일이 이름 변경되었나요? 클래스가 삭제되었나요? 모듈이 이동되었나요? Drift Score가 즉시 감지합니다.

Relationships — 관계는 소스와 타겟 요소 모두가 검증을 통과한 경우에 유효합니다. 어느 한쪽 엔드포인트가 드리프트한 경우 해당 관계에 플래그가 지정됩니다.

결과는 요소별 분류로, 무엇이 일치하고, 무엇이 누락되었으며, 무엇이 새로운지를 정확히 보여줍니다 -- 불투명한 점수가 아닌, 조치 가능한 보고서입니다.

경량성이 중요한 이유

드리프트 감지를 위해 전체 AI 디스커버리 파이프라인을 실행하지 않기로 의도적으로 결정했습니다. 그 이유는 다음과 같습니다:

속도. AI 분석은 대규모 리포지토리에서 수 분이 걸립니다. 드리프트 스코어링은 수 초입니다. 파이프라인을 늦추지 않고 모든 push에서 실행할 수 있습니다.

결정론. AI는 모델 온도, 프롬프트 변형, 토큰 제한에 따라 동일한 코드베이스에서 다른 결과를 생성할 수 있습니다. 파일 경로의 존재는 이진적입니다 -- 파일이 있거나 없거나입니다. 점수는 재현 가능합니다.

비용. AI 토큰 소비 없음. API 속도 제한 도달 없음. 원한다면 하루에 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 알림: 드리프트 발생 시 알림 받기

두 가지 새로운 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