살아있는 아키텍처 문서는 형식이 아니라 일하는 방식입니다. 모델은 코드에서 도출되고, 업데이트는 변경과 같은 Pull request에 함께 실리며, 무언가가 그것이 제대로 됐는지 확인합니다. 이를 지탱하는 다섯 가지 관행, 각각의 비용, 그리고 각각이 무너지는 지점을 소개합니다.

살아있는 아키텍처 문서: 항상 최신 상태로 유지하기

지난 화요일 누군가 서비스를 하나 추가하는 Pull request를 머지했고, 그 외에는 아무 일도 일어나지 않았습니다. 다이어그램은 하나도 바뀌지 않았고, ADR도 작성되지 않았으며, 리뷰 자체는 꼼꼼했습니다. 아무도 아키텍처를 언급하지 않은 이유는, 리뷰 대상이 아키텍처가 아니었기 때문입니다.

이 글의 주제가 바로 그것입니다. 문서가 낡아간다는 사실 자체가 아닙니다. 그건 아키텍처 드리프트 가이드가 감지 방법과 함께 다룹니다. 주제는, 문서가 최신 상태로 남을 수 있었던 그 한 번의 순간이 정상적이고 잘 굴러가는 워크플로 안에서 그냥 지나가 버렸다는 것입니다. 살아있는 문서란 그 순간을 놓치지 않게 만드는 장치들의 집합입니다. 이것은 문제의 실천 쪽 절반입니다. 다섯 가지 전략, 각각의 비용, 그리고 각각이 무너지는 지점을 다룹니다.

문서를 "살아있게" 만드는 것

살아있는 문서에는 전통적인 정적 문서와 구별되는 세 가지 핵심 특성이 있습니다.

자동 업데이트

살아있는 문서는 인간이 업데이트하는 것을 기억하는 것에만 의존하지 않습니다. 문서의 적어도 일부는 시스템 자체 -- 코드, 배포, 인프라, API 정의 -- 에서 도출됩니다. 시스템이 변하면 수동 개입 없이 문서가 그 변경을 반영합니다.

이것이 모든 것이 자동화된다는 뜻은 아닙니다. 아키텍처 의도, 설계 근거, 전략적 결정은 여전히 인간의 저작이 필요합니다. 하지만 문서의 사실적, 구조적 측면 -- 어떤 서비스가 존재하며, 어떤 기술을 사용하고, 어떻게 연결되는지 -- 은 자동화될 수 있고 자동화되어야 합니다.

지속적 검증

살아있는 문서에는 현실에서 벗어날 때를 감지하는 메커니즘이 포함됩니다. 누군가 읽고 잘못됐다고 깨달을 때가 아니라, 검증이 드리프트를 선제적으로 잡습니다.

실제로 이것은 서로 다른 두 가지 검사이며, 아래 전략 3에서 제대로 구분합니다. 하나는 적합성 규칙으로, 당신이 정한 기준에 모델이 부합하는지 검사합니다. 다른 하나는 드리프트 감지로, 코드베이스와 대조하여 모델을 검사합니다. 둘 다 CI에서 실행할 수 있습니다. 둘 다 잘못된 방향으로 움직일 때 알림을 받을 가치가 있습니다.

개발 워크플로의 일부

살아있는 문서는 별도의 프로세스에서 유지되지 않습니다. 코드가 작성되고, 리뷰되고, 배포되는 것과 같은 개발 워크플로에 통합됩니다. 아키텍처 변경은 Pull request를 통과합니다. 문서 업데이트는 코드 변경과 함께 이루어집니다. 문서는 개발자가 이미 작업하는 곳에 있습니다.

정적 문서의 문제

일하는 방식을 바꿔야 할 이유는, 그 대안에 정해진 모양이 있고 두 번쯤 보고 나면 일찍 알아볼 수 있게 되기 때문입니다.

생성-부패 순환

선의로 유지되는 문서는 예측 가능한 순환을 따릅니다:

