아키텍처 문서에는 뭘 써야 할까 — AI 에이전트가 읽는 시대의 architecture.md

아키텍처 문서, 왜 다시 이야기하나

아키텍처 문서는 오래된 주제다. 그런데 2025-2026년 들어 이 문서의 독자가 달라졌다. 사람만 읽는 게 아니라, AI 코딩 에이전트도 읽는다. 그런데 에이전트가 아키텍처 문서를 "알아서 찾아 읽는" 건 아니다. 실제로는 다음과 같은 3단계를 거친다.

AI 에이전트가 프로젝트를 이해하는 과정

1단계: 도구가 하드코딩된 지침 파일을 읽는다. 각 도구는 프로젝트 루트에서 자신만의 설정 파일을 자동으로 로딩한다. 이건 LLM의 학습이 아니라 도구 프레임워크의 동작이다.

도구	자동 로딩 파일
Claude Code	CLAUDE.md
Cursor	.cursorrules, .cursor/rules/
Cline	.clinerules (파일 또는 디렉토리)

2단계: 에이전트가 탐색을 시작한다. 사용자가 "이 프로젝트 파악해줘"라고 하면, 에이전트는 README.md, docs/ 같은 일반적인 위치를 탐색한다. 하지만 docs/architecture.md를 반드시 발견한다는 보장은 없다.

3단계: 지침 파일에서 참조해야 확실히 찾는다. CLAUDE.md나 .clinerules에 "아키텍처는 docs/architecture.md 참고"라고 적혀 있으면 에이전트는 확실하게 찾아간다. 연결고리가 있어야 아키텍처 문서가 빛을 발한다.

사람은 다이어그램을 훑고 대충 감을 잡는다. AI 에이전트는 텍스트를 정밀하게 읽되, 명시되지 않은 것은 모른다. "이 정도는 코드 보면 알겠지"가 사람에게는 통하지만, AI에게는 통하지 않는다. 그래서 아키텍처 문서에 뭘 담느냐가 AI와의 협업 품질을 좌우하게 되었다.

이 글에서는 실제 사이드 프로젝트에 작성한 architecture.md를 바탕으로, 아키텍처 문서에 어떤 내용이 담겨야 하는지를 정리한다. 각 항목이 왜 LLM에게 중요한지도 함께 설명한다.

1. 시스템 전체 구조도 (High-Level Diagram)

아키텍처 문서의 첫 번째 항목은 전체를 한눈에 보여주는 다이어그램이다. Mermaid나 PlantUML로 그린 블록 다이어그램이 가장 흔하다. 포함해야 할 것:

• 주요 컴포넌트(모듈, 서비스)와 이름
• 컴포넌트 간 데이터 흐름 방향
• 외부 시스템과의 연결점
• 서브시스템 경계 (subgraph)

예를 들어, 사진 파이프라인 프로젝트라면 이런 구조다:

사진 저장소 → 추출 → 필터링 → 그룹핑 → 내러티브 생성 → 렌더링(HTML/영상)

왜 LLM에게 중요한가: AI 에이전트는 코드를 파일 단위로 읽는다. 전체 구조도 없이는 "이 파일이 파이프라인의 어느 단계인지", "이 모듈의 출력을 누가 소비하는지"를 알 수 없다. 구조도가 있으면 에이전트는 수정 요청을 받았을 때 영향 범위를 정확히 판단할 수 있다. "grouper.py를 수정하면 narrator.py의 입력이 바뀐다"는 것을 코드 분석 없이 알 수 있다.

2. 레이어 구분 (Layer Architecture)

대부분의 프로젝트는 몇 개의 레이어로 나뉜다. 명시적으로 정리하면 코드의 책임 구조가 드러난다:

레이어	역할	예시
Data Layer	데이터 저장, 캐시, 외부 소스 연동	DB 클라이언트, JSON 캐시 파일, API 클라이언트
Processing Layer	핵심 비즈니스 로직, 데이터 변환	파이프라인 모듈, 알고리즘, LLM 호출
Presentation Layer	결과물 출력, 사용자 인터페이스	웹 서버, HTML 렌더러, CLI

왜 LLM에게 중요한가: 에이전트에게 "DB 연결 방식을 바꿔줘"라고 하면, Data Layer에 해당하는 파일만 수정하면 된다는 것을 즉시 알 수 있다. 레이어 구분이 없으면 에이전트는 모든 파일을 탐색해야 하고, 엉뚱한 곳을 건드릴 확률이 높아진다. 특히 의존 방향(Data → Processing → Presentation)을 명시하면 "하위 레이어 변경이 상위에 영향을 주는지"를 판단하는 데 결정적인 단서가 된다.

3. 데이터 모델 (Data Model)

시스템 내부에서 주고받는 핵심 데이터 구조를 정의한다. 클래스 다이어그램이나 테이블 형태로 표현할 수 있다:

• 주요 엔티티 이름과 필드
• 엔티티 간 관계 (1:N, N:M 등)
• 핵심 메서드나 변환 로직

예를 들어 사진 프로젝트라면, "개별 사진(PhotoRecord)"과 "이벤트 그룹(PhotoEvent)"이 1:N 관계이고, 각각 어떤 필드를 가지는지를 정리하는 것이다.

왜 LLM에게 중요한가: AI 에이전트가 새 기능을 추가할 때 가장 먼저 확인하는 것이 "이 데이터에 어떤 필드가 있는가"다. 데이터 모델이 문서화되어 있으면 에이전트는 기존 필드를 활용할지, 새 필드를 추가할지를 정확하게 판단한다. 문서가 없으면 코드 전체를 grep하면서 추측해야 하고, 동일한 정보를 중복으로 저장하는 실수를 하기 쉽다.

