아키텍처 드리프트 감지: 코드와 설계의 정합성 유지하기 - Archyl Blog

아키텍처 드리프트는 문서화한 시스템과 실제로 가지고 있는 시스템 사이의 간극입니다. 이에 대한 통상적인 조언(문서를 코드 옆에 두기, 같은 pull request에서 리뷰하기)은 좋은 조언이지만, 그중 무엇도 그것이 효과가 있었는지는 알려주지 않습니다. 이 가이드는 드리프트가 무엇인지, 감지하는 방법들, 그리고 이미 존재하는 간극에 숫자를 붙이는 방법을 다룹니다.

아키텍처 드리프트 감지: 코드와 설계의 정합성 유지하기

조직 어딘가에 잘못된 아키텍처 다이어그램이 있습니다. 6개월 전에 다른 서비스와 합쳐진 마이크로서비스를 보여주고 있을 수도 있습니다. 프로덕션 장애 중에 팀이 Memcached로 전환했는데 여전히 Redis를 캐싱 레이어로 나열하고 있을 수도 있습니다. 충분한 편법과 우회가 쌓여 스파게티처럼 보이는 서비스를 깔끔한 헥사고날 아키텍처로 설명하고 있을 수도 있습니다.

이것이 아키텍처 드리프트입니다: 시스템의 문서와 실제 작동 방식 사이의 점진적이고 조용한 괴리. 버그와 달리 드리프트는 알림을 발생시키지 않습니다. 성능 저하와 달리 모니터링에 나타나지 않습니다. 누군가 오래된 문서를 기반으로 결정을 내릴 때까지 조용히 있다가 -- 그 결정이 잘못되었음이 드러납니다.

아키텍처 드리프트는 보편적입니다. 모든 팀이 경험합니다. 문제는 문서가 드리프트할지 여부가 아니라, 얼마나 빨리 감지하고 어떻게 대처할 것인가입니다.

그 뒷부분에 대한 조언은 부족하지 않습니다. 문서를 코드 옆에 두세요. 같은 pull request에서 리뷰하세요. Definition of Done에 포함시키세요. 모두 좋은 조언이고, 그중 대부분은 이 페이지 아래쪽에도 나옵니다. 그리고 이 조언들은 하나의 맹점을 공유합니다. 무엇을 해야 하는지는 알려주지만, 그것이 효과가 있었는지는 알려주지 않습니다. 일반적인 지침 중 검증에 가장 가까운 것은 마지막 수정 타임스탬프인데, 이는 누군가 그 파일을 건드린 시점을 알려줄 뿐 그 파일이 사실인지를 알려주지는 않습니다.

드리프트를 감지하는 일은 건너뛰기 쉬운 쪽 절반입니다. 이 가이드는 문제 자체, 감지 방법의 다섯 갈래, 그리고 각 방법이 볼 수 있는 것과 볼 수 없는 것을 다룹니다. 두 편의 자매 글이 각각 한 가지를 더 깊이 파고듭니다. 드리프트 점수가 어떻게 계산되고 그 숫자가 무엇을 의미하는지, 그리고 모델을 가진 뒤 그것을 사실로 유지하는 실천들입니다.

아키텍처 드리프트란?

아키텍처 드리프트는 소프트웨어 시스템의 실제 구현이 문서화되거나 의도된 아키텍처에서 벗어날 때 발생합니다. Perry와 Wolf는 Foundations for the Study of Software Architecture(ACM SIGSOFT Software Engineering Notes, 1992)에서 이 문제에 이름을 붙였고, 아키텍처를 위반해서 생기는 erosion(침식)과 아키텍처에 무감각해서 생기는 drift를 구분했습니다. 이후 일상적인 용법은 달라졌습니다. 오늘날 대부분의 엔지니어는 문서와 코드 사이의 모든 간극을 "드리프트"라고 부르며, 이 가이드도 그 의미로 사용합니다. 이 구분 자체는 지킬 가치가 있고, 아래에 따로 다루는 섹션이 있습니다.