생성: 의욕적인 팀원(또는 아키텍트, 컨설턴트)이 문서를 작성합니다. 정확하고, 상세하며, 잘 정리되어 있습니다.
유용성: 몇 주 또는 몇 달간 문서가 가치를 발휘합니다. 팀원이 참조합니다. 새 입사자가 배웁니다.
첫 번째 드리프트: 변경이 발생합니다 -- 새 서비스, 이름이 바뀐 컴포넌트, 변경된 의존성. 변경한 개발자가 생각하지 않았거나, 문서가 어디 있는지 몰랐거나, 시간이 없어서 문서가 업데이트되지 않습니다.
가속화된 부패: 첫 번째 부정확성이 나타나면, 부패 속도가 가속화됩니다. 이후의 각 변경이 문서에 반영될 확률이 낮아집니다. 신뢰가 비례하여 감소합니다.
포기: 결국 문서가 너무 구식이어서 아무도 신뢰하지 않습니다. 시스템이 실제로 어떤 모습인지가 아니라 "예전에 어떤 모습이었는지"의 참고 자료가 됩니다.
재생성: 누군가 문제를 인식하고 처음부터 새 문서를 만듭니다. 순환이 다시 시작됩니다.

비싼 부분은 6단계입니다. 각 생성 단계는 실제 노력을 요구하는데, 그 대부분은 지난번 생성이 이미 알고 있던 것을 다시 도출하는 데 쓰입니다. 시도와 시도 사이에 판이 하나도 바뀌지 않았기 때문입니다. 팀이 같은 아키텍처 문서를 두 번째나 세 번째로 다시 쓰고 있다면, 문제는 애초에 쓰는 일이 아니었습니다.

인간 병목

정적 문서는 전적으로 인간이 추가적인 일을 하는 것에 의존합니다. 기능을 끝낸 후 개발자가 아키텍처 다이어그램을 업데이트하는 것을 기억해야 합니다. 설계 세션 후 누군가 화이트보드 논의를 구조화된 문서로 변환해야 합니다. 리팩토링 후 누군가 영향받는 모든 다이어그램이 여전히 정확한지 확인해야 합니다.

이 각각은 다른 우선순위와 경쟁하는 수동 단계입니다. 대부분의 조직에서 문서 업데이트는 코드 작성, 버그 수정, 마감 준수보다 우선순위가 낮습니다. 결과는 예측 가능합니다: 문서가 뒤처집니다.

발견 문제

문서가 정확하더라도 찾기 어려운 경우가 많습니다. 아키텍처 다이어그램은 Confluence에 있습니다. API 스펙은 별도 도구에 있습니다. ADR은 Git 저장소에 있습니다. 기술 선택은 위키에 문서화되어 있습니다. 완전한 그림을 제공하는 단일 장소가 없고, 개발자는 여러 도구를 검색하며 시간을 낭비합니다 -- 만약 검색한다면.

살아있는 아키텍처 문서를 위한 전략

문서를 진정으로 살아있게 만들려면 여러 전략을 결합해야 합니다. 어떤 단일 접근도 그 자체로 충분하지 않지만, 함께하면 최소한의 수작업으로 문서를 최신으로 유지하는 시스템이 만들어집니다.

전략 1: 코드 기반 문서

문서를 최신으로 유지하는 가장 효과적인 방법은 코드에서 도출하는 것입니다. 문서가 시스템의 소스 코드, 설정, 인프라 정의에서 생성되면 드리프트할 수 없습니다 -- 항상 현재 상태에서 재구축되기 때문입니다.

Architecture as code가 이 전략의 가장 직접적인 구현입니다. 시각적 도구에서 다이어그램을 그리고 누군가 업데이트하길 바라는 대신, Git 저장소에 있는 YAML 파일로 아키텍처를 정의합니다. 파일이 소스 오브 트루스이고, 시각적 다이어그램이 거기서 생성됩니다.

