기획 문서의 종류와 체계 (3): TRD·ADR·API Spec과 검증

이 글은 [기획 문서의 종류와 체계] 3부작의 마지막 편인 3편입니다. 1편에서는 '왜 만드나'(발견)와 '무엇을 만드나'(정의)를, 그 중심에 있는 PRD(Product Requirements Document, 제품 요구사항 문서)를 다뤘습니다. 2편에서는 '어떻게 생겼나'(설계)를 IA(Information Architecture, 정보 구조)와 와이어프레임, 그리고 한국 현업의 화면설계서를 통해 살펴봤습니다. 이제 남은 질문은 두 개입니다. 어떻게 구현하나, 그리고 잘 됐나.

한동안 저는 기획 문서란 기획자나 PM이 쓰는 것이고, 개발자는 그것을 받아 코드로 옮기는 사람이라고 막연히 생각했습니다. 그런데 무언가를 직접 처음부터 만들어 보면, 정작 가장 많은 문서를 쓰게 되는 사람이 개발자라는 것을 깨닫게 됩니다. 이번 편에서 다룰 기술과 검증 단계의 문서들은 대부분 개발자가 직접 쓰는 기획 문서입니다. 기획은 비개발자의 일이라는 오해가 가장 선명하게 깨지는 지점이 바로 여기라는 생각이 들었습니다.

4단계 — 기술(Tech): 어떻게 구현하나

설계까지 끝나면 '무엇을, 어떤 화면으로' 만들지는 정해집니다. 다만 '그것을 기술적으로 어떻게 구현할 것인가'는 아직 빈칸으로 남아 있습니다. 이 빈칸을 코드로 곧장 메우기 전에, 글로 한 번 먼저 메우는 단계가 기술 문서입니다. 돌이켜 생각해보면, 구현 전에 글로 정리하며 발견한 허점이 코드를 절반쯤 짜고 나서 발견한 허점보다 훨씬 고치기 쉬웠습니다.

PRD가 '무엇을 만드나'에 답한다면, TRD(Technical Requirements Document, 기술 요구사항 문서)는 '그것을 기술적으로 어떻게 만드나'에 답합니다. Tech Spec(Technical Specification)이나 Design Doc(Design Document)이라 부르기도 하는데, 특히 Design Doc은 구글의 엔지니어링 문화에서 핵심 산출물로 널리 알려져 있습니다. 이름은 달라도 목적은 같습니다. 구현에 들어가기 전에 접근 방식을 글로 적고, 팀의 리뷰를 받는 것입니다.

TRD에서 가장 중요한 섹션은 의외로 결론이 아니라 대안 비교라는 생각이 듭니다. 방법 A, B, C를 나란히 놓고 각각의 트레이드오프를 적은 다음, 왜 그중 하나를 골랐는지를 남기는 것입니다. 이 과정이 빠지면 TRD는 그저 '내가 짤 코드를 미리 적어 둔 문서'가 되어 버립니다.

시스템이 커지면 글만으로는 구조가 한눈에 들어오지 않습니다. 이때 아키텍처 다이어그램이 필요합니다. 서비스와 컴포넌트가 어떻게 연결되는지를 그림으로 합의하는 것인데, 너무 막연하거나 너무 빽빽해지기 쉬운 도구이기도 합니다. 이 균형을 잡는 데 C4 모델이 도움이 됩니다. C4는 Context(맥락), Container(컨테이너), Component(컴포넌트), Code(코드)의 네 단계로, 같은 시스템을 줌인하듯 점점 자세히 그리자는 제안입니다.

ERD(Entity Relationship Diagram, 개체 관계도)는 데이터를 어떻게 저장할지를 그립니다. 테이블과 그 관계, 정규화 수준을 정하는 작업인데, 한번 굳으면 바꾸기 가장 비싼 영역이라 신중할수록 좋습니다. API Spec(Application Programming Interface 명세)은 서로 다른 부분이 어떤 약속으로 데이터를 주고받을지를 정의하는, 프론트엔드와 백엔드가 함께 보는 단일 진실 소스(SSOT, Single Source of Truth)입니다. REST API라면 OpenAPI(예전의 Swagger)가 사실상 표준이지요. 코드를 먼저 짜고 스펙을 뽑을지, 스펙을 먼저 합의하고 코드를 맞출지는 팀마다 다르지만, 함께 일하는 사람이 둘 이상이라면 스펙을 먼저 두는 편이 분쟁을 줄여 준다는 생각이 들었습니다.

