[개인 프로젝트] - 기능 명세서 작성하는 법

1. 기능 명세서란?

 기능 명세서는 만들고자 하는 웹/앱 서비스에 구현해야 할 기능을 표로 정리해 놓은 것이다.

 

 프로젝트를 진행할 때, PM(Project Manager)은 웹/앱 서비스에 본인이 생각하기에 필요한 기능들이 많을 수도 있고, 아직 구체화되지 않았을 수도 있다. 이때 단순히 말이나 글로만 정리해서 개발팀에 전달한다면, 개발자가 이해한 기능과 PM이 의도한 기능이 어긋날 가능성이 크다.  즉, 서로 동일한 기준 없이 진행하면 프로젝트가 원활하게 진행되지 않을 수 있다.

 

 그래서, PM 입장에서는 웹/앱 서비스에 실제로 필요한 기능들을 구체적으로 표 형태로 작성해 개발자들에게 전달해야 하고, 개발자는 이 기능 명세서를 보고 어떤 기능이 필요하고 어떻게 구현해야 하는지 명확하게 파악할 수 있다.

---

2. 기능 명세서에 필요한 것들

 그렇다면 기능 명세서에는 어떤 항목들이 포함되어야 하고 어떻게 작성할 수 있을까?

 

 사실 기능 명세서는 정형화된 툴은 없다. 프로젝트 성격과 팀의 협업 방식에 따라 유동적으로 달라진다. 다만 그래도 필수적으로 들어가야 할 공통 요소는 존재한다

먼저 이 예시는 처음 프로젝트를 시작하면서, 로그인/회원가입 백엔드 구현을 맡았을 때, 프론트와의 소통을 위해 처음 써 본 기능 명세이다. 참고로 이후 리펙토링을 진행하면서 해당 기능과는 조금 많이 달라졌다. 

 

이 기능 명세서에는 회원 가입에 필요한 HTTP Method(POST)와 Request body, Response body, 기능 설명, 상태 코드, 파라미터, 예시 응답, 케이스 등이 정리되어 있다.

 

해당 기능 명세서가 틀리다고 할 수는 없지만, 다소 아쉬웠던 점을 정리해보자면,

• 응답 바디 칼럼에 있는 데이터와 예시 응답이 일관성있지 않고,
• 보안도 조금 신경써서 예시에서도 비밀번호는 굳이 저렇게 적을 필요는 없었던 것 같고,
• 예외 처리 케이스도 조금 더 구체적으로 정의했어야 된다는 것이다.

이외에도 많은 부족한 점들이 존재하지만, 이번 기회를 통해 다음 기능 명세서에는 조금 더 완성도 있게 작성해야 할 것 같다.

 

 그럼 진짜 기능 명세서에 필요한 것들은 무엇이 있을까?

• 기능 정의(기능명과 설명)
• 사용자 시나리오
• 요청 바디, 응답 바디
• 상태 코드
• 예외 처리

기능 명세서는 또 너무 복잡하면 의미가 퇴색된다고 생각하기 때문에 지금 생각해보면 이 정도인 것 같다. 그럼, 회원 가입에 대해서 간단하게 표로 기능 명세서를 작성해보면, 다음과 같이 나타날 것 같다.

항목	내용
기능	회원가입
설명	아이디와 비밀번호를 입력해 새로운 계정을 생성한다.
Method	POST
Endpoint	/api/abc/auth/signup
요청 바디	{ "id": "user123", "password": "********" }
응답 바디	{ "userId": 1, "token": "JWT..." }
응답 바디(요청 실패 시)	{ "errorCode": "DUPLICATE_EMAIL", "message": "이미 존재하는 아이디입니다." }
상태 코드	201 Created, 400 Bad Request, 409 Conflict
예외 처리	아이디 중복 시 409 반환, 비밀번호 규칙 위반 시 400 반환

 

위 표도 상당히 러프하게 그린 것이고, 더 구체적으로 만들 수 있으면 만들 수 있을 것 같다.

---

3. 기능 명세서 작성하는 법

 그럼, PM이 기능 명세서를 실제 작성할 때, 어떻게 작성해야 될까?

 

 보통, 처음 기능 명세서를 작성하게 된다면, 위의 표와 같이 기능 설명에 대해서 조금 모호하게 작성할 수도 있다. 해당 기능 명세서를 받고 개발팀이 개발을 시작하게 된다면, 여러 의문점들이 생길 것이다. 지금 저 명세를 보고 생기는 의문점들을 떠올리면 다음과 같다.

• 회원가입 시 진짜 아이디 비밀번호만 있으면 되나?
• 한 명의 사람이 아이디만 겹치지 않게 만들면 여러 계정을 가질 수 있나?
• 위의 질문에 파생돼서, 사용자를 인증할 수 있는 이메일이나 핸드폰 번호는 필요 없나?

그렇기에 개발팀은 PM에게 다시 연락할 것이고, PM은 설명을 해줘야 하는 상황이 반복될 것이다. 이렇게 되면, 기능 명세서의 의미가 퇴색된다. 따라서, 기능 명세서에서는 기능에 대해 간결하고 명확하게 이해 가능하게 작성해야 된다.

 

따라서 지켜야될 것은 다음과 같다.

• 기능에 대해 한 문장으로 정의
• 사용자 시나리오 구체적으로 작성
• 와이어 프레임 첨부
• 입/출력값 정확히 하기
• 예외 처리

즉, 기능 명세를 작성할 때, 위의 규칙(?) 같은 것들을 지키며 작성하면, 기능 명세서의 의미가 퇴색되지 않게 개발팀에게 명확히 기능을 전달할 수 있다.

 

위의 표를 다시 참고해 고쳐보면,

• 설명: "사용자는 이메일 인증과 아이디, 비밀번호를 통해 회원가입을 진행한다."
• 사용자 시나리오:
  1. 사용자는 홈페이지의 회원가입 버튼을 통해 회원가입 화면으로 이동한다.
  2. 회원가입 화면에서 이메일을 입력하고, 이메일 인증 버튼을 누르면 입력한 이메일로 인증 코드를 전송한다.
  3. 사용자는 이메일 인증코드 입력란에 받은 인증코드를 기입하고, 인증하기 버튼을 누른다.
  4. ...
• 와이어 프레임: 개발자가 이해하기 편하기 위해 홈페이지 화면과 회원가입 화면에 대한 와이어프레임을 제작해 같이 첨부한다.
• 입/출력값 정확히 하기: 어떤 데이터를 입력하면 어떤 데이터가 나오는지 명확하게 작성해야 한다.
• 예외 처리:
  • 이미 가입한 이메일이라면, "이미 가입된 이메일입니다."
  • 비밀번호 형식이 잘못됐다면, "비밀번호는 특수문자를 포함해 최소 8자리 이상이어야 합니다."

결국 기능 명세서는 개발팀과 PM이 같은 그림을 보게 만드는 문서이다. 따라서 표 형식으로 간결하고 명확하게 작성하면 불필요한 커뮤니케이션 비용을 줄이고 프로젝트를 훨씬 안정적으로 진행할 수 있다.