수동 아키텍처 문서화는 이길 수 없는 싸움입니다. 코드는 매일 변하지만, 다이어그램은 분기별로 업데이트됩니다. AI는 코드에서 아키텍처를 발견하고, 드리프트를 자동으로 감지하며, AI 에이전트에게 아키텍처 인식을 부여하여 이 균형을 바꾸고 있습니다. 그 원리와 앞으로의 방향을 소개합니다.

AI 기반 아키텍처 문서화: 미래가 도래하다

소프트웨어 아키텍처 문서화의 핵심에는 근본적인 긴장이 있습니다. 코드는 살아 있습니다 -- 매 커밋, 매 리팩토링, 매 핫픽스마다 변화합니다. 문서는 정적입니다 -- 누군가 업데이트를 기억할 때만 변합니다. 둘 사이의 격차는 위키의 다이어그램이 더 이상 존재하지 않는 시스템을 설명하게 될 때까지 조용히 커집니다.

이것은 규율의 문제가 아닙니다. 가장 성실한 팀도 결국에는 뒤처지게 됩니다. Lattix의 연구에 따르면 대부분의 조직에서 아키텍처 문서는 작성 후 몇 주 이내에 구식이 됩니다. 정확한 다이어그램을 수동으로 유지하는 데 필요한 노력은 시스템 복잡성에 비례하여 선형적으로 증가하는 반면, 코드 변경 속도는 일정하거나 가속화됩니다.

AI가 이 균형을 바꾸고 있습니다. 인간의 아키텍처 판단을 대체하는 것이 아니라, 인간이 잘 못하는 문서화의 영역인 발견, 동기화, 드리프트 감지를 자동화함으로써입니다. 그 결과 코드에서 시작하고, 자동으로 최신 상태를 유지하며, 인간과 AI 에이전트 모두를 위한 지식 레이어로 기능하는 아키텍처 문서가 탄생합니다.

수동 아키텍처 문서화의 문제

AI가 어떻게 도움이 되는지 살펴보기 전에, 무엇이 깨져 있는지 구체적으로 짚어봅시다.

생성 문제

기존 시스템에 대한 아키텍처 문서를 처음부터 만드는 것은 고통스럽습니다. 코드를 읽고, 의존성을 추적하고, 팀원을 인터뷰하며, 서서히 멘탈 모델을 구축하여 다이어그램으로 변환합니다. 중간 규모 시스템(20-30개 서비스)의 경우 몇 주가 걸립니다. 대규모 시스템(100개 이상 서비스)은 몇 달이 걸립니다.

그 시간 동안 시스템은 계속 변합니다. 문서가 "완성"될 즈음에는 일부가 이미 구식입니다. 움직이는 목표를 문서화하고 있는 셈입니다.

유지보수 문제

완벽한 문서를 만들더라도, 정확하게 유지하려면 지속적인 노력이 필요합니다. 모든 새 서비스, 이름이 바뀐 모든 모듈, 폐기된 모든 API가 아키텍처 다이어그램에 반영되어야 합니다. 실제로 이것은 다음을 의미합니다:

개발자가 코드 변경과 함께 다이어그램을 업데이트해야 합니다
누군가 다이어그램 업데이트의 정확성을 검토해야 합니다
오래된 다이어그램을 감지하고 수정해야 합니다

대부분의 팀은 프로세스로 해결하려 합니다: "아키텍처를 변경할 때 아키텍처 다이어그램을 업데이트하라." 이것은 마감과 기능 개발의 압박이 문서 업데이트를 우선순위 목록 맨 아래로 밀어내기 전 약 3개월 정도 작동합니다.

발견 문제

새 엔지니어가 팀에 합류하면, 생산적이 되기 전에 아키텍처를 이해해야 합니다. 문서가 존재하지만 구식이라면, 문서가 없는 것보다 더 나쁩니다. 적극적으로 잘못된 정보를 주기 때문입니다. 신규 엔지니어가 잘못된 다이어그램을 기반으로 멘탈 모델을 구축하고, 그 가정을 디버깅하는 데 며칠을 보냅니다.

문서가 없으면, 발견은 부족 지식에 의존합니다: 가장 오래된 엔지니어에게 물어보는 것입니다. 이것은 확장되지 않고 병목을 만들며, 핵심 인력이 떠나면 완전히 실패합니다.

일관성 문제

