TL;DR
요구사항 명세서는 백엔드 개발자끼리 보는 기술 문서가 아니다.
비개발 직군과의 소통 도구이며, "이거 제가 원한 게 아닌데요?"라는 말을 듣지 않기 위해, 그리고 놓친 케이스를 함께 찾아내기 위해 작성하는 문서다. 그래서 BAD_REQUEST 대신 "재고가 부족합니다"라고 써야 한다.
시작하며
이번 주 e-commerce 프로젝트를 시작하면서 가장 먼저 작성한 건 요구사항 명세서였다.
사실 처음엔 이런 생각이 들었다.
“이거 꼭 써야 하나? 어차피 코드로 구현하면 되는데... 문서 작성에 시간을 쓰는 게 비효율적인 거 아닌가?”
하지만 막상 써보니 생각이 완전히 달라졌다.
작성하는 과정 자체가 팀 전체의 이해를 맞추는 과정이었다.
이 문서는 누구를 위한 것인가?
처음엔 요구사항 명세서를 개발자를 위한 설계 문서로 생각했다.
ERD나 클래스 다이어그램처럼 기술적인 문서의 연장선으로 봤다.
그런데 작성하다 보니, 이건 명백히 비개발 직군과 대화하기 위한 문서라는 걸 깨달았다.
왜 필요한가?
"이거 제가 원한 기능이 아닌데요"를 방지하기 위해
개발 다 끝내고 이런 말을 들으면 정말 허무하다.
구현 전에 합의가 되어 있었다면, 이런 상황은 막을 수 있다.
요구사항 명세서는 바로 그 “합의서” 역할을 한다.
내가 놓친 케이스를 함께 찾기 위해
혼자 생각하면 빠뜨리는 게 정말 많다.
기획자나 PM이 “그럼 재고가 0일 때는요?” 같은 질문을 던져줄 때 비로소 놓쳤던 케이스를 발견하게 된다.
결국, 명세서는 내가 모르는 걸 찾아주는 대화 도구다.
가장 큰 고민: 어디까지 상세해야 할까?
너무 간단하면 정보가 부족하고, 너무 상세하면 읽는 사람이 지친다.
고민 끝에 세운 기준은 단순했다.
비개발자가 읽고 “아, 이렇게 동작하는구나”를 이해할 수 있어야 한다.
구체적인 선택들
1. 예외 메시지는 기술 용어 대신 사용자 언어로
이렇게는 쓰지 않았다
- 존재하지 않는 상품 주문 시 404 NOT_FOUND
- 재고 부족 시 400 BAD_REQUEST
- 포인트 부족 시 402 PAYMENT_REQUIRED이렇게 썼다
- 존재하지 않는 상품 주문 시 오류
- 재고 부족 시 → "재고가 부족합니다"
- 포인트 부족 시 → "포인트가 부족합니다"기획자가 “재고 부족할 때 어떻게 보여줄까요?”라고 물었을 때, OUT_OF_STOCK보다 "재고가 부족합니다"가 훨씬 대화하기 좋다.
2. 기능 흐름은 순서대로, 구어체로
시퀀스 다이어그램도 비슷한 이유로 한글로 작성했다.
처음엔 GET /products/{id} 같은 API 경로를 그대로 썼지만, 나중엔 “상품 상세 조회 요청”으로 바꿨다.
RESTful API를 모르는 사람도 읽을 수 있게 하기 위해서다.
사용자 → 컨트롤러: 상품 상세 조회 요청
컨트롤러 → 서비스: 상품 조회
서비스 → 레포지토리: 상품 데이터 조회
레포지토리 → 서비스: 상품 반환이 정도만 되어도 비개발자도 "아, 이런 흐름이구나"를 이해할 수 있다.
3. 유비쿼터스 언어 테이블 만들기
같은 개념을 팀마다 다르게 부르는 일이 정말 많은데, 예를 들어 “주문상품”은
- 어떤 팀원은 OrderItem,
- 기획자는 “주문 아이템”,
- 디자이너는 “구매 상품”
이렇게 제각각 부를 수 있는데, 그래서 다음처럼 정리했다.
| 한글 용어 | 영문 용어 | 설명 |
| 주문상품 | OrderItem | 주문 생성 시점의 상품 정보 스냅샷 (불변) |
이 표 하나만 있어도 회의가 훨씬 수월해진다.
작성하며 배운 것
1. 요구사항 명세서는 “계약서”다
문서는 개발팀과 비개발팀 간의 합의 내용이며, “이렇게 만들기로 했다”를 기록하는 문서이기도 하고, “이 부분은 논의가 필요하다”를 찾아내는 도구이기도 하다.
2. 상세한 게 좋은 게 아니다
처음엔 모든 예외 케이스를 다 적으려 했는데, 그렇게 하면 문서가 너무 길어지고, 핵심이 묻힌다.
그래서 중요한 비즈니스 규칙과 예외 상황만 남겼고, 그게 진짜 읽히는 문서였다.
3. 완벽한 문서를 만들려고 하지 말자
요구사항은 바뀌기 마련이고, 중요한 건 “처음부터 완벽하게 쓰는 것”이 아니라 “변화할 때마다 함께 업데이트 가능하게 하는 것”이다.
문서는 고정된 결과물이 아니라 팀의 현재 상태를 반영하는 과정이다.
마무리하며
요구사항 명세서를 작성하면서 가장 중요하게 느낀 건 "이 문서 왜 작성하는 거지?", "이 문서를 읽을 사람은 누구인가?"였다.
백엔드 개발자끼리만 공유할 문서라면 ERD나 클래스 다이어그램으로 충분하다.
하지만 기획자, 디자이너와 함께 논의해야 한다면 요구사항 명세서는 “코드보다 더 강력한 소통 도구”가 된다.
HTTP 400 대신 “재고가 부족합니다”라고 쓰는 이유는, 그게 더 명확하고, 더 공감할 수 있는 언어이기 때문이다.
