요구사항 정의서 작성할 때 자주 하는 실수

요구사항 정의서를 몇 번 쓰고 리뷰를 받으면서, 제가 반복해서 저질렀던 실수들이 있다는 걸 알게 됐습니다.

신입 때는 "문서 형식만 갖추면 되는 것 아닌가" 싶었는데, 실제로 개발팀과 QA팀 피드백을 받아보니 형식보다 훨씬 자주 문제가 되는 지점들이 있었어요.

 

이번 글에서는 제가 직접 겪었던, 그리고 지금도 가끔 반복하는 실수들을 정리해봤습니다.

 

"정상적으로 작동해야 한다"처럼 검증 불가능한 문장

이건 제가 초반에 가장 많이 썼던 표현입니다.
"검색 결과가 정상적으로 노출되어야 한다"라고 적어놓으면 누구도 반박할 수 없지만, 동시에 아무 의미도 없는 문장이 됩니다.
QA팀에서 "정상적으로가 뭔가요, 어떤 기준으로 통과/실패를 나누나요"라고 물었을 때 제대로 답을 못 했던 기억이 나요.
지금은 "검색어 입력 후 500ms 이내에 관련도 상위 20개 결과가 노출되며, 결과가 없을 경우 대체 문구를 표시한다"처럼 숫자와 조건을 넣어서 씁니다.
검증 가능한 문장으로 바꾸는 습관만 들여도 QA 단계에서의 왔다갔다가 확실히 줄어들었어요.

 

예외 상황을 정상 플로우 다 쓰고 나서 몰아서 적기

저는 예전에 정상 플로우를 먼저 다 쓰고, 맨 마지막에 "예외 케이스" 섹션을 따로 몰아서 적는 습관이 있었습니다.
그런데 이렇게 하면 각 단계마다 어떤 예외가 있는지 놓치기가 쉬워요.
결제 프로젝트에서 이 방식으로 문서를 썼다가, 결제 진행 중 네트워크가 끊기는 케이스를 통째로 빠뜨린 적이 있습니다.
QA 단계에서 발견돼서 다행이었지만, 이미 개발이 절반 이상 끝난 시점이라 수정 비용이 컸어요.
그 이후로는 각 단계 바로 아래에 "이 단계에서 실패하면"이라는 하위 항목을 붙여서, 정상 플로우와 예외 케이스를 같은 자리에서 같이 적는 방식으로 바꿨습니다.

 

화면 캡처만 붙이고 "왜"를 안 적는 것

리뷰 회의에서 개발자가 "이 버튼을 왜 여기 넣었는지" 물어보면, 저 스스로도 답을 못 할 때가 있었습니다.
화면 시안을 보고 그대로 요구사항에 옮겨적기만 하다 보니, 배경이 되는 이유를 문서에 담지 않은 거예요.
이렇게 되면 나중에 화면을 조금이라도 바꿔야 할 상황이 왔을 때, 원래 왜 이렇게 설계했는지 아무도 기억을 못 해서 처음부터 다시 논의해야 했습니다.
지금은 요구사항 각 항목마다 한 줄이라도 "이 요구사항이 존재하는 이유"를 같이 적어두려고 합니다.

 

우선순위 표시를 안 하거나, 전부 "필수"로 적는 것

바쁠 때는 모든 항목을 그냥 "필수"로 적어버리는 유혹이 강합니다.
그런데 일정이 촉박해져서 범위를 줄여야 하는 순간이 오면, 우선순위가 없는 문서는 아무 도움이 안 됩니다.
저희 프로젝트에서 막판에 일정이 2주 밀리면서 기능을 줄여야 했는데, 문서에 우선순위가 없어서 회의에서 다시 처음부터 "이건 있어야 하나요, 없어도 되나요"를 하나씩 논의해야 했어요.
그 회의만 세 시간이 걸렸습니다.
이후로는 요구사항마다 Must/Should/Could 태그를 반드시 붙이고, 이 기준도 "이게 없으면 서비스가 아예 작동 안 하는가"처럼 명확한 질문으로 미리 팀과 합의해둡니다.

 

용어를 정의하지 않고 그냥 쓰는 것

같은 단어를 팀마다 다르게 이해하는 경우가 생각보다 많습니다.
저희는 "활성 사용자"라는 단어를 두고 마케팅팀은 "로그인한 사용자"로, 개발팀은 "특정 API를 호출한 사용자"로 서로 다르게 해석하고 있었던 적이 있어요.
지표 관련 요구사항을 정의할 때 이 차이를 미리 확인하지 않았다면, 나중에 완전히 다른 숫자로 대시보드가 만들어질 뻔했습니다.
지금은 문서 맨 앞에 "용어 정의" 섹션을 두고, 조금이라도 헷갈릴 수 있는 단어는 전부 명시적으로 정의해두는 걸 원칙으로 하고 있어요.

 

리뷰를 한 번만 받고 끝내는 것

문서를 다 쓰고 딱 한 번 리뷰 받고 확정하면, 리뷰어들이 문서 전체를 처음부터 끝까지 훑느라 지쳐서 디테일을 놓치기 쉽습니다.
요즘은 초안이 30% 정도 채워졌을 때 방향만 먼저 가볍게 확인받고, 80% 정도 채워졌을 때 본격적인 리뷰를 받는 식으로 두 번에 나눠서 진행하고 있어요.
이렇게 하니 방향이 완전히 잘못된 채로 문서를 다 채우는 낭비도 줄고, 리뷰어들도 좀 더 집중해서 봐주는 것 같습니다.

 

요구사항 정의서는 결국 "내가 아는 걸 다른 사람도 똑같이 알게 만드는 도구"라는 생각이 듭니다.
제가 저지른 실수들을 돌이켜보면 대부분 "나는 알고 있으니 됐다"고 생각한 부분을 문서에 옮기지 않아서 생긴 문제였어요.

 

앞으로도 계속 비슷한 실수를 반복하겠지만, 최소한 이번에 정리한 여섯 가지는 문서 쓰기 전에 체크리스트로 붙여두고 확인하려고 합니다.