여러 팀이 있는 조직에서는 각 팀이 아키텍처를 다르게 문서화합니다. A팀은 Visio를 사용합니다. B팀은 Miro를 사용합니다. C팀은 ASCII 아트가 있는 README를 가지고 있습니다. D팀은 문서화를 전혀 하지 않습니다. 조직의 아키텍처에 대한 통합된 뷰도, 일관된 표기법도, 팀 간 의존성을 이해하는 방법도 없습니다.

AI가 균형을 바꾸는 방법

AI는 이러한 문제 각각을 해결합니다. 인간의 관여를 제거하는 것이 아니라, 지루하고 오류가 발생하기 쉬운 부분을 자동화하고 인간의 판단을 증폭시킴으로써입니다.

AI 기반 아키텍처 발견

아키텍처 문서화에서 AI의 가장 즉각적인 적용은 자동화된 발견입니다. 코드를 수동으로 읽고 다이어그램을 구축하는 대신, AI 시스템에 코드베이스를 가리키면 초안 아키텍처 모델이 생성됩니다.

Archyl에서 이것이 실제로 어떻게 작동하는지 살펴봅시다:

저장소 연결. Git 저장소(GitHub, GitLab, Bitbucket 또는 Azure DevOps)를 연결합니다.
코드 스캐닝. 시스템이 코드베이스를 순회하며 파일 구조, 설정 파일, 진입점, 의존성 그래프를 식별합니다.
AI 분석. 대규모 언어 모델이 코드를 청크 단위로 분석하여 다음을 식별합니다:
- 각 모듈이나 서비스가 담당하는 것
- 사용 중인 기술과 프레임워크
- 코드가 통합하는 외부 시스템
- 컴포넌트 간 통신 방식
C4 모델 생성. AI가 발견한 내용을 C4 모델 요소로 매핑합니다: 시스템, 컨테이너, 컴포넌트, 코드 요소, 관계.
인간 검토. 생성된 모델을 검토하고, 정확한 요소를 수락하고, 실수를 수정하고, AI가 추론할 수 없었던 맥락을 추가합니다.

결과는 몇 주가 아닌 몇 분 만에 생성된 C4 아키텍처 모델입니다. 완벽하지는 않습니다 -- AI는 비즈니스 도메인이나 조직적 맥락을 이해하지 못합니다. 하지만 빈 캔버스보다 훨씬 나은 출발점입니다.

AI가 잘하는 것

AI는 아키텍처 문서화의 구조적 측면에서 뛰어납니다:

기술 감지. LLM은 수십 가지 언어와 생태계에 걸쳐 프레임워크 패턴, 라이브러리 관용구, 설정 형식을 인식합니다. github.com/gofiber/fiber가 있는 go.mod 파일은 Fiber 프레임워크를 사용하는 Go 서비스를 즉시 식별합니다. next가 있는 package.json은 Next.js 애플리케이션을 식별합니다.

서비스 경계 감지. 마이크로서비스 아키텍처에서 AI는 디렉토리 구조, Docker 설정, 배포 매니페스트로부터 서비스 경계를 안정적으로 식별합니다. 5개 서비스가 있는 docker-compose.yml은 AI에게 작업할 수 있는 명확한 토폴로지를 제공합니다.

의존성 매핑. Import 문, API 클라이언트 라이브러리, 설정 파일은 서비스 간 그리고 외부 시스템에 대한 의존성을 드러냅니다. 모든 SDK import, 모든 API 기본 URL, 모든 연결 문자열이 단서입니다.

패턴 인식. AI는 수백만 개의 코드베이스에서 학습되었습니다. MVC 구조, 헥사고날 아키텍처, event-driven 패턴 및 수십 가지 다른 아키텍처 패턴을 인식합니다. 코드가 확립된 관행을 따르면, AI가 빠르게 식별합니다.

AI가 잘못하는 것

기대를 적절히 설정하기 위해 한계를 정직하게 인정하는 것이 중요합니다:

비즈니스 도메인. AI는 processOrder()가 존재한다는 것을 알려줄 수 있지만, 특정 비즈니스 맥락에서 "주문 처리"가 무엇을 의미하는지는 알려줄 수 없습니다. 도메인별 네이밍, 맞춤 워크플로, 비즈니스 규칙은 인간의 해석이 필요합니다.

