개발 설계문서 지도: 문서 이름보다 질문을 먼저 본다

개발 문서를 찾아보기 시작하면 약어가 끝없이 나온다. PRD, SRS, SDD 정도만 알아도 복잡한데 BRD, MRD, NFR, ADR, RFC, API Spec, ERD, Runbook, Postmortem까지 이어진다. 처음에는 이걸 전부 외워야 하나 싶다. 로그를 다시 펼쳤을 때 눈에 들어온 건 예쁜 성공 화면이 아니라, 개발 주변에서 반복되던 작은 끊김이었다.

문서 지도가 커진 문제

문서를 종류별로 외우면 금방 막힌다. 회사마다 이름이 다르고, 같은 약어도 다르게 쓰인다. TDD만 해도 어떤 팀은 Technical Design Document라고 부르고, 개발자 대부분은 Test-Driven Development로 이해한다. 그래서 문서 이름보다 먼저 봐야 할 것은 그 문서가 답하는 질문이다. - [제품 판단 문서: - [요구사항 문서: “빠르게” - [구조 설계 문서: - [결정 기록 문서: - [계약과 운영 문서: 그런데 실제 문제는 약어가 많다는 데 있지 않다. 각 문서가 어떤 질문을 맡는지 모르면 모든 문서가 비슷한 기획서처럼 보인다. PRD에는 API 필드가 들어가고, SRS에는 “빠르게 동작해야 한다” 같은 희망사항이 남고, 설계문서에는 박스 몇 개만 그려진다. 문서는 길어지지만 구현은 여전히 흔들린다. | 층위 | 대표 문서 | 핵심 질문 | | --- | --- | --- | | 제품 판단 | Product Brief, BRD, MRD, PRD, Roadmap | 왜 만들고 누구에게 가치가 있는가 | | 요구사항 | SRS, FRD, NFR, Acceptance Criteria | 시스템은 무엇을 만족해야 하는가 | | 구조/설계 | SDD, Design Doc, Architecture Doc, C4, arc42 | 어떤 구조로 풀 것인가 | | 결정 기록 | ADR, RFC, Decision Log | 왜 이 선택을 했는가 | | 계약/운영 | API Spec, OpenAPI, ERD, Threat Model, Runbook, SLO | 시스템끼리 무엇을 약속하고 어떻게 운영할 것인가 |

처음에는 이름만 맞추면 될 줄 알았다

좋은 설계문서는 개발을 대신하지 않는다. 대신 개발 전에 무엇을 결정했고, 무엇을 아직 열어두었으며, 나중에 무엇을 바꿔도 되는지 알려준다. 문서가 짐이 아니라 지도가 되는 순간은 거기서 시작된다. 이 표의 핵심은 순서다. 제품 판단에서 요구사항으로 내려오고, 요구사항은 설계와 인터페이스로 갈라지고, 결정은 ADR로 남으며, 검증과 운영 문서가 배포 이후까지 이어진다.

작은 팀이라면 이 문서를 모두 따로 만들 필요는 없다. 그래도 질문은 섞으면 안 된다. 처음에는 이 지도 글만 읽어도 된다. 지금 만들려는 기능이 “왜 해야 하는가”에서 흔들리면 제품 판단 문서로 가고, “정확히 무엇을 만족해야 하는가”가 흐리면 요구사항 문서로 가면 된다. 구조가 머릿속에만 있으면 설계문서로, 선택 이유가 사라질 것 같으면 ADR/RFC로, 배포 뒤가 불안하면 운영 문서로 내려가면 된다.

특히 개발에서는 재현 조건을 같이 적어야 의미가 있었다. 그래서 전체 지도만 남긴다. 각각의 문서군은 별도 글로 쪼갰다. 한 글에서 모든 문서를 설명하려고 하면 지금 내가 한 실수처럼 읽는 사람이 문서 더미 앞에 다시 서게 된다. 특히 개발에서는 재현 조건을 같이 적어야 의미가 있었다. 문서를 종류별로 외우면 금방 막힌다. 회사마다 이름이 다르고, 같은 약어도 다르게 쓰인다.

TDD만 해도 어떤 팀은 Technical Design Document라고 부르고, 개발자 대부분은 Test-Driven Development로 이해한다. 그래서 문서 이름보다 먼저 봐야 할 것은 그 문서가 답하는 질문이다.

질문이 먼저임이 선명해진 순간

• [제품 판단 문서:
• [요구사항 문서: “빠르게”
• [구조 설계 문서:
• [결정 기록 문서:
• [계약과 운영 문서: 그런데 실제 문제는 약어가 많다는 데 있지 않다. 각 문서가 어떤 질문을 맡는지 모르면 모든 문서가 비슷한 기획서처럼 보인다. PRD에는 API 필드가 들어가고, SRS에는 “빠르게 동작해야 한다” 같은 희망사항이 남고, 설계문서에는 박스 몇 개만 그려진다. 문서는 길어지지만 구현은 여전히 흔들린다. | 층위 | 대표 문서 | 핵심 질문 | | --- | --- | --- | | 제품 판단 | Product Brief, BRD, MRD, PRD, Roadmap | 왜 만들고 누구에게 가치가 있는가 | | 요구사항 | SRS, FRD, NFR, Acceptance Criteria | 시스템은 무엇을 만족해야 하는가 | | 구조/설계 | SDD, Design Doc, Architecture Doc, C4, arc42 | 어떤 구조로 풀 것인가 | | 결정 기록 | ADR, RFC, Decision Log | 왜 이 선택을 했는가 | | 계약/운영 | API Spec, OpenAPI, ERD, Threat Model, Runbook, SLO | 시스템끼리 무엇을 약속하고 어떻게 운영할 것인가 | 좋은 설계문서는 개발을 대신하지 않는다. 대신 개발 전에 무엇을 결정했고, 무엇을 아직 열어두었으며, 나중에 무엇을 바꿔도 되는지 알려준다. 문서가 짐이 아니라 지도가 되는 순간은 거기서 시작된다. 이 표의 핵심은 순서다. 제품 판단에서 요구사항으로 내려오고, 요구사항은 설계와 인터페이스로 갈라지고, 결정은 ADR로 남으며, 검증과 운영 문서가 배포 이후까지 이어진다. 작은 팀이라면 이 문서를 모두 따로 만들 필요는 없다. 그래도 질문은 섞으면 안 된다. 특히 개발에서는 재현 조건을 같이 적어야 의미가 있었다. 처음에는 이 지도 글만 읽어도 된다. 지금 만들려는 기능이 “왜 해야 하는가”에서 흔들리면 제품 판단 문서로 가고, “정확히 무엇을 만족해야 하는가”가 흐리면 요구사항 문서로 가면 된다. 구조가 머릿속에만 있으면 설계문서로, 선택 이유가 사라질 것 같으면 ADR/RFC로, 배포 뒤가 불안하면 운영 문서로 내려가면 된다. 개발를 설명할 때 서버/클라이언트/사용자 중 누구 문장으로 말하는지 먼저 고르면 논쟁이 줄었다.

문서 종류별 경계 나누기

그래서 전체 지도만 남긴다. 각각의 문서군은 별도 글로 쪼갰다. 한 글에서 모든 문서를 설명하려고 하면 지금 내가 한 실수처럼 읽는 사람이 문서 더미 앞에 다시 서게 된다. 문서를 종류별로 외우면 금방 막힌다. 회사마다 이름이 다르고, 같은 약어도 다르게 쓰인다. TDD만 해도 어떤 팀은 Technical Design Document라고 부르고, 개발자 대부분은 Test-Driven Development로 이해한다. 그래서 문서 이름보다 먼저 봐야 할 것은 그 문서가 답하는 질문이다. - [제품 판단 문서: - [요구사항 문서: “빠르게” - [구조 설계 문서: - [결정 기록 문서: - [계약과 운영 문서: 그런데 실제 문제는 약어가 많다는 데 있지 않다. 각 문서가 어떤 질문을 맡는지 모르면 모든 문서가 비슷한 기획서처럼 보인다. PRD에는 API 필드가 들어가고, SRS에는 “빠르게 동작해야 한다” 같은 희망사항이 남고, 설계문서에는 박스 몇 개만 그려진다. 문서는 길어지지만 구현은 여전히 흔들린다.

지도가 버틴 이유

| 층위 | 대표 문서 | 핵심 질문 | | --- | --- | --- | | 제품 판단 | Product Brief, BRD, MRD, PRD, Roadmap | 왜 만들고 누구에게 가치가 있는가 | | 요구사항 | SRS, FRD, NFR, Acceptance Criteria | 시스템은 무엇을 만족해야 하는가 | | 구조/설계 | SDD, Design Doc, Architecture Doc, C4, arc42 | 어떤 구조로 풀 것인가 | | 결정 기록 | ADR, RFC, Decision Log | 왜 이 선택을 했는가 | | 계약/운영 | API Spec, OpenAPI, ERD, Threat Model, Runbook, SLO | 시스템끼리 무엇을 약속하고 어떻게 운영할 것인가 | 좋은 설계문서는 개발을 대신하지 않는다. 대신 개발 전에 무엇을 결정했고, 무엇을 아직 열어두었으며, 나중에 무엇을 바꿔도 되는지 알려준다. 문서가 짐이 아니라 지도가 되는 순간은 거기서 시작된다. 이 표의 핵심은 순서다. 제품 판단에서 요구사항으로 내려오고, 요구사항은 설계와 인터페이스로 갈라지고, 결정은 ADR로 남으며, 검증과 운영 문서가 배포 이후까지 이어진다. 작은 팀이라면 이 문서를 모두 따로 만들 필요는 없다. 그래도 질문은 섞으면 안 된다. 처음에는 이 지도 글만 읽어도 된다. 지금 만들려는 기능이 “왜 해야 하는가”에서 흔들리면 제품 판단 문서로 가고, “정확히 무엇을 만족해야 하는가”가 흐리면 요구사항 문서로 가면 된다. 구조가 머릿속에만 있으면 설계문서로, 선택 이유가 사라질 것 같으면 ADR/RFC로, 배포 뒤가 불안하면 운영 문서로 내려가면 된다. 그래서 전체 지도만 남긴다. 각각의 문서군은 별도 글로 쪼갰다. 한 글에서 모든 문서를 설명하려고 하면 지금 내가 한 실수처럼 읽는 사람이 문서 더미 앞에 다시 서게 된다. 특히 개발에서는 재현 조건을 같이 적어야 의미가 있었다. '개발 설계문서 지도: 문서 이름보다 질문을 먼저 본다'을 관통하는 질문은 이 섹션에서도 같았고, 답만 더 구체적이 됐다.

마치며

처음에는 이 지도 글만 읽어도 된다. 지금 만들려는 기능이 “왜 해야 하는가”에서 흔들리면 제품 판단 문서로 가고, “정확히 무엇을 만족해야 하는가”가 흐리면 요구사항 문서로 가면 된다. 구조가 머릿속에만 있으면 설계문서로, 선택 이유가 사라질 것 같으면 ADR/RFC로, 배포 뒤가 불안하면 운영 문서로 내려가면 된다. 그래서 전체 지도만 남긴다. 각각의 문서군은 별도 글로 쪼갰다. 한 글에서 모든 문서를 설명하려고 하면 지금 내가 한 실수처럼 읽는 사람이 문서 더미 앞에 다시 서게 된다. 문서를 종류별로 외우면 금방 막힌다. 회사마다 이름이 다르고, 같은 약어도 다르게 쓰인다. TDD만 해도 어떤 팀은 Technical Design Document라고 부르고, 개발자 대부분은 Test-Driven Development로 이해한다. 그래서 문서 이름보다 먼저 봐야 할 것은 그 문서가 답하는 질문이다.