개발자가 새 서비스를 추가하면, 같은 Pull request에서 아키텍처 파일에 몇 줄을 추가합니다. 변경이 구현과 함께 코드 리뷰를 거칩니다. CI/CD 파이프라인이 업데이트된 파일을 문서 플랫폼에 동기화합니다. 다이어그램이 항상 코드에서 재생성되므로 항상 최신입니다.

API 계약 생성도 코드 기반 문서의 한 형태입니다. OpenAPI 생성기와 같은 도구가 주석이 달린 코드에서 API 명세서를 생성할 수 있습니다. API 문서를 별도로 유지하는 대신, 구현에서 문서가 추출됩니다. 코드가 변하면 문서가 변합니다.

Archyl에서 archyl.yaml 파일이 코드 기반 소스 오브 트루스 역할을 합니다. REST API나 MCP 서버를 사용하여 빌드 파이프라인에서 프로그래밍 방식으로 아키텍처 요소를 업데이트하여, 자동화된 프로세스가 문서를 동기화 상태로 유지하도록 할 수도 있습니다.

전략 2: AI 기반 발견

코드 기반 문서가 있더라도, 코드에 명시적이지 않은 아키텍처 측면이 있습니다. 서비스가 환경 변수를 통해 설정된 데이터베이스를 사용할 수 있습니다. 두 서비스가 인프라 코드에 정의된 공유 Kafka 토픽을 통해 통신할 수 있습니다. 새 서비스가 배포 파이프라인에 존재하지만 아키텍처 파일에는 아직 없을 수 있습니다.

AI 기반 발견이 코드베이스, 인프라, 배포 아티팩트를 분석하여 아키텍처 문서에 대한 업데이트를 제안함으로써 이러한 격차를 메웁니다.

Archyl의 AI 발견 기능은 저장소를 스캔하여 식별합니다:

아직 문서화되지 않은 새 서비스
코드에 존재하지만 아키텍처 모델에 반영되지 않은 의존성
마지막 문서 업데이트 이후 변경된 기술 스택
문서와 다른 통신 패턴

AI가 자동으로 문서를 수정하지 않습니다 -- 인간이 검토하고 승인하는 변경을 제안합니다. 모델이 무엇을 말할지에 대한 판단은 여전히 전부 당신 몫입니다. 그만두게 되는 것은 무엇이 바뀌었는지 찾아다니는 일입니다.

전략 3: 적합성 규칙과 드리프트 감지

살아있는 문서에는 두 개의 가드레일이 필요합니다. 그리고 이 둘은 일상적으로 서로 혼동됩니다. 둘 다 숫자를 내놓고, 둘 다 요란하게 실패하기 때문입니다. 하지만 서로 다른 것을 측정합니다.

적합성 규칙은 당신의 모델이 당신이 정한 기준을 따르는지 묻습니다. 모든 컨테이너가 기술을 명시한다, 모든 외부 시스템에 설명이 있다, 고아가 없다. 규칙 엔진이 이를 평가하고 위반을 보고합니다.

드리프트 감지는 당신의 모델이 여전히 코드베이스와 일치하는지 묻습니다. 문서화된 아키텍처를 저장소와 비교하여 0에서 100 사이의 점수를 반환합니다. 당신의 규칙에 대해서는 아무것도 모릅니다.

모델은 당신이 쓴 모든 규칙을 충족하면서도, 지난 분기 리팩토링으로 사라진 시스템을 서술하고 있을 수 있습니다. 반대의 경우도 일어납니다. 정확한 모델이 당신의 기준 절반을 어기고 있는 경우입니다. 두 검사가 모두 필요하며, 한쪽 숫자를 다른 쪽인 양 읽어서는 안 됩니다. 드리프트 점수가 계산되는 방식이 후자를 자세히 다루며, 그것이 볼 수 없는 것까지 설명합니다.

적합성 규칙 예시:

모든 컨테이너에 최소 하나의 기술이 문서화되어야 함
모든 외부 시스템에 설명이 있어야 함
데이터베이스 의존성이 있는 모든 서비스에 문서화된 데이터 소유권 설명이 있어야 함
고아 컨테이너 금지 (모든 컨테이너가 최소 하나의 관계에 참여해야 함)
모든 ADR이 최소 하나의 아키텍처 요소를 참조해야 함
모든 API 유형 컨테이너에 연결된 API 계약이 있어야 함