드리프트는 아키텍처 문서의 모든 수준에서 나타납니다:

구조적 드리프트

문서화된 구조가 더 이상 코드베이스와 일치하지 않습니다:

  • 독립형 컨테이너로 문서화된 서비스가 모놀리스에 흡수됨
  • 컴포넌트 이름이 변경되었지만 다이어그램에는 여전히 이전 이름이 표시됨
  • 새 서비스가 생성되었지만 아키텍처 모델에 추가되지 않음
  • 데이터베이스가 MySQL에서 PostgreSQL로 마이그레이션되었지만 컨테이너 다이어그램에는 여전히 MySQL로 표시됨

행동적 드리프트

문서화된 행동이 더 이상 현실과 일치하지 않습니다:

  • 동기 API 호출이 비동기 메시지로 대체되었지만 관계에는 여전히 "REST/HTTP"로 표시됨
  • 데이터 흐름이 API 게이트웨이를 경유하도록 변경되었지만 다이어그램에는 직접 서비스 간 통신으로 표시됨
  • 시스템 맥락 다이어그램에 반영되지 않은 인증 단계가 추가됨

의존성 드리프트

문서화된 의존성이 더 이상 실제 통합과 일치하지 않습니다:

  • 써드파티 API가 자체 솔루션으로 대체됨
  • 새로운 외부 의존성(결제 제공자, 모니터링 서비스)이 추가되었지만 문서화되지 않음
  • 통합이 폐기되었지만 시스템 맥락 다이어그램에 여전히 표시됨

결정 드리프트

문서화된 아키텍처 결정이 더 이상 따르지 않고 있습니다:

  • ADR에 "모든 영구 저장에 PostgreSQL 사용"이라고 되어 있지만 한 팀이 MongoDB를 사용하기 시작함
  • 적합성 규칙에 "프론트엔드에서 직접 데이터베이스 접근 금지"라고 되어 있지만 누군가 클라이언트 측 Supabase 통합을 추가함
  • 배포 아키텍처에 "단일 리전"이라고 되어 있지만 서비스가 여러 리전에 배포됨

아키텍처 드리프트가 발생하는 이유

드리프트의 원인을 이해하는 것은 이를 방지하는 데 필수적입니다. 드리프트는 보통 악의적이지도, 심지어 태만하지도 않습니다 -- 소프트웨어가 개발되는 방식에서 자연스럽게 따라오는 결과입니다.

문서보다 속도

금요일까지 기능을 출시해야 할 때, 아키텍처 다이어그램 업데이트는 가장 먼저 빠지는 항목입니다. 코드 변경이 산출물입니다. 문서 업데이트는 오버헤드입니다. 단기적으로는 합리적인 행동이고 장기적으로는 파괴적입니다.

수많은 작은 변경

드리프트는 극적인 한 순간에 일어나는 경우가 드뭅니다. 문서를 업데이트할 만큼 크지 않은 수백 개의 작은 변경을 통해 누적됩니다:

  • 파일 이름 변경
  • 유틸리티 패키지 추가
  • 라이브러리 의존성 교체
  • 함수를 별도 모듈로 추출

어떤 변경도 단독으로는 문서 업데이트를 유발할 만큼 중요하지 않습니다. 하지만 합쳐지면 아키텍처를 바꿔놓습니다.

팀 이탈

엔지니어가 떠날 때 암묵적 지식도 함께 가져갑니다. 새 팀은 코드베이스를 물려받지만 왜 그렇게 구조화되어 있는지에 대한 이해는 물려받지 못합니다. 그들은 문서가 말하는 것이 아니라 코드에서 보이는 것에 근거해 변경하고, 드리프트를 넓힙니다.

피드백 루프의 부재