비전통적 아키텍처. 시스템이 커스텀 플러그인 프레임워크, 자체 구축 빌드 시스템, 비표준 프로젝트 구조를 사용하면 AI가 어려움을 겪을 수 있습니다. React 앱은 React 앱처럼, Go 서비스는 Go 서비스처럼 보일 것을 기대합니다.

런타임 의존성. 정적 코드 분석은 런타임에만 존재하는 의존성을 감지할 수 없습니다: 사이드카 컨테이너, 서비스 메시 설정, 환경별 통합, 코드에 표현되지 않은 인프라 등입니다.

의도. AI는 코드가 하는 일을 설명할 수 있지만, 왜 그렇게 작성되었는지는 설명할 수 없습니다. 시스템을 형성한 아키텍처 결정, 트레이드오프, 제약 조건은 코드 자체에 보이지 않습니다. 이것이 ADR(Architecture Decision Records)이 여전히 필수적인 이유입니다 -- AI는 구조를 발견하지만, 의도는 인간이 문서화합니다.

드리프트 감지: 문서를 정직하게 유지하기

발견은 생성 문제를 해결합니다. 드리프트 감지는 유지보수 문제를 해결합니다.

아키텍처 드리프트는 문서가 말하는 것과 코드가 실제로 하는 것 사이의 격차입니다. 이름이 바뀐 서비스가 다이어그램에서 여전히 이전 이름으로 표시되는 것. 폐기된 컴포넌트가 여전히 활성으로 표시되는 것. 아키텍처 모델에 추가되지 않은 새로운 마이크로서비스.

자동화된 드리프트 감지 작동 방식

Archyl의 드리프트 감지는 경량 접근 방식을 취합니다. 전체 AI 발견 파이프라인을 다시 실행하지 않습니다(느리고 비쌉니다). 대신 대상별 검증을 수행합니다:

시스템: 문서화된 시스템 이름이 저장소 이름과 일치하는가?
컨테이너: 문서화된 컨테이너가 코드베이스의 실제 디렉토리에 해당하는가?
컴포넌트: 문서화된 컴포넌트가 상위 컨테이너의 존재를 고려할 때 여전히 유효한가?
코드 요소: 문서화된 각 코드 요소의 파일 경로가 저장소에 여전히 존재하는가?
관계: 문서화된 각 관계의 양 끝점이 여전히 유효한가?

결과는 0에서 100 사이의 드리프트 점수로, 문서화된 아키텍처가 현실과 얼마나 일치하는지의 비율을 나타냅니다. 95%는 문서가 매우 정확하다는 뜻입니다. 50%는 문서의 절반이 허구라는 뜻입니다.

드리프트를 실행 가능하게 만들기

점수만으로는 충분하지 않습니다. Archyl은 정확히 무엇이 드리프트했는지 보여주는 상세 분석을 제공합니다:

코드베이스에서 누락되었지만 문서화된 컨테이너
더 이상 존재하지 않는 파일을 참조하는 코드 요소
드리프트한 요소에 연결된 관계
코드베이스에 존재하지만 문서화되지 않은 새로운 요소

이 분석은 "문서가 아마 구식일 것이다"라는 막연한 느낌을 수정해야 할 구체적이고 실행 가능한 목록으로 전환합니다.

CI/CD에서의 드리프트

드리프트 감지의 가장 강력한 활용은 지속적 통합입니다. Archyl은 모든 push에서 드리프트 점수를 계산하는 GitHub Action을 제공합니다:

- 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'

임계값을 설정하면, 문서 정확도가 그 이하로 떨어지면 빌드가 실패합니다. 이것은 아키텍처 문서를 테스트처럼 취급합니다: 저하를 방지하는 품질 관문입니다.

이 접근 방식을 도입한 팀은 문서에 대한 사고방식이 근본적으로 바뀌었다고 보고합니다. 문서화가 후속 작업이 아니라, 모든 커밋에서 확인되는 일급 관심사가 됩니다.

MCP 혁명: 아키텍처를 이해하는 AI 에이전트

Model Context Protocol (MCP)은 AI 에이전트가 외부 도구 및 데이터 소스와 상호작용할 수 있게 하는 개방형 표준입니다. Archyl의 MCP 서버는 전체 아키텍처 모델 -- C4 다이어그램, ADR, 적합성 규칙, 드리프트 점수 -- 을 모든 MCP 호환 AI 에이전트에 노출합니다.