4. 외부 의존성 (External Dependencies)

프로젝트가 의존하는 외부 시스템을 표로 정리한다:

의존성	용도	연결 방식
PostgreSQL	사용자 데이터 저장	SQL (환경변수 DATABASE_URL)
Redis	캐시, 세션	TCP (REDIS_URL)
OpenAI API	텍스트 생성	REST API (OPENAI_API_KEY)
S3	파일 저장	AWS SDK (AWS_* 환경변수)

왜 LLM에게 중요한가: 외부 의존성 목록이 없으면 AI 에이전트는 로컬에서 완결되는 로직과 외부 호출이 필요한 로직을 구분하지 못한다. "이 함수가 실패하는 이유"를 진단할 때 외부 API가 관여하는지 아닌지를 아는 것은 디버깅의 출발점이다. 또한 연결 방식(환경변수명)을 명시해두면 에이전트가 설정 파일을 수정할 때 올바른 변수명을 사용한다.

5. 설정 관리 (Configuration)

환경변수와 주요 상수를 한 곳에 정리한다:

• 환경변수 이름, 기본값, 설명
• 매직 넘버의 의미 (예: EVENT_GAP_HOURS = 48 → "48시간 이상 간격이면 별도 이벤트로 분리")
• 설정 파일의 위치 (예: config.py, .env)

왜 LLM에게 중요한가: 코드 안에 흩어진 매직 넘버는 AI 에이전트가 발견하기 어렵다. 설정 목록이 있으면 "이벤트 분리 기준을 24시간으로 바꿔줘"라는 요청에 에이전트가 정확히 어떤 값을 어디서 바꿔야 하는지 즉시 파악한다. 환경변수 기본값이 명시되어 있으면 로컬 개발 환경 설정도 에이전트가 도와줄 수 있다.

6. 추가로 다룰 수 있는 항목들

위 5가지가 핵심이지만, 프로젝트 성격에 따라 다음 항목을 추가하면 문서의 가치가 올라간다:

에러 처리 전략

"외부 API 실패 시 재시도 3회 후 캐시 폴백", "GPU 선점 시 중간 결과를 체크포인트로 저장" 같은 에러 처리 규칙. LLM은 에러 처리 전략이 명시되어 있지 않으면 자기 나름의 에러 핸들링을 만들어버리는데, 이게 프로젝트의 기존 패턴과 충돌하는 경우가 많다.

캐시 전략

어떤 데이터가 캐시되고, 캐시 파일의 위치와 갱신 조건이 무엇인지. 예를 들어 narrative_cache.json은 LLM이 생성한 결과를 저장하고, 동일 입력에 대해 재호출을 방지한다. 이 정보가 없으면 에이전트가 매번 LLM을 호출하는 비효율적인 코드를 작성할 수 있다.

보안 경계

API 키가 어떻게 관리되는지, 어떤 엔드포인트가 인증을 요구하는지. AI 에이전트가 새 API 연동 코드를 작성할 때 기존 인증 패턴을 따르게 하려면 이 정보가 필요하다.

성능 제약

"사진 1만 장 처리 시 40분 소요", "GPU 메모리 16GB 제한으로 배치 크기 최대 32" 같은 실측 데이터. 에이전트가 성능 최적화를 시도할 때, 현실적인 제약을 인지하고 있어야 실현 가능한 개선안을 제시한다.

배포/실행 방법

로컬 실행 커맨드, Docker 설정, 환경별 차이 등. 에이전트가 "이 프로젝트를 실행해봐"라는 요청을 받았을 때 어떤 명령을 실행해야 하는지 알 수 있게 한다.

아키텍처 문서 작성 체크리스트

정리하면, 아키텍처 문서는 이 질문들에 답할 수 있어야 한다:

항목	핵심 질문	LLM에게 주는 효과
전체 구조도	시스템이 무엇으로 구성되어 있나?	수정 영향 범위 파악
레이어 구분	각 모듈의 책임이 무엇인가?	올바른 파일에 코드 배치
데이터 모델	시스템 내부에서 어떤 데이터가 흐르나?	기존 필드 활용, 중복 방지
외부 의존성	외부와 어떻게 연결되나?	로컬/외부 로직 구분, 디버깅 기점
설정 관리	조정 가능한 값은 어디에 있나?	정확한 설정 변경 위치 파악

사람을 위한 문서에서 AI를 위한 문서로

전통적인 아키텍처 문서(IEEE 1471, ADD 등)는 이해관계자 분석, 품질 속성 시나리오, 아키텍처 평가 같은 항목을 포함한다. 이것들은 팀 프로젝트나 엔터프라이즈 환경에서는 여전히 유효하다.

하지만 사이드 프로젝트나 소규모 팀에서는 실용적인 5가지 항목만으로 충분하다. 중요한 것은 분량이 아니라, AI 에이전트가 프로젝트를 이해하고 올바른 판단을 내리는 데 필요한 최소한의 맥락을 제공하는 것이다.

코드는 "무엇(what)"을 말해주고, 커밋 로그는 "언제(when)"를 말해주지만, "어떻게 연결되어 있는가(how)"와 "왜 이렇게 나눴는가(why)"는 아키텍처 문서만이 말해줄 수 있다. 그리고 이것이 바로 AI 에이전트가 코드만으로는 추론할 수 없는 것이다.

---

이 글은 생성형 AI의 도움을 받아 작성되었습니다. 원본 자료를 기반으로 AI가 초안을 생성하고, 작성자가 검토·편집하였습니다.