문서가 현실과 일치하는지 아무도 확인하지 않으면 드리프트는 보이지 않습니다. 감지 메커니즘이 없다면 드리프트를 발견하는 유일한 방법은 장애 중, 감사 중, 또는 새 엔지니어가 다이어그램이 코드와 맞지 않는다고 지적할 때입니다. 그때쯤이면 드리프트는 이미 광범위할 수 있습니다.

긴급 변경

프로덕션 장애는 종종 아키텍처적 편법을 요구합니다: API 레이어를 거치는 대신 데이터베이스에 직접 연결, config 서비스 대신 하드코딩된 설정, 영구화되는 임시 캐시. 이런 변경은 정상적인 리뷰 프로세스를 우회하고 거의 문서화되지 않습니다.

아키텍처 드리프트의 비용

드리프트는 미관상의 문제만이 아닙니다. 구체적이고 측정 가능한 비용이 있습니다.

잘못된 결정

아키텍트가 오래된 문서를 기반으로 결정을 내리면 그 결정은 틀릴 수 있습니다. "이 서비스는 트래픽이 적으니 동기 의존성을 감당할 수 있다" -- 다만 문서가 낡았고 그 서비스는 실제로 문서에 적힌 부하의 10배를 처리하고 있었다면요.

느린 온보딩

새 엔지니어는 멘탈 모델을 만들기 위해 아키텍처 문서에 의존합니다. 문서가 틀리면 잘못된 멘탈 모델을 만듭니다. 실제 아키텍처에 맞지 않는 코드를 작성합니다. 혼란을 드러내는 질문을 하며 시니어 엔지니어의 시간을 소모합니다.

장애 대응

프로덕션 장애 중에 아키텍처 다이어그램은 팀이 영향 범위와 의존성을 파악하는 데 도움이 되어야 합니다. 그 다이어그램이 틀리면 팀은 잘못된 의존성 체인을 추적하거나 중요한 상위 시스템을 놓치며 귀중한 몇 분을 낭비합니다.

컴플라이언스 및 감사 실패

규제 산업에서 아키텍처 문서는 종종 컴플라이언스(SOC 2, ISO 27001, HIPAA)를 위해 요구됩니다. 감사인이 문서가 현실과 일치하지 않는다고 판단하면 그것은 지적 사항이며 -- 심각한 지적일 수도 있습니다.

AI 에이전트의 혼란

AI 코딩 에이전트가 널리 쓰이면서, 이들은 맥락을 위해 아키텍처 문서에 점점 더 의존합니다. 오래된 C4 모델을 읽은 에이전트는 실제 아키텍처가 아니라 문서화된 아키텍처에 맞는 코드를 생성합니다. 이는 드리프트를 고치는 대신 증폭시킵니다.

아키텍처 드리프트를 감지하는 방법

일반적으로 쓰이는 접근법은 다섯 가지이고, 각각 다른 질문에 답합니다. 수동 리뷰는 그 자리에 있는 사람들이 보기에 다이어그램이 여전히 맞아 보이는지를 묻습니다. 피트니스 함수와 정적 분석은 특정 규칙이 깨지고 있는지를 묻습니다. LLM 평가는 코드가 스스로 구현한다고 주장하는 설계처럼 읽히는지를 묻습니다. 드리프트 스코어링은 문서화된 모델 중 얼마나가 아직 존재하는지를 묻습니다. 지금 당신에게 비용을 물리고 있는 질문이 무엇인지로 고르세요.

수동 리뷰 (전통적 접근)

가장 단순한 접근법은 주기적인 수동 리뷰입니다: 팀을 모으고, 아키텍처 다이어그램을 훑고, 여전히 현실과 일치하는지 확인합니다.

효과적인 경우: 소규모 팀, 단순한 아키텍처, 분기별 주기.

실패하는 경우: 대규모 시스템, 빠르게 움직이는 팀, 또는 코드를 가장 잘 아는 사람들이 리뷰 미팅에 쓸 시간이 없을 때. 수동 리뷰는 확증 편향에도 취약합니다 -- 사람들은 자신이 볼 것이라 예상한 것을 보는 경향이 있습니다.

