AI로 아키텍처 문서를 쓰는 방법

아키텍처 문서는 여섯 섹션으로 이루어집니다. 맥락, 제약, 구성요소, 데이터 흐름, 결정, 위험입니다. AI는 PRD에서 구성요소와 데이터 흐름의 첫 초안을 쓰는 데, 각 결정 아래 대안을 나열하는 데, 그리고 나중에 쳐낼 위험 목록을 뽑는 데 유용합니다. 해로운 때는 제약 섹션을 채울 때입니다. 당신이 가진 적 없는 한계를 지어내고 그에 맞춰 설계하기 때문입니다. 제약과 결정은 직접 쓰고, 나머지는 에이전트가 초안을 쓰게 하며, 전체를 두 페이지 아래로 유지하세요.

이것은 Atrix에서 한 사이클보다 큰 모든 기능에 쓰는 템플릿이며, 에이전트와 엔지니어 사이의 분업은 둘 다 1년간 쓰고 나서 정착한 형태입니다.

아키텍처 문서의 쓸모

다음 사람을 위해 한 가지 질문에 답합니다. 왜 시스템이 이런 모양인가? 어떻게 운영하는지가 아니라(그건 런북), 사용자에게 무엇을 해 주는지도 아니라(그건 PRD), 어떤 조각이 존재하고, 데이터가 그 사이를 어떻게 움직이며, 어떤 선택이 우연이 아니라 의도로 이루어졌는지입니다.

독자는 여섯 달 뒤에 합류하는 엔지니어이거나 긴 휴식 뒤의 당신입니다. 10분 안에 읽을 수 없는 문서는 읽히지 않습니다. 두 페이지, 다이어그램 하나, 결정 표 하나.

여섯 섹션 템플릿

섹션	들어가는 내용	초안 작성자
맥락	기능을 두 문장으로; PRD 링크; 오늘 존재하는 것	에이전트, PRD에서
제약	엄격한 한계: 데이터 소재지, 지연 시간, 예산, 기존 계약, 팀 크기	사람만
구성요소	건드리는 조각과 일부러 건드리지 않는 조각	에이전트가 초안, 사람이 잘라냄
데이터 흐름	요청이나 레코드가 구성요소를 순서대로 어떻게 지나는가	에이전트가 초안, 사람이 코드와 대조
결정	중요한 선택마다: 검토한 옵션, 택한 것, 이유	사람이 결정; 에이전트가 대안 나열
위험	무엇이 잘못될 수 있는지, 가능성, 우리의 대응	에이전트가 나열, 사람이 다섯으로 줄임

"초안 작성자" 열이 이 글의 핵심입니다. 템플릿 자체는 평범하고, 분업이 AI를 위험하지 않고 유용하게 만듭니다.

맥락

두 문장과 링크 하나. 에이전트는 받은 문서를 요약하는 일이라 잘합니다. 오늘 존재하는 것을 명시하게 하세요. "리마인더는 없다. 캘린더 동기화와 이메일 발송기는 있다."

제약

설계가 지켜야 하는 엄격한 한계입니다. "고객 데이터는 EU 리전에 머문다." "이메일 공급자는 분당 100건으로 제한한다." "엔지니어 둘, 한 사이클." "다음 분기에 교체될 동기화 계층은 바꾸지 않는다."

이 섹션은 에이전트가 문서를 보기 전에 직접 쓰세요. 제약 초안을 요청받은 에이전트는 그럴듯한 것들을 만듭니다. "동시 사용자 1만 명 지원", "수평 확장 가능", "다중 리전 장애 조치 지원". 어느 것도 당신 것이 아닙니다. 문서에 들어가는 순간 구성요소 섹션이 그에 맞춰 설계되고, 하루에 이메일 40통을 보내는 기능을 위해 큐, 캐시, 예비 리전이 생깁니다.

구성요소

에이전트의 첫 초안은 보통 건드리는 조각들의 합리적인 목록입니다. 당신의 일은 잘라내는 것입니다. 지어낸 제약을 만족시키려고 추가한 구성요소를 빼고, 일부러 손대지 않는 부분에 "건드리지 않음: X, Y" 줄을 추가하세요. 검토자에게는 건드리는 목록보다 "건드리지 않음" 목록이 더 유용합니다.

데이터 흐름

