설계 산출물 — 누가 무엇을 보고 개발하는가

한 줄 요약

설계 산출물의 독자는 개발자이고 목적은 하나다 — 다시 물어보지 않고 코드를 짤 수 있게 하는 것. 질문이 다시 올라오면 그 산출물은 실패한 것이다.

왜 이게 필요한가

설계서를 형식이라고 여기는 순간 그 프로젝트는 개발 단계에서 멈춘다. 산출물이 부실하면 개발자는 매번 기획자에게 물어야 하고, 기획자는 하루에 스무 번 같은 질문을 받으며, 그 답은 문서가 아니라 메신저에 흩어진다. 두 달 뒤 새 개발자가 합류하면 그 메신저를 읽을 방법이 없다.

더 큰 문제는 동시 작업이 불가능해진다는 것이다. 화면 개발자와 백엔드 개발자가 같은 화면을 나눠 맡으려면 둘 다 같은 명세를 보고 있어야 하는데, 명세가 없으면 한쪽이 다른 쪽을 기다린다. 산출물의 진짜 용도는 기록이 아니라 병렬화다.

설계 산출물은 '개발자에게 보내는 명세'다

분석 단계가 끝나면 설계 단계로 넘어간다. 이 단계 산출물의 독자는 개발자이고,
목적은 단 하나 — 개발자가 기획자에게 다시 물어보지 않고 코드를 짤 수 있게 하는 것이다.
질문이 다시 올라온다면 그 산출물은 실패한 것이다.

현장에서 실제로 쓰이는 것은 대략 이 다섯이다.

| 산출물 | 독자 | 없으면 생기는 일 |
| --- | --- | --- |
| 메뉴구성도 | 전원 | 화면 ID 체계가 사람마다 달라진다 |
| 화면정의서 | 화면 개발자, 퍼블리셔, QA | 버튼 하나 동작을 매번 물어본다 |
| ERD / 테이블정의서 | 백엔드, DBA | 컬럼 타입·길이가 개발자마다 다르게 잡힌다 |
| 인터페이스정의서 | 양쪽 시스템 개발자 | 연동 테스트 첫날 하루를 통째로 날린다 |
| 프로그램목록 | PL, QA | 진척률을 셀 단위가 없어 감으로 보고한다 |

화면정의서 — 그림이 아니라 '동작'이 본문이다

신입이 만든 화면정의서를 보면 화면 캡처만 크게 붙어 있다. 정작 개발자가 필요한 건
그림 밑에 있어야 할 표다.

항목 정의: 항목명 / 필수 여부 / 입력 형식 / 최대 길이 / 초기값 / 코드 참조
이벤트 정의: 어떤 버튼을 누르면 → 어떤 검증을 하고 → 어디로 가는가
오류 처리: 검증 실패 시 문구, 서버 오류 시 문구
권한: 이 화면을 누가 볼 수 있고, 어떤 버튼이 누구에게 비활성인가

특히 권한이 빠진 화면정의서는 통합테스트에서 반드시 사고를 만든다.
"관리자만 보여야 하는 버튼이 일반 사용자에게 보인다"는 결함은 늦게 발견될수록 비싸다.

테이블정의서 — 표준단어가 먼저다

공공 프로젝트에는 「공공기관의 데이터베이스 표준화 지침」이 있고,
민간 대기업도 대부분 사내 데이터 표준을 갖고 있다. 순서는 이렇다.

표준단어사전  (주문 → ORD, 고객 → CUST, 명칭 → NM, 일자 → DT, 금액 → AMT)      ↓표준도메인    (금액 → NUMBER(15,2), 일자 → CHAR(8), 여부 → CHAR(1) Y/N)      ↓표준용어      (주문금액 → ORD_AMT, 고객명 → CUST_NM)      ↓테이블정의서  (ORD_AMT NUMBER(15,2) NOT NULL DEFAULT 0)