Archyl은 이런 규칙 169개를 카탈로그로 제공하며, 이름이 명시된 23개 기술과 언어 비종속 세트를 아우릅니다. 그래서 대부분의 팀은 직접 규칙을 쓰기보다 해당되는 것을 켜는 데서 시작합니다. 위반은 요소별로 보고되는데, 이것이 중요합니다: "컨테이너 일곱 개에 문서화된 기술이 없다"는 할 일이지만, "당신의 문서는 불완전하다"는 기분일 뿐입니다.

드리프트 점수는 별도로, 요청 시 또는 CI 잡에서 계산되며, 10점 이상 떨어지면 웹훅이 발화합니다. 이 둘이 함께 Pull request가 열어둔 채 남긴 고리를 닫습니다. 규칙은 끝내 완성되지 않은 문서를 잡아내고, 점수는 더 이상 사실이 아니게 된 문서를 잡아냅니다.

전략 4: 완료 정의의 일부로서의 문서

살아있는 문서를 위한 가장 효과적인 조직적 전략은 아키텍처에 영향을 미치는 모든 작업의 완료 정의에 문서 업데이트를 포함시키는 것입니다.

이것은 다음을 의미합니다:

Pull request가 새 서비스를 추가하면, 같은 PR에서 아키텍처 파일이 업데이트되어야 함
설계 세션에서 결정이 나오면, 결정이 구현되기 전에 ADR이 만들어져야 함
API 계약이 변경되면, 문서화된 계약이 업데이트되어야 함
서비스가 폐기되면, 아키텍처 모델에서 제거되어야 함

이것은 관료주의가 아닙니다 -- "변경이 발생하는 시점"과 "문서가 업데이트되는 시점" 사이의 격차를 0으로 줄이는 것입니다. 문서가 코드 변경과 같은 워크플로의 일부이면, 별도의 노력이 필요하지 않습니다.

Archyl은 architecture-as-code 통합을 통해 이를 지원합니다. 아키텍처 파일이 코드와 같은 저장소에 있으면, 같은 Pull request에서 둘 다 업데이트하는 것이 자연스럽습니다. 코드 리뷰어가 아키텍처 변경이 구현과 함께 문서화되었는지 확인할 수 있습니다.

전략 5: 지속적 시각화

살아있는 문서는 접근하기 쉽고 시각적으로 유용해야 합니다. 개발자가 아키텍처를 이해하기 위해 YAML 파일을 파싱해야 한다면, 도입률이 떨어집니다. 코드 기반 정의는 항상 최신이고, 항상 접근 가능하며, 항상 유용한 시각적 출력을 생산해야 합니다.

이것은 다음을 의미합니다:

소스 오브 트루스에서 자동으로 재생성되는 아키텍처 다이어그램
시스템 맥락에서 컨테이너, 컴포넌트로 줌할 수 있는 인터랙티브 탐색
특정 측면(소유권, 기술 스택, 통신 패턴)을 강조하는 오버레이
모든 아키텍처 요소, 관계, 문서에 걸친 검색

Archyl의 시각적 레이어는 모델에서 읽어옵니다. 그래서 그 모델이 어떻게 업데이트되었든 -- YAML 파일, MCP 서버, REST API, 시각적 편집기 -- 아무도 다시 그리지 않아도 다이어그램이 현재 상태를 보여줍니다. 그것이 정확히 무엇을 보장하는지 짚어두세요: 그림은 항상 모델과 일치합니다. 모델이 코드와 일치하는지는 드리프트 점수의 질문이지, 렌더러의 질문이 아닙니다.

문서 신선도 측정

살아있는 문서는 측정 가능해야 합니다. 중요한 메트릭을 소개합니다.

드리프트 점수