아키텍처 피트니스 함수

Neal Ford와 "Building Evolutionary Architectures" 책으로 널리 알려진 피트니스 함수는 아키텍처 속성을 검증하는 자동화된 테스트입니다:

// Example: Ensure no direct database imports in handler packages
func TestNoDatabaseImportsInHandlers(t *testing.T) {
    packages := analyzeImports("./internal/handler/...")
    for _, pkg := range packages {
        for _, imp := range pkg.Imports {
            assert.NotContains(t, imp, "database/sql",
                "Handler %s imports database/sql directly", pkg.Name)
            assert.NotContains(t, imp, "gorm.io",
                "Handler %s imports GORM directly", pkg.Name)
        }
    }
}

피트니스 함수는 특정 규칙을 강제하는 데 강력하지만, 작성하고 유지하는 데 선행 노력이 필요합니다. 이들은 제약을 확인하지, 모델 전체를 확인하지는 않습니다.

정적 분석 도구

ArchUnit(Java), Deptrac(PHP), go-arch-lint(Go) 같은 도구는 코드 구조를 분석하고 의존성 규칙을 강제합니다:

// go-arch-lint configuration
components:
  handler:
    in: ./internal/handler/
  service:
    in: ./internal/service/
  repository:
    in: ./internal/repository/

rules:
  handler:
    can_depend_on: [service]
  service:
    can_depend_on: [repository]
  repository:
    can_depend_on: []

이 도구들은 단일 코드베이스 내에서 계층형 아키텍처를 강제하는 데 훌륭합니다. 서비스 간 드리프트는 다루지 않고, 아키텍처 모델이 코드와 일치하는지도 검증하지 않습니다.

LLM을 활용한 평가

Thoughtworks는 LLM을 활용한 아키텍처 드리프트 감소를 Technology Radar Vol. 34(2026년 4월)의 Assess 링에 올렸습니다. 이들이 문제를 규정한 방식은 인용할 가치가 있습니다. 벤더가 아닌 곳에서 나온 것이기 때문입니다:

Increased use of AI coding agents can accelerate drift from the intended codebase and architecture designs. Left unchecked, this drift compounds as agents and humans replicate existing patterns, including degraded ones, creating a feedback loop where poor code begets poorer code.

한국어 번역: AI 코딩 에이전트의 사용이 늘어나면 의도했던 코드베이스와 아키텍처 설계로부터의 드리프트가 가속될 수 있다. 방치하면 에이전트와 사람이 기존 패턴을(품질이 떨어진 것까지 포함해) 복제하면서 이 드리프트는 복리로 커지고, 나쁜 코드가 더 나쁜 코드를 낳는 피드백 루프가 만들어진다.

이들이 설명하는 기법은 결정론적 분석 도구(Spectral, ArchUnit, Spring Modulith를 언급합니다)와 LLM 평가를 짝지어, 규칙 엔진으로는 표현할 수 없는 의미적 위반을 잡아내고, 그런 다음 발견된 것을 고치는 데도 LLM을 활용합니다. 이들의 팀은 이를 API 품질 가이드라인에, 그리고 에이전트가 생성하는 변경을 안내하는 아키텍처 구역을 정의하는 데 적용해 왔습니다.

이들의 교훈 두 가지는 어떤 도구를 쓰든 가져갈 만합니다. 첫 스캔은 누구도 다 분류하지 못할 만큼 많은 위반을 드러내므로, 우선순위 결정이 진짜 작업이라는 것. 그리고 에이전트의 수정에는 그 자체의 검증 루프가 필요하다는 것 -- "코드를 바꿨다"와 "시스템을 개선했다"는 서로 다른 주장이기 때문입니다.

