소프트웨어 아키텍처 문서 템플릿 (무료)
아키텍처 문서는 보통 이렇게 쓰입니다. 새 엔지니어가 합류해 시스템이 어떻게 맞물려 있는지 묻고, 누군가 "제대로 정리해 두겠다"고 약속합니다. 그 사람은 소프트웨어 아키텍처 문서 템플릿을 검색해 2012년에 만든 40쪽짜리 Word 파일이나 대학 PDF를 찾아내고, 절반쯤 채운 뒤 다시는 열지 않습니다. 1년 뒤, 다음 신입이 그 문서를 발견하고, 믿고, 잘못 이해합니다.
문제는 템플릿이 없어서인 경우가 드뭅니다. 모든 것을 요구하는 템플릿 때문에 아무것도 완성되지 않고, 소유자가 없는 문서 때문에 아무것도 업데이트되지 않는 것이 문제입니다. 아래 템플릿은 일부러 간결하게 만들었습니다. Markdown 파일 하나, 섹션 아홉 개, 각 섹션은 그것을 읽을 누군가가 필요로 하기 때문에 존재합니다. 리포지토리에 복사하세요. 가입도, 다운로드도 필요 없습니다. 그런 다음 각 부분에 무엇을 써야 하는지, 그리고 어떻게 낡지 않게 유지하는지에 대한 섹션별 설명을 읽어 보세요.
아키텍처 문서는 무엇을 위한 것인가 (그리고 누가 읽는가)
아키텍처 문서는 코드로는 빠르게 답할 수 없는 질문에 답합니다. 시스템은 무엇을 위한 것인지, 무엇과 통신하는지, 어떻게 나뉘어 있는지, 왜 그렇게 나뉘었는지, 그리고 무엇이 취약하다고 알려져 있는지. 기능 하나를 위한 설계 명세도 아니고, API 레퍼런스도 아닙니다.
독자는 다섯 부류이며, 이들을 하나하나 떠올리며 쓰면 도움이 됩니다:
| 독자 | 문서에서 필요로 하는 것 | 읽게 될 섹션 |
|---|---|---|
| 입사 첫 주의 새 엔지니어 | 무엇이 어디에 있고 요청이 어떻게 흐르는지 | 컨텍스트, 컨테이너, 핵심 흐름, 용어집 |
| 설계 변경을 검토하는 리뷰어 | 변경이 무엇을 건드리는지, 무엇이 이미 결정되었는지 | 컨테이너, 결정, 품질 목표 |
| 새벽 3시의 온콜 엔지니어 | 무엇이 무엇에 의존하는지, 무엇이 잘 깨지는지 | 컨테이너, 핵심 흐름, 리스크 |
| 감사인 또는 보안 검토 | 경계, 데이터 흐름, 외부 당사자 | 컨텍스트, 제약, 결정 |
| 1년 뒤의 여러분 | 왜 이렇게 했는지 | 결정, 리스크 |
문서의 어떤 섹션이 이들 중 누구에게도 쓸모가 없다면 삭제하세요. 이 규칙이 어떤 템플릿보다도 문서 품질에 크게 기여합니다.
이름에 대해 한마디: "아키텍처 문서", "시스템 설계 문서"(SDD), "소프트웨어 아키텍처 문서"(SAD)는 거의 같은 것을 가리키는 데 쓰입니다. SDD 템플릿은 보통 프로젝트나 기능 단위로 작성되며 상세 설계를 포함하는 경향이 있습니다. 아키텍처 문서는 시스템을 있는 그대로 기술하고 시스템과 함께 바뀝니다. 여기서 소개하는 템플릿은 후자입니다.
템플릿 (Markdown 블록 하나)
이것을 docs/architecture.md(또는 루트의 ARCHITECTURE.md)에 복사해서 채우세요. 꺾쇠괄호 안의 내용은 모두 자리표시자입니다. 해당하지 않는 섹션은 비워 두지 말고 삭제하세요.
# <시스템 이름>: 아키텍처
| | |
|---|---|
| 소유자 | <이 문서를 정확하게 유지할 책임이 있는 팀 또는 사람> |
| 마지막 검토 | <YYYY-MM-DD> |
| 다음 검토 | <YYYY-MM-DD, 또는 "섹션 3~5가 바뀔 때마다"> |
| 상태 | <초안 / 최신 / X로 대체 중> |
## 1. 컨텍스트와 범위
<두세 문장으로: 시스템이 무엇을 하는지, 누구를 위한 것인지, 왜 존재하는지.>
**사용자**
- <역할>: <그 사용자가 시스템으로 하는 일>
**외부 시스템**
- <시스템>: <주고받는 것, 프로토콜>
**범위 밖**
- <사람들이 이 시스템이 한다고 여기지만 실제로는 하지 않는 것>
**시스템 컨텍스트 다이어그램 (C4 레벨 1)**
<링크 또는 임베드. 시스템을 상자 하나로, 모든 종류의 사용자와 모든 외부 시스템을 함께.>
## 2. 품질 목표
서로 충돌할 때 우선하는 세 개에서 다섯 개의 품질 속성, 우선순위 순.
| 우선순위 | 품질 속성 | 구체적인 시나리오 |
|---|---|---|
| 1 | <예: 가용성> | <예: 추천 서비스가 다운되어도 결제는 계속 동작한다> |
| 2 | <예: 지연 시간> | <예: 분당 주문 500건에서 결제 p95가 2초 미만> |
| 3 | <예: 변경 용이성> | <예: 주문 서비스를 건드리지 않고 새 결제 수단을 출시할 수 있다> |
## 3. 제약
우리가 선택하지는 않았지만 감수해야 하는 것들.
- <예: 회사의 Kubernetes 플랫폼에서 실행한다>
- <예: 고객 데이터는 EU 안에 둔다>
- <예: 백엔드 서비스는 Go 또는 Java만 사용한다>
## 4. 아키텍처
**컨테이너 다이어그램 (C4 레벨 2)**
<링크 또는 임베드. 모든 배포 단위와 데이터 저장소를 기술과 프로토콜과 함께.>
| 컨테이너 | 기술 | 책임 | 소유자 |
|---|---|---|---|
| <웹 앱> | <React SPA> | <하는 일> | <팀> |
| <API> | <Go> | <하는 일> | <팀> |
| <데이터베이스> | <PostgreSQL> | <저장하는 것> | <팀> |
**컴포넌트 다이어그램 (C4 레벨 3)**
<새로 합류한 사람이 어려워할 한두 개의 컨테이너에 대해서만. 링크 또는 임베드.>
**핵심 흐름**
<가장 중요한 두세 개의 시나리오를 번호 붙인 단계 또는 C4 동적 다이어그램으로.>
1. <액터> -> <컨테이너>: <일어나는 일>
2. <컨테이너> -> <컨테이너>: <일어나는 일, 프로토콜, 동기 또는 비동기>
## 5. 핵심 결정
전체 기록은 <docs/adr/>에 있습니다. 여기는 색인입니다.
| ADR | 결정 | 상태 | 날짜 |
|---|---|---|---|
| [ADR-001](adr/001-<slug>.md) | <예: 서비스마다 데이터베이스 하나> | 승인됨 | <YYYY-MM-DD> |
| [ADR-002](adr/002-<slug>.md) | <예: 주문 이벤트에 Kafka 사용> | 승인됨 | <YYYY-MM-DD> |
## 6. 횡단 관심사
모든 컨테이너가 관련된 것들을 시스템 전체가 어떻게 다루는지. 각각 한두 줄로, 상세 내용 링크와 함께.
- **인증과 인가:** <어디서 이루어지는지, 어떤 토큰인지>
- **옵저버빌리티:** <로그, 메트릭, 트레이스, 어디를 보면 되는지>
- **오류 처리와 재시도:** <컨벤션, 멱등성>
- **데이터와 개인정보:** <개인정보 위치, 보관 기간>
## 7. 배포와 운영
- **환경:** <프로덕션, 스테이징, ...>과 그 차이
- **실행 위치:** <클라우드, 리전, 클러스터>
- **런북:** <링크>
- **대시보드와 알림:** <링크>
## 8. 리스크와 기술 부채
| 리스크 또는 부채 | 현실화될 때의 영향 | 계획 | 소유자 |
|---|---|---|---|
| <예: 결제 전에 재고를 예약하며 보상 처리가 없음> | <결제 실패 후 유령 예약이 남음> | <실패 시 해제 로직 추가, 4분기> | <팀> |
## 9. 용어집
| 용어 | 여기서의 의미 |
|---|---|
| <주문> | <비즈니스에서 쓰는 의미 그대로의 정의> |
템플릿은 이게 전부입니다. 컨테이너가 열 개 정도인 시스템으로 채우면 보통 몇 쪽 분량입니다. 그보다 훨씬 길어진다면, 그 안의 무언가는 이 문서가 아니라 링크된 다른 문서에 속할 가능성이 큽니다.
섹션별 설명
헤더: 소유자와 검토 날짜
맨 위 네 줄은 그 아래 어떤 섹션보다 중요합니다. 소유자는 문서가 틀렸을 때 누가 고치는지 말해 줍니다. 마지막 검토는 독자에게 문서를 얼마나 믿어도 되는지 알려 줍니다. "마지막 검토: 14개월 전"이라고 적힌 문서는 정직합니다. 아무것도 적혀 있지 않은 문서는 최신이 아닌데도 최신처럼 보입니다.
1. 컨텍스트와 범위
여기서 시작하세요. 다른 모든 섹션이 경계에 의존하기 때문입니다. 모든 종류의 사용자와 모든 외부 시스템을 나열하세요. 당연하게 여기는 것(ID 제공자, 이메일 서비스, 결제 게이트웨이)도 포함해서요. 범위 밖 목록은 문서의 다른 어떤 부분보다 많은 회의를 줄여 줍니다. 모두가 이 시스템이 환불을 처리한다고 생각하더라도 실제로는 하지 않는다는 사실을 적어 두는 곳입니다.
다이어그램은 C4 시스템 컨텍스트 다이어그램입니다. 여러분의 시스템을 상자 하나로 두고, 그 주위에 사용자와 외부 시스템을 배치하고, 레이블 붙은 화살표로 연결합니다. 무엇이 들어가야 하는지는 System Context 다이어그램 가이드에서 다룹니다.
2. 품질 목표
대부분의 아키텍처 문서는 이 섹션을 건너뛰지만, 나머지 전부를 설명해 주는 섹션이 바로 이것입니다. "일관성보다 가용성" 또는 "원초적 성능보다 변경 용이성"이라고 적혀 있으면, 독자는 컨테이너가 왜 그런 모양인지 이해합니다. 목표는 세 개에서 다섯 개로 제한하고, 순위를 매기고, 각각에 테스트할 수 있을 만큼 구체적인 시나리오를 붙이세요. 숫자, 부하, 장애.
3. 제약
제약은 다른 누군가가 내린 결정입니다. 플랫폼 팀, 법무팀, 회사의 언어 정책. 적어 두면 "왜 그냥 X를 쓰지 않았어요?"라는 대화가 사라지고, 미래의 독자에게 어떤 선택은 다시 검토할 수 있고 어떤 것은 그럴 수 없는지 알려 줍니다.
4. 아키텍처: C4 다이어그램
대부분의 사람이 "아키텍처"라고 하면 떠올리는 섹션입니다. C4 모델을 쓰세요. 각 다이어그램에 하나의 역할을 주기 때문입니다:
- 컨테이너 다이어그램 (레벨 2), 항상. 모든 배포 단위와 데이터 저장소를 각각의 기술과 함께, 각 화살표에는 프로토콜을 적어 그립니다. 다이어그램을 하나만 그린다면 이것을 그리세요. Container 다이어그램 가이드에 실습 예제가 있습니다.
- 컴포넌트 다이어그램 (레벨 3), 선별적으로. 새로 합류한 사람이 어려워할 컨테이너에 대해서만.
- 핵심 흐름. 두세 개의 시나리오를 번호 붙인 단계로. 정적 다이어그램은 두 컨테이너가 통신한다는 것을 보여 주고, 흐름은 그것이 어떤 순서로 일어나며 사용자가 어떤 단계를 기다리는지 보여 줍니다. 작성 방법은 C4 Dynamic 다이어그램 가이드에서 볼 수 있습니다.
컨테이너 표에 소유자 열이 있는 것은 의도적입니다. 아무도 소유하지 않은 컨테이너는 이 문서에서도 아무도 업데이트하지 않을 컨테이너입니다.
C4가 처음이라면 C4 모델이란 무엇인가에서 네 가지 레벨을 설명합니다. 이런 다이어그램을 실제 대규모 시스템에 적용한 예는 C4 모델 예제를 보세요.
5. 핵심 결정 (ADR)
결정을 본문에 직접 쓰지 마세요. 각 결정을 별도 파일의 아키텍처 결정 기록(컨텍스트, 결정, 검토한 대안, 결과)으로 남기고, 여기에는 색인만 두세요. ADR은 한 번 쓰고 나면 수정하지 않고 새 ADR로 대체하므로, 문서는 짧게 유지되고 이력은 온전히 남습니다. 형식과 어떤 결정이 ADR을 가질 만한지는 아키텍처 결정 기록 완벽 가이드에서 다룹니다.
색인을 점검하는 좋은 테스트가 있습니다. 새 엔지니어가 섹션 4의 의외인 상자 아무거나 가리켰을 때, 그것을 설명하는 ADR을 찾을 수 있어야 합니다.
6. 횡단 관심사
어느 한 컨테이너에 속하지 않는 것들이 있습니다. 인증, 로깅, 오류 처리, 개인 데이터가 있는 위치. 각각 한두 줄과 상세 링크면 충분합니다. 감사인이 가장 많은 시간을 보내는 섹션이니, 보기 쉽게 만들어 두세요.
7. 배포와 운영
짧게 쓰고 외부로 링크하세요. 환경과 그 차이, 시스템이 실행되는 곳, 그리고 런북과 대시보드 링크. 상세 내용은 인프라 코드와 런북에 속하며, 그것들은 이 문서보다 더 자주 바뀌어야 합니다.
8. 리스크와 기술 부채
정직함의 섹션입니다. 취약하다고 알려진 것을 소유자와 계획과 함께 적으세요. 계획이 "수용함, 3분기에 재검토"라도 괜찮습니다. 적어 둔 리스크는 누군가 우선순위를 매길 수 있는 리스크입니다. 한 엔지니어의 머릿속에만 있는 리스크는 그 사람과 함께 떠납니다.
9. 용어집
모든 시스템에는 그곳에서만 특정한 의미를 갖는 단어가 있습니다. "주문"과 "장바구니", "계정"과 "테넌트", "풀필먼트". 각각 한 번씩 정의하세요. 새 엔지니어는 생각보다 이 섹션을 많이 읽습니다.
arc42와의 관계
이 템플릿이 익숙해 보인다면, Peter Hruschka와 Gernot Starke가 만든 무료 오픈소스 아키텍처 문서 템플릿인 arc42와 같은 아이디어를 간결하게 추린 것이기 때문입니다. arc42에는 열두 개의 섹션이 있으며, arc42 스스로도 "이해관계자에게 필요한 것만" 문서화하라고 권합니다(arc42 FAQ, B-1). 대응 관계는 다음과 같습니다:
| 이 템플릿 | arc42 섹션 |
|---|---|
| 1. 컨텍스트와 범위 | 1 Introduction and Goals (목적), 3 Context and Scope |
| 2. 품질 목표 | 1 Introduction and Goals (품질 목표), 10 Quality Requirements |
| 3. 제약 | 2 Constraints |
| 4. 아키텍처 | 4 Solution Strategy (간단히), 5 Building Block View, 6 Runtime View |
| 5. 핵심 결정 | 9 Architecture Decisions |
| 6. 횡단 관심사 | 8 Crosscutting Concepts |
| 7. 배포와 운영 | 7 Deployment View |
| 8. 리스크와 기술 부채 | 11 Risks and Technical Debt |
| 9. 용어집 | 12 Glossary |
arc42의 전체 구조가 필요할 때는 arc42를 선택하세요. 규제가 있는 환경, 아키텍트가 여럿인 대규모 시스템, 이미 arc42를 표준으로 삼는 조직이 그렇습니다. 대안이 아예 문서가 없는 것이라면 이 정도 크기의 것을 선택하세요. 어떤 C4 다이어그램이 arc42의 어느 섹션에 들어가는지를 포함한 자세한 비교는 arc42 vs C4를 참고하세요.
낡지 않게 유지하기
모든 아키텍처 문서는 병합되는 날에는 정확합니다. 여섯 달 뒤에도 정확할지는 몇 가지 습관에 달려 있고, 그 대부분은 다이어그램에 관한 것입니다. 현실이 가장 빠르게 바뀌는 곳이 섹션 4와 5이기 때문입니다.
리포지토리에 두세요. 코드 옆에 docs/architecture.md가 있으면, 서비스를 분리하는 풀 리퀘스트가 같은 리뷰에서 컨테이너 표도 업데이트할 수 있습니다. 위키 페이지는 코드 리뷰의 일부가 될 수 없습니다.
스크린샷을 붙이지 말고 다이어그램에 링크하세요. 컨테이너 다이어그램 스크린샷은 컨테이너 이름이 바뀌는 순간 낡습니다. 모델(Structurizr DSL, YAML 모델, 또는 모델을 보관하는 도구)에서 렌더링한 다이어그램은 모델이 낡은 만큼만 낡습니다.
검토 날짜를 실제로 활용하세요. 컨테이너가 추가되거나 제거될 때 돌아가는 체크리스트에 이 문서를 넣으세요. 풀 리퀘스트 템플릿, 아키텍처 리뷰, 분기 계획 등입니다. "다음 검토: 섹션 3~5가 바뀔 때마다"도 유효한 항목입니다.
결정은 앞으로 써 나가세요. 승인된 ADR은 절대 수정하지 마세요. 대체하세요. 그러면 섹션 5의 색인이 이력을 보여 주고, 그것이 사람들에게 가장 필요한 부분입니다.
구조에 관한 부분은 자동으로 검사하세요. 섹션 1과 4는 코드에 존재하는 것들, 즉 서비스, 데이터 저장소, 의존성을 기술합니다. 이것들은 리포지토리와 대조할 수 있습니다. 섹션 2, 6, 8은 그럴 수 없으며, 정해진 일정에 따라 사람이 검토해야 합니다. 앞의 것들을 위한 방법과, 각 방법이 무엇을 볼 수 있고 무엇을 볼 수 없는지는 아키텍처 드리프트 감지 가이드에서 다룹니다.
archyl은 문서의 다이어그램 절반에 대해 바로 이 문제를 풀기 위해 만들어졌습니다. 리포지토리를 연결하면 AI 발견이 C4 모델(시스템, 컨테이너, 컴포넌트, 관계)을 제안하고, 여러분은 그리는 대신 검토하고 승인합니다. ADR, 문서, 플로우는 그것들이 설명하는 요소에 연결됩니다. 그런 다음 드리프트 점수가 문서화된 요소가 여전히 코드에 존재하는지를, 결정론적으로 그리고 중간에 AI 없이 검사하므로, 낡은 섹션 4가 뜻밖의 사고가 아니라 숫자로 드러납니다. 품질 목표나 리스크 목록은 검사하지 않으므로, 그것들에는 여전히 검토 날짜가 필요합니다. 도구가 있든 없든 문서를 최신으로 유지하는 실천 방법은 살아 있는 아키텍처 문서를 참고하세요.
자주 묻는 질문
소프트웨어 아키텍처 문서에는 무엇이 들어가야 하나요?
최소한 시스템의 컨텍스트와 범위(사용자와 외부 시스템), 기술을 표시한 컨테이너 수준 다이어그램, 이유를 포함한 핵심 아키텍처 결정, 알려진 리스크, 그리고 소유자와 검토 날짜입니다. 위 템플릿은 여기에 품질 목표, 제약, 횡단 관심사, 배포 메모, 용어집을 모두 짧게 더합니다.
이 템플릿은 정말 무료인가요?
네. 위의 Markdown 블록이 그것입니다. 복사해서 여러분의 시스템에 맞게 고치세요. 가입도, 다운로드도, 이메일도 필요 없습니다.
아키텍처 문서는 어디에 두어야 하나요?
리포지토리 안에 docs/architecture.md 또는 ARCHITECTURE.md로, docs/adr/의 ADR 옆에 두세요. 그러면 아키텍처 변경과 문서 변경이 같은 풀 리퀘스트를 거칩니다.
아키텍처 문서는 얼마나 길어야 하나요?
독자의 질문에 답하면서도 가능한 한 짧게. 컨테이너가 열 개 정도인 시스템이라면 몇 쪽이 보통입니다. 그보다 훨씬 길어지면 상세 내용은 링크된 문서(런북, ADR, API 레퍼런스)로 옮기고, 이 문서는 지도로 유지하세요.
시스템 설계 문서와는 무엇이 다른가요?
시스템 설계 문서는 보통 하나의 프로젝트나 기능을 위해, 만들기 전에 작성되며 상세 설계를 포함합니다. 아키텍처 문서는 현재 있는 그대로의 시스템 전체를 기술하고 시스템과 함께 바뀝니다. 팀은 흔히 시스템마다 아키텍처 문서 하나를 두고, 그 수명 동안 많은 설계 문서를 쓰며, 설계 문서의 오래 남을 결정은 결국 ADR이 됩니다.
대신 arc42를 써야 하나요?
arc42의 전체 구조가 필요하거나 조직이 이미 arc42를 쓰고 있다면 그렇습니다. 이 템플릿은 arc42의 섹션에 대응되므로(위의 표 참고), 여기서 시작해 나중에 아무것도 다시 쓰지 않고 arc42로 확장할 수 있습니다.
섹션 4의 다이어그램을 기억이 아니라 코드에서 만들고 싶으신가요? Developer 플랜으로 archyl을 무료로 사용해 보세요. 신용카드는 필요 없습니다. 더 읽어 보기: arc42 vs C4 | Architecture Decision Records: 완벽 가이드 | C4 모델이란? | 살아 있는 아키텍처 문서 | 아키텍처 드리프트 감지.