이 순서를 지키면 서로 다른 팀이 만든 테이블에서도 CUST_NM 은 언제나 고객명이고
언제나 같은 길이다. 안 지키면 CUST_NAME, CUSTOMER_NM, CUST_NM 이 한 DB 에
공존하고, 3년 뒤 데이터 이관할 때 그 대가를 치른다.

여부 컬럼은 Y/N 한 자리로, 날짜는 CHAR(8) YYYYMMDD 로 하는 관행이 아직도
많다. 마음에 안 들 수 있지만, 이미 그렇게 만들어진 레거시와 연동해야 한다면
새 테이블만 다르게 가는 것이 더 큰 비용이다. 표준은 '최선'이 아니라 '합의'다.

인터페이스정의서 — 사고가 가장 많이 나는 문서

시스템 간 연동은 양쪽 회사가 다르고, 개발자가 다르고, 테스트 일정이 다르다.
그래서 정의서에 안 적힌 것은 100% 서로 다르게 구현된다.

반드시 적혀 있어야 하는 것:

인터페이스 ID, 업무명, 송신/수신 시스템, 연계 방식(REST/파일/큐/DB링크)
주기(실시간/일배치/시간배치)와 시각, 그리고 재처리 규칙
전문 레이아웃: 항목명 / 타입 / 길이 / 필수 / 샘플값 / 비고
문자셋(UTF-8? EUC-KR?), 날짜 포맷, 금액의 소수 자릿수, 부호 표현
응답 코드 체계와 각 코드에 대한 수신측 조치(재시도/중단/담당자 통보)
장애 시 연락 체계와 SLA

문자셋과 날짜 포맷 — 이 둘만 안 적혀 있어도 연동 테스트 첫날은 날아간다.
현장 격언이 있다: "인터페이스 정의서에 없는 건 반드시 다르게 구현돼 있다."

설계 산출물의 진짜 용도는 '동시 작업'이다

왜 이렇게 문서를 많이 쓰냐고 묻는다면, 답은 병렬화다.
SI 프로젝트는 인원이 수십 명이고 기간이 정해져 있다. 화면 개발자, API 개발자,
DBA, 연동 담당자가 서로를 기다리지 않고 동시에 일하려면 그 사이에
"합의된 인터페이스"가 문서로 존재해야 한다.

애자일 팀이 문서를 줄일 수 있는 건 같은 방에서 매일 대화하기 때문이다.
SI 는 회사가 다르고, 층이 다르고, 심지어 망이 분리돼 있다. 그 조건에서
문서는 관료주의가 아니라 동기화 프로토콜이다.

산출물 검토(리뷰)에서 실제로 봐야 할 것

검토 회의에서 오탈자를 잡는 건 시간 낭비다. 봐야 할 것은 이것이다.

1. 요구사항 ID 가 붙어 있는가 (추적 가능한가)
2. 숫자가 있는가 (길이, 건수, 주기, 타임아웃)
3. 예외 흐름이 있는가 (정상 흐름만 있는 설계서는 절반짜리다)
4. 상대편이 서명했는가 (인터페이스정의서는 양쪽 합의 문서다)

현장에서 만나는 모습

설계서가 부실할 때 가장 먼저 무너지는 것은 연동 테스트 첫날이다.

인터페이스정의서에 필드 길이나 필수 여부가 비어 있으면, 양쪽 개발자가 각자 합리적으로 추측해 만들어 온다. 그리고 첫 연동 시험에서 전문이 서로 안 맞는다. 그 하루는 개발이 아니라 협의로 통째로 나가고, 그 협의 결과는 대개 정의서가 아니라 메신저에 남는다 — 그래서 두 달 뒤 같은 문제가 다시 난다.

화면정의서에서는 다른 방식으로 드러난다. 그림만 크게 붙어 있고 동작 표가 없으면, 개발자는 버튼 하나마다 기획자에게 묻는다. 기획자가 자리에 없는 날 그 화면은 멈춘다. 산출물이 없으면 사람이 병목이 된다.

그래서 산출물 검토에서 봐야 할 것은 문장의 매끄러움이 아니라 "이걸 보고 개발자가 혼자 짤 수 있는가" 하나다.