Assess는 Thoughtworks에서 "볼 만한 가치는 있지만 아직 추천하지는 않는다"는 링입니다. 딱 그렇게 받아들이세요. 이것이 정리해 주는 바는, 큰 컨설팅 회사가 글로 남길 만큼 이 문제가 실재한다는 것이고, 이는 드리프트를 둘러싼 대부분의 주장이 가리킬 수 있는 것보다는 많습니다.

자동화된 드리프트 스코어링

이것이 Archyl이 취하는 접근법입니다. 특정 규칙을 확인하는 대신, 아키텍처 모델 전체를 코드베이스와 대조해 검증합니다:

  • 문서화된 각 시스템이 리포지토리와 일치하는가?
  • 문서화된 각 컨테이너가 코드베이스의 디렉터리와 일치하는가?
  • 문서화된 각 코드 요소가 여전히 존재하는 파일을 참조하는가?
  • 문서화된 각 관계의 양 끝이 여전히 유효한가?

결과는 0에서 100까지의 점수와, 요소별 내역입니다. 무엇이 일치했는지, 무엇이 문서에는 있지만 사라졌는지, 무엇이 코드에는 있지만 어디에도 기록된 적 없는지를 보여줍니다. 피트니스 함수가 당신이 작성할 생각을 해낸 제약을 확인한다면, 이쪽은 이미 가지고 있는 모델 전체를 확인합니다.

Archyl 드리프트 감지의 핵심 설계 결정은 다음과 같습니다:

가볍습니다. AI 호출이 없고 파일 내용도 가져오지 않습니다. Git 제공자에 대한 재귀적 트리 요청 한 번, 그다음은 모델과의 경로·이름 대조뿐입니다. 계산은 몇 초면 끝납니다.

결정론적입니다. 같은 코드베이스, 같은 모델이면 같은 점수가 나옵니다. LLM 온도나 프롬프트 엔지니어링으로 인한 변동이 없습니다.

저렴합니다. 비용 걱정 없이 모든 푸시마다 실행하세요. 하루 100번 계산해도 괜찮습니다.

실행 가능합니다. 내역이 어떤 요소가 드리프트했는지 이름을 지목하므로, 무엇을 고칠지 알 수 있습니다.

트레이드오프는 첫 번째 항목에 있습니다. 코드를 읽는 대신 경로와 이름을 확인하기 때문에 점수는 빠르고 무료이며 재현 가능하지만, 그만큼 검사는 구조적인 것에 그칩니다. 디렉터리가 사라진 컨테이너와 파일이 삭제된 코드 요소는 보입니다. 두 서비스가 이름을 그대로 유지한 채 REST 호출이 큐 메시지로 바뀐 것은 보이지 않습니다. 그것이 행동적 드리프트이고, 이 가이드 앞부분의 분류 중 저렴한 검사로는 잡히지 않는 유일한 종류입니다. 그것에 대해 쓸 수 있는 것은 수동 리뷰와 LLM 평가입니다.

드리프트 점수가 어떻게 계산되는지 자세히에서 계산식, 분모에서 무엇이 제외되며 왜인지, 그리고 나머지 한계들을 다룹니다.

루프 닫기

감지만으로는 아무것도 바뀌지 않습니다. 누군가 한 번 계산하고 들여다보는 점수는 피드백 루프가 아니라 감사입니다. 이를 루프로 만드는 메커니즘이 셋 있고, 그중 무엇을 연결하기 전에 제대로 짚어둘 구분이 하나 더 있습니다. 그 옆에 놓이는 워크플로 실천들 -- architecture as code, Definition of Done에 문서 포함하기, 적합성 규칙 도입 -- 은 살아있는 아키텍처 문서에서 다룹니다.

CI에서 드리프트 감지 자동화

가장 강한 이빨을 가진 메커니즘은 드리프트가 임계값을 넘으면 실패하는 CI 게이트입니다. 머지를 멈출 수 있는 것은 이것뿐이기 때문입니다:

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'