이는 새로운 패러다임을 만듭니다: 아키텍처를 인식하는 AI 에이전트.

작동 방식

Claude Code, Cursor 또는 다른 MCP 호환 AI 코딩 어시스턴트를 Archyl의 MCP 서버에 연결하여 사용하면:

에이전트가 get_agent_context를 호출하여 프로젝트의 전체 C4 모델, ADR, 적합성 규칙을 받을 수 있습니다.
코드를 작성하기 전에, 에이전트는 문서화된 아키텍처를 이해합니다: 어떤 서비스가 존재하는지, 어떻게 통신하는지, 어떤 기술이 사용되는지, 어떤 결정이 내려졌는지.
에이전트가 get_drift_score를 확인하여 문서의 신뢰도를 평가할 수 있습니다.
에이전트가 특정 ADR을 읽어 특정 아키텍처 선택이 왜 내려졌는지 이해할 수 있습니다.

왜 이것이 중요한가

아키텍처 맥락 없이, AI 코딩 에이전트는 강력하지만 눈이 멀었습니다. 아키텍처 원칙을 위반하거나, 원하지 않는 의존성을 도입하거나, 다른 서비스에 이미 존재하는 기능을 중복시키는 훌륭한 코드를 작성할 수 있습니다.

MCP를 사용하면, 에이전트는 다음을 알게 됩니다:

"이 시스템은 MongoDB가 아니라 PostgreSQL을 사용한다 -- MongoDB 쿼리가 아니라 SQL 쿼리를 생성해야 한다."
"서비스 간 통신은 HTTP 호출이 아니라 Kafka 이벤트를 사용한다 -- REST 요청이 아니라 이벤트를 발행해야 한다."
"팀이 GraphQL을 거부했다(ADR-0019) -- GraphQL 구현을 제안하면 안 된다."
"아키텍처 드리프트 점수가 45%이다 -- 문서화된 구조에 의존할 때 신중해야 한다."

이것은 AI 에이전트를 코드 생성기에서 아키텍처 인식 협업자로 변환합니다.

적합성 규칙

수동적 맥락을 넘어, Archyl은 아키텍처 제약을 정의하는 적합성 규칙을 지원합니다:

"프론트엔드 컨테이너는 데이터베이스와 직접 통신해서는 안 된다"
"모든 서비스 간 통신은 API 게이트웨이를 통해야 한다"
"모든 신규 서비스에는 관련 ADR이 있어야 한다"

AI 에이전트는 MCP를 통해 이러한 규칙을 읽고, 생성한 코드가 규칙을 준수하도록 할 수 있습니다. 이는 AI 지원 개발과 함께 확장되는 아키텍처 거버넌스입니다.

실제 영향

AI 기반 문서화 도입 전

AI 지원 없이의 일반적인 시나리오:

신규 엔지니어가 팀에 합류합니다
코드를 읽고, 질문하고, 멘탈 모델을 구축하는 데 2-3주를 보냅니다
아무도 혜택받지 못하는 개인 메모를 작성합니다
아키텍처 다이어그램이 8개월 전에 마지막으로 업데이트되었고 40% 오류가 있습니다
어떤 ADR이 아직 유효한지 아무도 모릅니다
맥락이 소실되어 모든 아키텍처 논의가 처음부터 시작됩니다

AI 기반 문서화 도입 후

AI 기반 문서화가 적용된 같은 시나리오:

신규 엔지니어가 Archyl을 열고 현재 C4 모델을 봅니다 (드리프트 점수: 92%)
시스템 맥락에서 컨테이너, 컴포넌트로 탐색합니다
복잡한 서비스를 클릭하여 핵심 결정을 설명하는 연결된 ADR을 읽습니다
아키텍처 채팅을 사용하여 질문합니다: "주문 서비스는 결제 서비스와 어떻게 통신하나요?"
몇 주가 아닌 며칠 만에 코드에 기여하기 시작합니다
코드를 작성하는 AI 에이전트가 문서화된 아키텍처와 결정을 존중합니다

그 차이는 미묘하지 않습니다. 부족 지식과 조직적 지식의 차이입니다. 번거로운 문서화와 자산인 문서화의 차이입니다.

AI 아키텍처 문서화의 미래

아직 초기 단계입니다. AI 기반 아키텍처 문서화가 향하는 방향을 소개합니다:

지속적 발견