이 관행이 작동하고 있는지 알려주는 단 하나의 숫자입니다. 문서화된 아키텍처 중 얼마나 많은 부분이 여전히 코드베이스에 존재하는지 측정하며, 이 글의 장치들이 버텨주고 있다면 하락을 멈춥니다. main에 푸시할 때마다 CI에서 실행하면, 그 추세선은 당신의 의도가 아니라 당신의 워크플로에 대한 정직한 보고서가 됩니다.

전체 메커니즘, 공식, 그리고 그것이 볼 수 없는 네 가지는 별도의 글에서 다룹니다.

문서화 소요 시간

아키텍처 변경이 문서에 나타나기까지 걸리는 시간을 측정합니다. 잘 작동하는 살아있는 문서 시스템에서 이것은 거의 0이어야 합니다 -- 문서 업데이트가 코드 변경과 같은 Pull request에서 발생하기 때문입니다. 일관된 지연이 있으면, 워크플로 통합을 개선해야 합니다.

커버리지

아키텍처의 몇 퍼센트가 문서화되어 있는지 추적합니다. 얼마나 많은 서비스에 설명이 있나요? 얼마나 많은 관계에 레이블이 있나요? 얼마나 많은 컨테이너에 문서화된 기술 스택이 있나요? 커버리지 메트릭이 격차가 어디 있는지 알려줍니다.

신뢰 설문

정기적으로 개발자에게 묻습니다: "아키텍처 문서를 신뢰하십니까?" 답이 아니오이면, 정량적 메트릭이 무엇을 말하든 살아있는 문서 관행을 개선해야 합니다. 개발자 신뢰가 문서 품질의 궁극적 측정입니다.

흔한 실수

모든 것을 자동화하기

모든 것이 자동화될 수 있거나 되어야 하는 것은 아닙니다. 아키텍처 의도, 설계 근거, 트레이드오프 분석, 전략적 방향은 인간의 저작이 필요합니다. 살아있는 문서는 사실적, 구조적 측면을 자동화하면서 인간의 통찰을 위한 공간을 보존합니다.

적합성을 규정 준수로 취급하기

적합성 규칙은 처벌적이 아니라 도움이 되어야 합니다. 의도하지 않은 드리프트를 잡기 위해 존재하며, 관료적 오버헤드를 만들기 위한 것이 아닙니다. 팀이 유용한 작업보다 적합성 규칙을 충족하는 데 더 많은 시간을 쓴다면, 규칙이 너무 엄격합니다.

온보딩 유스케이스 무시하기

살아있는 문서는 시스템을 한 번도 본 적 없는 사람에게도 접근 가능해야 합니다. 문서를 이해하기 위해 깊은 맥락이 필요하다면, 가장 중요한 목적 중 하나를 제대로 수행하지 못하고 있는 것입니다. 정기적으로 신규 입사자의 관점에서 문서를 살펴보며 테스트하세요.

완벽을 좋은 것의 적으로 만들기

유용한 살아있는 문서를 위해 완전한 커버리지와 완벽한 드리프트 점수가 필요하지 않습니다. 서비스 대부분을 다루고 매주 업데이트되는 Container 다이어그램이 6개월 전에 정확했던 완전한 문서 세트보다 가치 있습니다. CI 임계값은 오늘 있는 자리보다 낮게 잡고 팀이 준비되면 올리세요. 아무도 도달한 적 없는 숫자로 막아세우는 것보다 그편이 낫습니다.

Archyl이 살아있는 아키텍처 문서를 지원하는 방법

Archyl은 처음부터 살아있는 문서 관행을 지원하도록 구축되었습니다. 각 기능이 기여하는 방식입니다.

Architecture as Code가 문서를 코드 기반으로 만듭니다. archyl.yaml 파일이 Git에 있고, 코드 리뷰를 거치며, CI/CD를 통해 자동으로 동기화됩니다. 아키텍처 파일 변경이 시각적 다이어그램에 즉시 업데이트를 생성합니다.

AI 발견이 코드베이스를 분석하고 업데이트를 제안하여 문서 격차를 식별합니다. 새 서비스, 변경된 의존성, 업데이트된 기술 스택을 잡아냅니다.