드리프트 점수가 떨어져서 빌드가 실패하면, 누군가 머지 전에 고쳐야 합니다. 문서 정확도가 테스트 통과만큼이나 타협 불가능한 것이 됩니다.

임계값은 원하는 숫자가 아니라 현재 점수보다 아래로 설정하세요. 첫 실행에서 실패하는 게이트는 첫 실행에서 비활성화됩니다. 팀이 습관을 들여가는 만큼 올리세요.

드리프트 알림 설정

Archyl은 드리프트 이벤트에 대한 웹훅 알림을 지원합니다:

  • drift.score_computed: 드리프트 계산이 있을 때마다 발생합니다. 가시성을 위해 Slack 채널에 게시하세요.
  • drift.score_degraded: 점수가 10점 이상 하락하면 발생합니다. 이것이 조기 경보 시스템입니다.

이 알림들은 팀이 실제로 보는 채널로 설정하세요. 인지하는 것이 행동의 첫걸음입니다.

아키텍처 리뷰 진행

월별 또는 분기별 아키텍처 리뷰는 여러 목적에 기여합니다:

  • 문서화된 아키텍처가 여전히 현실과 일치하는지 검증
  • 자동화 도구가 놓친 드리프트(예: 행동적 드리프트) 식별
  • 드리프트한 컴포넌트를 코드에서 고칠지 문서에서 고칠지 논의
  • 다시 검토가 필요할 수 있는 결정에 대해 ADR 검토 및 갱신

드리프트와 적합성을 혼동하지 마세요

이 둘은 함께 실행되는 일이 잦아서 구분해 둘 가치가 있습니다. 계산 방식이 다르고, 실패하는 이유도 다르기 때문입니다.

드리프트 감지는 당신의 모델이 현실과 일치하는지 묻습니다. 문서화된 아키텍처를 리포지토리와 비교해 점수를 냅니다.

적합성 규칙은 현실이 당신의 규칙을 따르는지 묻습니다. 프론트엔드 컨테이너는 데이터베이스 컨테이너에 의존해서는 안 된다, 모든 공개 API는 게이트웨이를 거친다, 각 서비스는 자기 데이터베이스를 소유한다 같은 것들입니다. 심하게 드리프트한 모델에서도 적합성 검사는 통과할 수 있고, 완벽하게 정확한 모델이 당신이 가진 모든 규칙을 위반할 수도 있습니다.

둘 다 필요하며, 한쪽 숫자를 다른 쪽인 것처럼 읽어서는 안 됩니다.

아키텍처 드리프트 vs. 아키텍처 침식

이 용어들은 관련이 있지만 구별됩니다:

아키텍처 드리프트는 문서와 구현 사이의 괴리입니다. 코드는 완벽히 멀쩡할 수도 있습니다 -- 틀린 것은 문서 쪽입니다.

아키텍처 침식은 아키텍처 자체의 퇴화입니다. 코드가 아키텍처 원칙을 위반하고, 기술 부채를 쌓고, 유지보수가 어려워집니다. 침식은 코드 품질 문제입니다. 드리프트는 문서 정확도 문제입니다.

Perry와 Wolf는 1992년에 선을 다른 곳에 그었습니다. 그들에게는 둘 다 문서가 아니라 시스템의 속성이었고, 침식은 아키텍처를 위반해서, 드리프트는 아키텍처에 무감각해서 생기는 것이었습니다. 현대의 용법은 더 느슨하고 실무 팀에게 더 유용하지만, 아키텍처 침식에 관한 학술 문헌을 읽는다면 용어의 자리가 여기와는 다르게 잡혀 있으리라 예상하세요.

둘은 자주 함께 나타납니다. 문서가 드리프트하면 팀은 의도된 아키텍처에 대한 인식을 잃습니다. 그 인식 없이 가하는 변경이 아키텍처를 침식합니다. 드리프트가 침식을 가능하게 합니다.