현재 발견은 특정 시점 작업입니다: 실행하고, 결과를 검토하고, 넘어갑니다. 미래의 발견은 지속적일 것입니다 -- 코드베이스의 변경을 모니터링하고 아키텍처 모델 업데이트를 실시간으로 제안합니다. 새 서비스를 추가하는 PR을 머지했나요? 시스템이 감지하고 C4 모델에 추가를 제안합니다.

행동 분석

현재 AI 분석은 구조적입니다: 코드에 무엇이 존재하는지 이해합니다. 미래 분석은 행동을 이해할 것입니다: 런타임에 컴포넌트가 어떻게 상호작용하는지, 어떤 데이터가 시스템을 통해 흐르는지, 오류가 어떻게 전파되는지. 이를 통해 정적 분석이 아닌 프로덕션 트래픽으로부터 생성된 동적 다이어그램이 가능해집니다.

교차 저장소 인텔리전스

대부분의 조직은 여러 저장소에 걸친 아키텍처를 가지고 있습니다. 미래의 AI 발견은 교차 저장소 의존성을 이해할 것입니다: 저장소 A의 이 서비스가 저장소 B의 저 서비스를 호출하고, 저장소 C에서 관리되는 이 데이터베이스에 쓴다. 전체 조직에 걸친 통합 아키텍처 모델입니다.

자가 치유 문서

궁극적 목표: 스스로 수정하는 문서. 드리프트가 감지되면, AI가 업데이트를 생성하고, 수정된 모델로 Pull request를 만들고, 인간 승인을 요청합니다. 인간의 역할이 문서 작성에서 AI가 제안한 업데이트의 검토로 전환됩니다 -- 훨씬 가벼운 작업입니다.

아키텍처 인식 코드 생성

AI 코딩 에이전트가 더 강력해지면서, 아키텍처 인식이 핵심이 됩니다. 아키텍처를 이해하는 에이전트는 다음을 수행할 수 있습니다:

확립된 패턴을 따르는 코드 생성
아키텍처 목표에 부합하는 리팩토링 제안
제안된 변경이 드리프트를 증가시킬 때 경고
코드 변경 시 아키텍처 모델 자동 업데이트

시작하기

모든 것을 한 번에 도입할 필요는 없습니다. 다음은 실용적인 진행 순서입니다:

1단계: 발견 (1일차)

저장소를 Archyl에 연결하고 AI 발견을 실행합니다. 생성된 C4 모델을 검토합니다. 명백한 실수를 수정합니다. 이제 약 70-80% 정확한 기준 아키텍처 모델을 갖게 됩니다.

2단계: 보강 (1주차)

AI가 발견할 수 없는 맥락을 추가합니다: 핵심 결정에 대한 ADR, 중요한 워크플로에 대한 문서, 아키텍처 제약에 대한 적합성 규칙. ADR을 영향을 받는 C4 요소에 연결합니다.

3단계: 드리프트 감지 (2주차)

드리프트 점수 GitHub Action을 설정합니다. 기준 점수를 설정하고 임계값을 지정합니다. 모든 push에서 드리프트 모니터링을 시작합니다.

4단계: MCP 통합 (3주차)

Archyl의 MCP 서버를 AI 코딩 도구에 연결합니다. 에이전트에게 아키텍처 맥락을 제공합니다. 에이전트가 아키텍처를 존중하는 코드를 생성하는 것을 확인합니다.

5단계: 거버넌스 (지속적)

적합성 규칙을 정의합니다. 드리프트 추세를 모니터링합니다. 분기별로 ADR을 검토하고 업데이트합니다. 아키텍처 문서화가 일회성 프로젝트가 아닌 살아 있는 관리 자산이 됩니다.

아키텍처 문서화의 미래는 더 나은 다이어그램을 그리는 것이 아닙니다. 문서가 스스로 생성하고, 스스로 유지하며, 인간과 AI 에이전트 모두에게 아키텍처 진실의 공유 소스로 기능하는 시스템을 구축하는 것입니다.

오늘부터 AI 기반 아키텍처 문서화를 시작하세요. Archyl 무료 체험 -- 저장소를 연결하고 몇 분 만에 아키텍처가 발견되는 것을 확인하세요. 더 알아보기: AI 기반 발견: 작동 방식 | 아키텍처 드리프트 점수 | MCP 서버: 아키텍처와 대화하기.

AI 기반 아키텍처 문서화: 미래가 도래하다 - Archyl Blog