번호 매긴 순서입니다. "1. 정각에 크론 실행. 2. 발송 플래그 없는 24시간 내 예약 조회. 3. 템플릿 렌더링. 4. 공급자로 발송. 5. 발송 표시." 에이전트가 PRD와 구성요소에서 초안을 쓰고, 당신이 각 단계를 기존 코드와 대조합니다. 버그 대부분은 2단계에 있고, 에이전트는 예약 테이블에 소프트 삭제 열이 있다는 것을 모릅니다.

결정

나중에 누군가 의문을 가질 만한 선택마다 한 줄: 옵션, 택한 것, 이유. 에이전트는 당신이 생각 못 한 옵션을 나열하는 데 능하고, 고르는 데는 서툽니다. 당신의 팀이나 역사를 모르기 때문입니다. 대안을 요청한 뒤 "택한 것"과 "이유" 칸은 직접 쓰세요. 세 줄에서 여섯 줄이 보통입니다. 열두 줄이라면 그 문서는 기능 두 개짜리입니다.

위험

에이전트는 열다섯 개를 나열합니다. 다섯 개만 남기고 각각 한 줄짜리 완화책을 붙이세요. 완화책 없는 위험은 걱정이지 위험이 아닙니다.

AI가 돕는 곳과 해치는 곳

돕는 곳:

PRD에서 맥락, 구성요소, 데이터 흐름의 첫 초안. 문서를 읽고 구조적으로 다시 말하는 일이며, 잘합니다.
각 결정 아래의 대안. "여기서 달리 뭘 할 수 있을까?"는 생각 못 했던 옵션 하나를 꾸준히 내놓습니다.
일관성 검사. "데이터 흐름의 모든 구성요소가 구성요소 섹션에 나오는가?"는 지친 사람이 놓치는 것을 잡습니다.
위험 브레인스토밍. 쳐내기만 한다면.

해치는 곳:

제약. 지어낸, 그럴듯한, 구조를 좌우하는 것. 위에서 다뤘습니다.
옵션 중 선택. 마감이 있는 두 명 팀에 맞는 답이 아니라 교과서적 답을 고릅니다.
현재 상태에 대한 주장. "기존 동기화 계층은 웹훅을 노출한다"고 하지만 실제로는 아닙니다. 에이전트가 오늘의 시스템에 대해 말하는 모든 것은 코드와 대조해야 합니다.
규모. 내버려 두면 당신의 규모가 아니라 학습 데이터의 규모에 맞춰 설계합니다.

우리가 쓰는 규칙: 에이전트는 받은 입력을 다시 말하는 것이라면 무엇이든 써도 된다. 세상에 대한 사실이나 선택은 사람이 쓴다.

Atrix에서 하기

우리 AI 에이전트는 당신이 준 브리프와 PRD로 Develop 실행의 세 산출물 중 하나로 요구사항, 계획된 이슈와 함께 아키텍처 문서를 만듭니다. 위의 분업을 따르는 이유는 우리가 그렇게 브리프하기 때문입니다. 실행의 브리프는 제약을 입력으로 명시하고, 에이전트에게는 거기에 추가하지 말라고 합니다. 문서는 Docs의 페이지로 들어가며 버전 기록, 댓글, 실시간 공동 편집이 있어서, 구성요소와 결정에 대한 엔지니어의 수정이 에이전트 초안과의 diff로 보입니다.

블록 다이어그램은 페이지 안의 화이트보드에 그립니다. Atrix의 화이트보드는 Excalidraw 보드입니다. 상자와 화살표를 손으로 그리고, 그림은 텍스트 옆에서 편집 가능한 상태로 남습니다. 텍스트에서 다이어그램을 생성하는 기능은 없습니다. 에이전트가 다이어그램을 만들게 하고 싶다면 번호 매긴 데이터 흐름을 요청하고 그것으로 그리세요. 구성요소 여섯 개짜리 기능이면 10분쯤 걸립니다. Miro의 AI나 Eraser의 DiagramGPT처럼 텍스트에서 다이어그램을 생성하는 도구는 별도의 글에서 다룹니다.

실제 사례, 요약

맥락: 예약 리마인더; PRD v3; 오늘 리마인더는 없고, 캘린더 동기화와 이메일 발송기는 있음.