그래서 드리프트 감지는 단순한 문서 정확도를 넘어서 중요합니다. 정확한 문서는 침식을 막는 참조점 역할을 합니다. 모두가 의도된 아키텍처를 볼 수 있을 때, 그것이 유지될 가능성이 높아집니다.

시간에 따른 드리프트 측정 및 추적

한 번의 드리프트 점수는 유용합니다. 추세는 강력합니다.

기준선 설정

팀이 일하는 방식에 대해 무엇도 바꾸기 전에 첫 계산을 실행하세요. 그때 나오는 값이 당신의 기준선이고, 첫 숫자가 낮다는 것은 판결이 아니라 정보입니다. 아무도 유지하라고 요청받은 적 없는 문서는 실패해 온 것이 아닙니다. 그저 측정된 적이 없었을 뿐입니다.

첫 실행 전에 뭔가를 고치고 싶은 충동은 참으세요. 필요한 것은 실제로 처해 있는 상황을 서술하는 숫자이지, 주말 내내 정리한 뒤에 나오는 숫자가 아닙니다.

추세 추적

단일 점수는 오늘에 대한 사실입니다. 당신이 바꾼 무언가가 효과가 있었는지 알려주는 것은 추세입니다:

  • 드리프트가 시간이 지나면서 나아지고 있는가, 나빠지고 있는가?
  • 특정 스프린트나 릴리스가 하락을 유발했는가?
  • CI 임계값이 선을 지키고 있는가, 아니면 다들 낮추고 있는가?

Archyl은 모든 계산을 전체 내역과 함께 저장하므로, 과거 리포트를 다시 열어 요소 단위로 비교할 수 있습니다. 어떤 도구를 쓰든 이력은 남기세요. 분기마다 처음부터 다시 계산하고 버리는 드리프트 점수는 다시 감사가 됩니다.

실제로 지킬 수 있는 목표를 정하세요

이상적인 숫자가 아니라 그다음 숫자를 고르세요. 오늘이 58이라면 유용한 목표는 65이고, 유용한 대화는 어떤 다섯 개 요소가 거기까지 데려다주는가입니다. 분기 말까지 90%에 도달하기로 합의한 팀은 대개 아무것에도 합의하지 않은 것입니다.

AI 지원 개발에서 드리프트 감지의 역할

이 부분이 가장 최근에 크게 달라진 부분이고, 앞에서 인용한 항목을 Thoughtworks가 쓴 이유이기도 합니다. 에이전트는 발견한 패턴을, 품질이 떨어진 것까지 포함해 복제하므로, 예전에는 사람의 commit 속도로 쌓이던 드리프트가 이제는 생성된 commit의 속도로 쌓입니다.

AI 에이전트는 맥락을 위해 아키텍처 문서에 점점 더 의존합니다. MCP 같은 프로토콜을 통해 에이전트는 코드를 생성하기 전에 당신의 C4 모델, ADR, 적합성 규칙을 읽을 수 있습니다. 이는 에이전트를 더 효과적으로 만듭니다 -- 추측하는 대신 당신의 아키텍처에 맞는 코드를 생성하니까요.

하지만 이는 문서가 정확할 때만 작동합니다. 오래된 C4 모델을 읽고 그것을 기반으로 코드를 생성하는 에이전트는 잘못된 아키텍처에 맞는 코드를 만들어냅니다. 에이전트는 드리프트를 방지하는 대신 증폭시킵니다.

드리프트 감지는 AI 에이전트를 정직하게 유지하는 피드백 루프를 만듭니다:

  1. 에이전트가 아키텍처를 읽음 (MCP 경유)
  2. 에이전트가 코드를 생성함 (문서화된 아키텍처에 맞게)
  3. 코드가 머지됨 (실제 아키텍처가 바뀔 수 있음)
  4. 드리프트 감지가 실행되어 모든 괴리를 잡아냄
  5. CI 게이트가 실패함 (드리프트가 임계값을 초과하면)
  6. 팀이 문서를 업데이트하여 현실을 반영함
  7. 에이전트가 업데이트된 아키텍처를 읽음 -- 루프가 닫힘