적합성 규칙이 올바른 문서가 어떤 모습인지 정의하고 위반을 요소별로 보고합니다. 드리프트 감지는 별개의 검사입니다: 모델을 저장소와 비교하여 그 격차에 점수를 매깁니다. 규칙은 끝내 완성되지 않은 문서를 잡아내고, 점수는 더 이상 사실이 아니게 된 문서를 잡아냅니다.

MCP 서버가 아키텍처 문서를 AI 지원 개발 워크플로에 통합합니다. 개발자가 별도 도구로 맥락 전환하지 않고 IDE에서 문서를 쿼리하고 업데이트할 수 있습니다.

소유권 맵이 모든 아키텍처 요소를 책임 팀에 매핑하여 책임을 만듭니다. 문서가 드리프트하면 소유 팀이 식별되어 조치를 취할 수 있습니다.

협업 기능 -- 코멘트, 변경 요청, 실시간 공동 편집 -- 이 문서를 혼자 하는 부담이 아닌 팀 활동으로 만듭니다.

릴리스 추적과 DORA 메트릭이 아키텍처 문서를 딜리버리 성과에 연결하여, 아키텍처 결정이 팀의 소프트웨어 배포 능력을 개선하고 있는지 방해하고 있는지에 대한 지속적인 신호를 제공합니다.

시작하기

아키텍처 문서가 현재 정적이라면, 살아있게 만드는 실용적인 경로입니다. 계속할 이유가 생기는 순서로 배열했습니다:

이미 가진 것을 측정하세요. 팀이 일하는 방식을 바꾸기 전에, 기존 모델을 상대로 드리프트 점수를 계산합니다. 저장소 하나를 연결하면 되고, 이후 모든 단계를 판단할 기준선이 생깁니다.
Container 다이어그램부터 시작하세요. 서비스, 기술, 핵심 관계. 그것을 정식 참조로 삼고 차점자들은 지우세요. 진실의 원천이 둘이라는 것은 곧 없다는 뜻입니다.
아키텍처를 코드로 이동하세요. 모델을 archyl.yaml로 내보내고, 저장소에 커밋하고, CI/CD 동기화를 설정합니다.
적합성 규칙을 추가하세요. 뻔한 것들(모든 컨테이너가 기술을 명시한다, 모든 컨테이너가 최소 하나의 관계에 속한다)로 시작하고, 팀이 더는 거기에 걸려 넘어지지 않을 때 확장합니다.
문서를 PR 워크플로의 일부로 만드세요. 체크리스트 항목도 됩니다. CI의 드리프트 임계값이 더 낫습니다. 묻는 대신 실패하기 때문입니다.
MCP 서버를 설정하세요. 코딩 에이전트에게 모델을 주어, 아키텍처를 읽고 업데이트하는 일이 작업이 끝난 뒤가 아니라 작업의 흐름 속에서 일어나게 하세요.
숫자가 아니라 추세를 보세요. 월 1회면 충분합니다. 물어야 할 것은 3번부터 6번까지가 선을 지키고 있는가이고, 거기에 답할 수 있는 것은 추세뿐입니다.

살아있는 아키텍처 문서는 목적지가 아니라 관행입니다. 목표는 완벽한 문서가 아니라, 신뢰를 받을 만큼 충분히 정확하고 그 상태를 유지할 만큼 일관되게 유지되는 문서입니다. 그 둘 중 어느 쪽을 가지고 있는지 알아내는 방법이 바로 점수입니다.

이 클러스터의 나머지: 문제 자체와 감지 방법은 아키텍처 드리프트 감지, 메커니즘은 드리프트 점수가 계산되는 방식. 정의: 살아있는 문서, 아키텍처 드리프트. 제품 페이지: 드리프트 감지. 1단계는 Developer 플랜에서 무료이며 카드가 필요 없습니다: archyl.com.

살아있는 아키텍처 문서: 항상 최신 상태로 유지하기 - Archyl Blog