기능 명세서 작성법, 개발자가 바로 쓰는 10가지

기능 명세서는 요구사항 정의서(PRD)에서 정한 기능을 화면·이벤트·예외 단위로 쪼개서 개발자가 코드를 짤 때 더 물어볼 게 없도록 만든 문서다. 2026년 현재 실무에서는 PRD 승인 뒤 기능 명세서로 상세화하는 순서가 표준으로 자리 잡았다. 이 글은 명세서에 꼭 들어가는 10가지 항목과 좋은 명세와 나쁜 명세를 가르는 기준을 로그인 예시로 정리한다.

핵심 요약

• 요구사항 정의서가 "무엇을 왜"라면, 기능 명세서는 "어떻게 동작하는가"를 화면·이벤트 단위로 못 박는다.
• 필수 항목은 기능 ID, 트리거, 입력과 유효성, 처리 로직, 출력, 예외, 연관 데이터, 우선순위로 요약된다.
• 명세서의 절반은 예외다. 정상 흐름 하나에 실패 상황을 3~5개 붙여야 개발자가 임의로 판단하지 않는다.
• 화면 단위로 뭉뚱그리면 나쁜 명세, 이벤트 단위로 쪼개면 좋은 명세다. 기능 ID 하나가 곧 테스트 한 건이 된다.
• 초안은 기획자가, 데이터·API·예외는 개발 리드가 보강하고 개발 킥오프 최소 1주 전에 확정한다.

요구사항 정의서와 무엇이 다른가

둘을 같은 문서로 여기는 경우가 많은데 역할이 다르다. 요구사항 정의서는 "회원가입 기능이 필요하다"까지를 정하고 기능 명세서는 이메일 형식이 틀리면 어떤 문구를 어디에 띄우는지, 인증 메일이 5분 안에 안 오면 재발송 버튼을 언제 켜는지까지 정한다. 개발자가 코드를 짤 때 실제로 필요한 것은 뒤쪽의 판단 기준이다.

구분	요구사항 정의서(PRD)	기능 명세서
답하는 질문	무엇을 왜 만드나	어떻게 동작하나
주 독자	대표·기획·마케팅	개발자·QA·디자이너
상세 수준	기능 단위	화면·필드·이벤트·예외 단위
작성 시점	기획 초기	PRD 승인 직후

요구사항 정의서를 아직 안 썼다면 요구사항 정의서 작성법을 먼저 보고 오는 편이 순서에 맞는다. 명세서는 그 위에 얹는 상세 문서이기 때문이다.

기능 명세서에 꼭 들어가는 10가지 항목

명세서 한 줄, 곧 하나의 기능은 다음 항목으로 채운다. 로그인 기능을 예로 들면 이렇게 갈린다.

항목	무엇을 적나	로그인 예
기능 ID	도메인·화면·번호로 된 고유 코드	USR-LOGIN-001
기능명	화면·행위 기준 이름	이메일 로그인
트리거	기능이 실행되는 조건	로그인 버튼 클릭
사전조건	필요한 사전 상태	비로그인, 이메일 인증 완료
입력·유효성	받는 값과 형식 규칙	이메일, 비밀번호 8~20자
처리 로직	조건과 결과로 쓴 규칙	5회 틀리면 10분 잠금
출력	성공했을 때의 결과	토큰 발급, 홈으로 이동
예외	실패 상황별 동작	형식 오류·미가입·불일치
연관 데이터·API	호출 흐름과 연결 지점	로그인 API 호출
우선순위	개발 순서 등급	P0(첫 버전 필수)

기능 ID를 도메인·화면·번호 3단으로 붙여 두면, 기획자·개발자·QA가 같은 기능을 같은 이름으로 부른다. 이슈 트래커에서 문서·코드·테스트가 한 번에 연결되는 것도 이 ID 덕분이다.

예외 케이스가 명세서의 절반이다

초보 명세서가 얇은 이유는 대개 예외를 안 써서다. 정상 흐름 하나에 실패 상황을 최소 3~5개 붙인다고 생각하면 편하다. 예외는 세 방향에서 뽑는다.

• 입력 오류: 형식이 틀리거나 필수값이 비었을 때 어떻게 안내할지 정한다.
• 규칙 위반: 미가입, 권한 부족, 계정 잠금처럼 비즈니스 규칙에 걸릴 때를 정한다.
• 시스템 실패: 네트워크가 끊기거나 외부 API 응답이 늦을 때를 정한다.