문서	무엇에 답하나	언제 쓰나
TRD / Tech Spec / Design Doc	이걸 기술적으로 어떻게 구현할까	구현 착수 전, 팀 리뷰가 필요할 때
아키텍처 다이어그램	시스템이 어떤 조각으로 나뉘나	전체 구조를 합의·공유할 때
ERD / 데이터 모델	데이터를 어떻게 저장하나	DB 스키마를 설계할 때
API Spec (OpenAPI)	서로 어떤 약속으로 주고받나	프론트-백 협업의 경계를 정할 때
ADR	왜 이 선택을 했나	되돌리기 어려운 결정을 내릴 때마다

ADR — 1인 개발자에게도 권하고 싶은 문서

기술 단계 문서 중에서 딱 하나만 꼽으라면, 저는 망설임 없이 ADR(Architecture Decision Record, 아키텍처 결정 기록)을 고르겠습니다. ADR은 '왜 이 기술과 구조를 택했는가'를 결정이 일어난 시점마다 짧게 남기는 문서입니다. Michael Nygard가 2011년에 제안한 포맷이 가장 널리 쓰입니다.

핵심은 분량이 작다는 데 있습니다. 제목, 상태, 맥락, 결정, 결과. 이 다섯 칸이면 충분합니다. 상태는 보통 제안됨(Proposed), 승인됨(Accepted), 폐기됨(Deprecated), 대체됨(Superseded) 정도로 흐릅니다. 결정을 지우지 않고 '대체됨'으로 표시한 뒤 새 ADR을 잇는 방식이라, 생각이 어떻게 바뀌어 왔는지가 기록에 그대로 남습니다.

# ADR-007: 검색에 RRF 하이브리드 방식을 도입한다

상태(Status): 승인됨(Accepted) — 2026-03-12

맥락(Context):
키워드 검색만으로는 표현이 다른 비슷한 글을 놓치고,
벡터 검색만으로는 정확한 용어 매칭이 약하다.
두 방식의 장점을 함께 살릴 방법이 필요했다.

결정(Decision):
벡터 점수와 키워드 점수를 RRF(Reciprocal Rank Fusion)로 결합한다.
가중치는 vector 0.7, keyword 0.3 으로 시작한다.

결과(Consequences):
- 의미 검색과 정확한 용어 매칭을 모두 살릴 수 있다.
- 가중치 튜닝과 인덱스 2종 유지라는 비용이 생긴다.
- 효과가 없으면 키워드 검색 단독으로 되돌릴 수 있게 둔다.

이 문서가 특히 1인 개발자에게 유용하다고 느낀 이유는, 가장 자주 '왜 이렇게 했지?'라고 묻는 사람이 다름 아닌 몇 달 뒤의 나 자신이기 때문입니다. 협업이 없어 합의가 필요 없는 상황에서도, ADR은 결국 미래의 나에게 보내는 짧은 메모인 셈입니다.

5단계 — 검증(Verify): 잘 됐나

만들었다고 끝이 아닙니다. '이게 의도대로 동작하나', 그리고 '무엇이 어떻게 바뀌었나'에 답하는 단계가 검증입니다. 이 단계의 문서들은 화려하지 않지만, 빠졌을 때 가장 조용히 그리고 가장 비싸게 대가를 치르게 하는 종류라는 생각이 듭니다.

Test Plan / QA Spec(Quality Assurance Specification, 품질 보증 명세)은 무엇을 어떤 환경에서, 어떤 케이스로 테스트할지를 정합니다. 범위와 우선순위를 미리 적어 두면, 시간이 부족할 때 무엇을 포기하고 무엇을 지킬지 판단할 근거가 됩니다.

인수기준(AC, Acceptance Criteria)은 '어디까지 되면 완성인가', 즉 완성의 정의(DoD, Definition of Done)를 못 박는 문서입니다. 2편에서 다룬 User Story(사용자 스토리)가 '무엇을 원하는가'를 적었다면, 인수기준은 그 스토리가 '충족되었다고 말할 수 있는 조건'을 적습니다. 흔히 Given-When-Then 포맷을 씁니다.

시나리오: 비밀번호 재설정
  Given 가입된 이메일로 재설정을 요청했고
  When 메일의 링크를 24시간 안에 클릭하면
  Then 새 비밀번호를 설정할 수 있다

  When 링크를 24시간이 지난 뒤에 클릭하면
  Then "만료된 링크"라는 안내가 표시된다