4단계가 없으면 루프는 열려 있습니다. 문서는 점점 더 허구가 됩니다. 에이전트는 환상 속 아키텍처에 맞는 코드를 점점 더 많이 생성합니다. 간극은 commit마다 벌어집니다.

드리프트 감지는 이 루프를 닫는 메커니즘입니다.

드리프트 감지 시작하기

이미 어딘가에 모델이 있다면

다른 무엇을 바꾸기 전에 그것을 측정하세요. 가능한 가장 저렴한 첫 수이고, 어떤 것도 약속하게 만들지 않습니다.

아키텍처가 이미 Structurizr DSL, LikeC4, IcePanel 또는 Backstage 카탈로그에 있다면, 그 모델을 가져와서 있는 그대로 점수를 계산해 보세요. 당신이 측정하는 것은 이미 써 놓은 문서를, 남겨둔 상태 그대로입니다. 워크플로 변경도, 팀의 새로운 습관도, 도구에 대한 결정도 아직 필요 없습니다. 이 숫자는 그 결정의 입력이지 결과가 아닙니다.

솔직한 유의사항이 두 가지 있습니다. 임포터는 무손실이 아닙니다. 뷰, 스타일, 레이아웃은 남지 않고, Structurizr 파서는 배포 환경과 배포 노드를 건너뛰지만, 경고 목록에 줄 번호와 함께 이름을 남깁니다. 분모를 신뢰하기 전에 그 목록과 임포트된 모델을 읽어보세요. 그리고 점수는 도착한 모델을 서술하는 것이지, 당신이 내보낸 파일을 서술하지 않습니다.

돌아오는 것은 요소별 목록입니다. 84점은 일정에 넣을 수 있는 유지보수 문제입니다. 41점은 다른 시스템을 서술하는 문서를 놓고 결정이 내려져 왔다는 뜻이며, 그것은 다음 장애 중에 아는 것보다 지금 아는 편이 낫습니다.

아키텍처 문서가 없다면

AI 디스커버리로 시작하세요. 리포지토리를 연결하고, 디스커버리가 C4 모델을 제안하게 하고, 직접 그리는 대신 제안을 승인하거나 거절하세요. 모델이 생기고 나면, 그것을 정직하게 유지하는 것이 드리프트 감지입니다.

이미 드리프트를 추적하고 있다면

CI에 넣으세요. 현재 점수보다 아래로 임계값을 설정하세요. 하락 알림을 구성하세요. 드리프트를 리뷰 전에 한 사람이 계산하는 숫자가 아니라, 팀이 매주 보는 지표로 만드세요.

어디서 시작하든

드리프트는 기술 부채처럼 불어납니다. 오래 둘수록 맞춰야 할 것이 많아지고, 그동안 그 문서를 믿는 사람은 줄어듭니다. 다른 점은, 먼저 아무것도 고치지 않고도 오늘 자신이 어디에 서 있는지 알아낼 수 있다는 것입니다.

당신의 아키텍처 문서는 현실을 반영하거나, 반영하지 않거나 둘 중 하나입니다. 드리프트 점수의 요점은 그것이 어느 쪽인지 더는 추측하지 않아도 된다는 데 있습니다.

더 깊이: 메커니즘은 드리프트 점수가 어떻게 계산되는지, 모델을 사실로 유지하는 실천은 살아있는 아키텍처 문서, 처음부터 시작한다면 C4 모델이란 무엇인가를 보세요. 정의는 아키텍처 드리프트, 살아있는 문서, 제품 안의 기능은 드리프트 감지입니다. Developer 플랜은 무료이고 카드도 필요 없습니다. 이미 가지고 있는 문서에 숫자를 붙여보고 싶다면: archyl.com.