실제 프로젝트를 진행하다 보면 QA에서 터지는 재작업은 대개 이 시스템 실패 쪽에서 나온다. 결제 요청을 보냈는데 응답이 10초째 안 오면 화면을 어떻게 할지 안 정해 두면, 개발자는 임의로 처리하고 나중에 다시 뜯는다. 예외를 이벤트 단위로 쪼개 두면 기능 ID 하나가 그대로 테스트 케이스 하나가 된다.

좋은 명세와 나쁜 명세, 흔한 실수

나쁜 명세는 화면 단위로 뭉뚱그린다. "로그인 화면에서 이메일과 비밀번호로 로그인한다"가 전부면, 유효성 규칙도 에러 문구도 계정 잠금도 개발자가 알아서 판단하게 된다. 좋은 명세는 이벤트 단위로 쪼갠다. 정상 로그인, 형식 오류, 미가입, 불일치, 잠금을 각각 한 줄로 나눈다.

자주 나오는 실수를 오해와 함께 정리하면 이렇다. 첫째, 예외를 한두 개만 적고 끝난다고 여기지만, 그러면 사용자 시나리오의 절반이 빠진다. 둘째, 상태 전이를 안 적는다. 주문이 결제 대기에서 결제 완료, 취소, 환불로 바뀌는 규칙을 빼면 나중에 데이터베이스와 API를 함께 뜯어야 한다. 셋째, 권한별 화면 분기를 놓친다. 관리자와 일반 사용자가 보는 화면이 다른데 이걸 안 적으면 라우팅을 새로 짠다.

작성 순서와 착수 전 점검

혼자 다 쓰려 하지 않아도 된다. 초안은 기획자가 화면 흐름·이벤트·규칙 중심으로 잡고 데이터·API·예외 처리는 개발 리드가 보강한다. 디자이너와 QA는 그사이 검토에 들어간다. 확정 시점은 개발 킥오프 최소 1주 전이 안전하다. 이 1주 동안 개발자가 데이터 모델을 설계하고 작업을 잘게 쪼갠다.

1. 화면 요소가 모두 기능 ID에 연결됐는지 확인한다.
2. 각 입력의 유효성 규칙이 적혀 있는지 본다.
3. 처리 로직을 조건과 결과 형태로 썼는지 점검한다.
4. 정상 흐름 하나당 예외가 3개 이상인지 센다.
5. 상태 전이와 권한별 분기가 빠지지 않았는지 살핀다.

한 항목이라도 통과하지 못하면 킥오프를 미루는 편이 낫다. 명세가 빈 채로 개발을 시작하면 그 빈칸을 코드로 메우다 재작업이 쌓인다. 빈칸 하나가 나중에 화면 하나를 다시 만드는 일로 번지는 걸 여러 번 봤다.

직접 쓰기 어렵다면

기획·기술 리소스가 부족하면 명세 작성부터 코드 검수까지 한 곳에서 진행하는 방식이 안전하다. 노바랩 기준으로는 웹 애플리케이션 개발을 맡을 때 기능 명세를 함께 정리하고 넘어가는데, 명세를 쓴 쪽이 곧 구현을 검수하니 문서와 코드가 어긋날 여지가 줄어든다.

가상 예시로 감을 잡아 보자. 동네 세탁소가 픽업 예약 웹앱을 만든다고 하자. 예약하기 한 기능만 봐도 명세는 이렇게 갈린다. 트리거는 예약 버튼, 입력은 주소·희망 시간·세탁물 종류, 처리 로직은 같은 시간대 예약이 5건을 넘으면 마감 처리, 출력은 예약 번호 발급, 예외는 시간 미선택·중복 예약·서버 지연이다. 여기까지 적히면 개발자가 물어볼 게 거의 없다.

어디까지 상세히 쓸지 판단이 서지 않으면 기준은 단순하다. 그 항목을 안 적었을 때 개발자가 "이건 어떻게 하죠"라고 물어볼 것 같으면 적는다. 반대로 누가 봐도 하나로만 해석되는 부분은 굳이 늘리지 않는다. 화면 스케치가 필요하면 와이어프레임을 먼저 그려 명세와 나란히 두면 이해가 빨라진다. 판단이 애매한 지점은 문의로 물어봐도 된다.