릴리즈 노트 / 변경 로그(Changelog)는 '무엇이 바뀌었나'를 사용자나 동료에게 알립니다. 사소해 보여도 몇 달 뒤 '이 기능이 언제, 왜 들어왔지?'를 추적할 때 가장 먼저 펴 보게 되는 문서입니다. 마지막으로 Runbook(운영 대응 문서)은 '이 알람이 뜨면 이렇게 한다'를 적어 둔 운영 단계의 문서입니다. 새벽에 장애가 났을 때, 당황한 머리 대신 차분하게 적어 둔 절차가 일을 해결한다는 것을 한 번 겪고 나면 이 문서의 가치를 다시 보게 됩니다.

전부 다 쓸 필요는 없습니다 — 상황별 추천 세트

여기까지 오면 문서 종류가 스무 개 가까이 됩니다. 이 목록을 처음 마주하면 '이걸 다 써야 하나' 하는 압박부터 듭니다. 하지만 시리즈 내내 말해 온 것처럼, 문서는 의무가 아니라 목적입니다. 지금 답해야 할 질문이 없는 문서는 쓰지 않아도 됩니다. 상황별로 실제 필요한 세트는 생각보다 많이 다릅니다.

상황	추천 문서 흐름	핵심
1인 개발 · 빠른 검증	Lean Canvas → 간소화 PRD → IA + 화면 스케치 → (선택) ADR	가설 검증이 먼저, 문서는 최소로
SI · 외주 프로젝트	RFP → 제안서 → 화면설계서 → 기능정의서	계약과 분쟁 방지가 중심
스타트업 제품팀	PR-FAQ → PRD → User Flow → Design System → ADR	정렬과 반복 속도
엔지니어링 중심	RFC / Design Doc(TRD) → ADR → API Spec	기술 합의와 결정 기록

표에 처음 나온 약어를 풀면, RFP는 제안 요청서(Request for Proposal), RFC는 의견 요청서(Request for Comments), PR-FAQ는 출시 보도자료와 예상 질문을 먼저 써 보는 기법입니다. 같은 PRD라도 1인 개발에서는 한 페이지면 충분하고 제품팀에서는 더 촘촘해지듯, 문서는 이름이 같아도 깊이를 상황이 정합니다.

딱 세 개만 고른다면

그럼에도 '뭐부터 손대야 할지 모르겠다'면, 저는 이 세 가지를 기획의 뼈대로 권하고 싶습니다.

• PRD — 무엇을, 왜 만드는가
• IA · User Flow — 어떻게 구성하고 어떻게 흘러가는가
• 화면설계서 또는 와이어프레임 — 구체적으로 어떤 화면인가

이 세 개만 있어도 '왜 → 무엇 → 어떻게 → 화면'으로 이어지는 골격이 잡힙니다. 나머지 문서는 이 뼈대에 살을 붙이거나 특정 상황에서만 필요한 것들이지요. 처음부터 스무 개를 채우려 하기보다, 이 세 개에서 시작해 필요할 때마다 한 칸씩 늘려 가는 편이 현실적이라는 생각이 듭니다.

시리즈를 닫으며

세 편에 걸쳐 기획 문서의 지도를 그려 봤습니다. 1편의 발견과 정의(왜·무엇), 2편의 설계(어떻게 생겼나), 그리고 3편의 기술과 검증(어떻게 구현하고 잘 됐나). 라이프사이클의 다섯 단계를 따라오면서 가장 하고 싶었던 말은, 문서의 이름을 외우는 일은 생각보다 중요하지 않다는 것입니다.

중요한 것은 지금 무슨 질문에 답해야 하는가입니다. 질문이 정해지면 어떤 문서를 써야 할지는 자연히 따라옵니다. PRD인지 ADR인지 헷갈릴 때, 문서 이름을 떠올리는 대신 '나는 지금 무엇을 만들지 정하는 중인가, 아니면 왜 이렇게 구현할지 기록하는 중인가'를 물으면 답이 나옵니다.

문서의 목적은 결국 두 가지로 모입니다. 같은 그림을 보고 일하기 위한 정렬(alignment), 그리고 몇 달 뒤의 내가 같은 고민을 처음부터 다시 하지 않도록 돕는 일.

문서 자체가 목적이 된 순간, 문서는 가장 빨리 버려진다는 생각이 들었습니다. 과하지도 부족하지도 않게, 답해야 할 질문이 있는 만큼만 쓰는 것. 그것이 이 긴 목록을 관통하는 단 하나의 원칙이라고 정리하며, 세 편의 글을 닫습니다.