제약(사람): 동기화 계층 변경 없음; 공급자 한도 분당 이메일 100건; 엔지니어 한 명, 한 사이클; EU 데이터만.

구성요소(에이전트 초안, 사람이 잘라냄): 리마인더 스케줄러(신규), 리마인더 템플릿(신규), 예약 조회(기존, 읽기 전용), 이메일 발송기(기존). 건드리지 않음: 동기화 계층, 캘린더 UI.

데이터 흐름: 앞서 나열한 다섯 단계, 테이블 확인 후 소프트 삭제된 예약을 제외하도록 2단계 수정.

결정: 크론 대 큐(크론; 하루 40건이고 큐는 운영해야 할 두 번째 시스템); 예약별 발송 대 일괄 발송(일괄, 공급자 한도 아래에 머물기 위해); 템플릿 저장(Docs의 페이지, 새 테이블 아님).

위험: 크론 겹침으로 중복 발송(완화: 발송 전에 발송 플래그 기록); 공급자 장애(완화: 다음 시간에 재시도, 한 시간 미만은 알림 없음); 시간대 실수(완화: UTC로 저장·비교, 예약의 시간대로 렌더링).

에이전트 초안은 스스로 쓴 확장성 제약을 만족시키려고 Redis 큐와 "알림 서비스"를 추가했었습니다. 둘 다 잘라냈고, 문서는 한 페이지 반에 들어갑니다.

자주 묻는 질문

아키텍처 문서에는 무엇이 들어가야 하나요?

여섯 섹션입니다. 맥락, 제약, 구성요소(건드리는 것과 건드리지 않는 것), 번호 매긴 순서의 데이터 흐름, 옵션과 이유가 있는 결정 표, 완화책이 있는 위험 다섯 개. 두 페이지와 다이어그램 하나가 목표입니다.

AI가 소프트웨어 아키텍처 문서를 쓸 수 있나요?

PRD에서 맥락, 구성요소, 데이터 흐름, 대안을 초안할 수 있고, 잘합니다. 제약을 쓰거나 결정을 내려서는 안 됩니다. 제약을 지어내고 교과서적 옵션을 고르기 때문입니다. 모든 사실과 선택에 사람 책임자가 있는 초안 도구로 다루세요.

아키텍처 문서와 ADR의 차이는 무엇인가요?

아키텍처 결정 기록(ADR)은 결정 하나를 다룹니다. 맥락, 옵션, 선택, 결과. 기능의 아키텍처 문서는 표에 여러 결정을 담고 그 주변에 구성요소와 데이터 흐름이 있습니다. 작은 팀은 보통 표를 문서 안에 두고, 둘 이상의 기능에 영향을 주는 줄만 별도 ADR로 승격합니다.

아키텍처 문서는 얼마나 길어야 하나요?

두 페이지, 10분 안에 읽을 수 있게. 더 길면 기능 두 개를 설명하거나 런북을 흡수한 것입니다. 운영 세부는 밖으로 빼세요.

아키텍처 문서에 다이어그램을 넣어야 하나요?

네, 주요 데이터 흐름을 화살표로 표시한 구성요소 블록 다이어그램 하나. 번호 매긴 데이터 흐름으로 손으로 그리세요. 10분이면 되고, 그리는 행위 자체가 빠진 화살표를 찾아냅니다.

아키텍처 문서는 언제 써야 하나요?

PRD가 고정된 뒤, 이슈가 만들어지기 전입니다. 구성요소 섹션이 작업이 어떻게 쪼개지는지를 결정하기 때문입니다. 이슈가 생긴 뒤에 쓰면 한 일에 대한 서술이 되는데, 그것은 다른 문서입니다.

다음 단계

지금 진행 중인 기능을 가져와 제약 섹션을 5분 동안 손으로 쓴 다음, PRD와 그 제약을 쓰고 있는 에이전트에게 넘기고 나머지 다섯 섹션을 요청하세요. PRD 템플릿은 에이전트에게 필요한 번호 매긴 요구사항을 주고, Atrix에서는 AI 에이전트의 Develop 실행이 팀과 함께 편집할 수 있는 페이지로 아키텍처 문서를 돌려줍니다.

AI로 아키텍처 문서를 쓰는 방법: 여섯 섹션 템플릿, AI가 돕는 곳, 제약을 지어내는 곳