기능 명세 문서(Feature Specification Document)

좋은 아이디어가 현실이 되는 곳은 feature spec이다

Stripe 엔지니어링 문화에는 이런 말이 있습니다. "spec을 못 쓰면 ship도 못 한다." 그들의 PM은 코드베이스를 한 번도 본 적 없는 엔지니어도 그대로 만들 수 있을 정도로 상세한 feature spec을 씁니다. 엔지니어에게 손을 잡아주기 위해서가 아닙니다. shipping velocity를 죽이는 가장 조용한 원인이 ambiguity이기 때문입니다.

대부분의 제품팀은 이 단계를 건너뜁니다. "사용자가 검색 결과를 필터링할 수 있어야 한다"고 쓰인 PRD 하나만 있고, 나머지는 엔지니어링이 알아서 하겠지라고 생각합니다. 그러다 2주 뒤 누군가 묻습니다. "사용자가 필터를 12개 동시에 걸면 어떻게 되죠?" 그런데 아무도 모릅니다.

전략과 코드 사이에 빠져 있는 층

McKinsey의 2022년 소프트웨어 생산성 연구에 따르면, 불명확한 요구사항은 엔지니어링 재작업의 가장 큰 원인으로 전체 낭비 시간의 최대 35%를 차지합니다. Technical debt도 아니고, 툴링도 아닙니다. 애매함입니다.

PRD는 전략 레이어에 있습니다. 왜 만드는지, 누구를 위한 것인지, 무엇을 만들지 높은 수준에서 정의합니다. 하지만 "우리가 collaborative editing 기능을 만든다"는 말과 실제 구현 사이에는 큰 간극이 있습니다. 그 간극을 메우는 문서가 feature spec입니다. 데이터 모델은 무엇인지, error state는 어떻게 보이는지, API contract는 무엇인지, 두 사용자가 같은 문단을 동시에 수정하면 어떤 edge case가 생기는지 같은 불편한 질문에 답하는 곳입니다.

바로 이 문서가 code review에서 나오는 "아, 그건 생각 못 했네요"를 줄여줍니다. Teresa Torres는 이를 opportunity space 문제라고 표현합니다. 팀은 opportunity를 찾는 데는 능숙하지만, 그것을 실제로 만들 만큼 정밀하게 명세하는 데는 서툽니다.

이 프롬프트가 돕는 방식

이 프롬프트는 feature context를 바탕으로 build-ready feature specification을 생성합니다. 기능 이름, 상위 PRD, 타깃 릴리스, engineering lead를 입력하면 user flow, edge case 문서화, API contract, error state, acceptance criteria, 테스트 고려사항까지 포함한 문서를 만들어줍니다.

특히 좋은 점은, 당신이 빼먹기 쉬운 질문을 대신 해준다는 것입니다. 인터넷이 없는 상황에서 어떻게 되는지, empty state가 어떤 모습이어야 하는지, 오래된 브라우저에서는 어떻게 degrade되는지 같은 항목은 경험 많은 PM도 자주 놓칩니다.

언제 사용할까

• PRD를 끝냈고, 개별 기능 단위로 엔지니어링이 바로 구현할 수 있는 명세로 쪼개야 할 때
• 엔지니어가 "그 상황에서는 어떻게 돼야 하죠?"라고 물었고, 답이 어디에도 적혀 있지 않다는 걸 깨달았을 때
• 시차가 있는 분산 팀과 일해서 회의 없이도 홀로 서는 spec이 필요할 때
• 상태 관리가 복잡하거나 user path가 여러 갈래인 기능이라 코딩 전에 충분히 문서화해야 할 때
• acceptance criteria를 upfront에 정의해서 code review 왕복을 줄이고 싶을 때

좋은 결과물의 모습

강한 feature spec은 제품과 엔지니어링 사이의 계약처럼 읽힙니다. Happy path만이 아니라 decision tree가 있는 user flow를 담고, error state는 정확한 copy와 behavior까지 규정하며, API contract는 request/response schema를 포함하고, acceptance criteria는 엔지니어나 QA가 읽고 "통과" 또는 "실패"를 분명히 판정할 수 있어야 합니다.

참고 자료

• The Real Cost of Unclear Requirements — McKinsey Digital
• Continuous Discovery Habits — Teresa Torres