요구사항 문서: “빠르게”를 검증 가능한 문장으로 바꾸기

요구사항 문서는 “좋게 만들자”를 “무엇을 만족해야 통과인가”로 바꾸는 문서다. 이 층위에는 SRS, SyRS, FRD, NFR, Acceptance Criteria, Traceability Matrix가 들어간다. 같은 입력인데 어떤 환경에서만 요구사항가 도드라졌다. 같은 단어를 쓰더라도 제품 문맥이 다르면 답이 갈렸다. 그 갈림길을 숨기지 않는 쪽으로 썼다.

요구사항이 커진 문제

ISO/IEC/IEEE 29148은 요구사항 공학과 요구사항 산출물의 기준을 다룬다. NASA의 요구사항 작성 가이드는 좋은 요구사항이 necessary, verifiable, attainable, clear, correct, complete, consistent, traceable해야 한다고 정리한다. 핵심은 검증 가능성이다. 요구사항 문서의 목적은 문장을 많이 쓰는 것이 아니다. 나중에 “이건 됐다 / 안 됐다”를 말할 수 있게 만드는 것이다. 이 문장은 테스트로 옮기기 쉽다. 동시에 제품 문장으로도 읽힌다. 개발자, 디자이너, 운영자가 같은 기준을 볼 수 있다. 특히 요구사항에서는 재현 조건을 같이 적어야 의미가 있었다. 참고: NASA requirements guide — https://www.nasa.

처음에는 "빠르게"로 충분할 줄 알았다

참고: ISO/IEC/IEEE 29148 — https://standards.ieee.org/ieee/29148/6937/ Acceptance Criteria는 “이 정도면 통과”라는 기준이다. 구현자가 만든 내부 함수 목록이 아니라 사용자가 보는 결과와 경계 조건을 적어야 한다. NFR은 non-functional requirements다. 성능, 보안, 가용성, 확장성, 접근성, 관측 가능성 같은 품질 조건을 다룬다. 이름 때문에 기능보다 덜 중요한 것처럼 보이지만 실제 제품 실패는 NFR에서 자주 나온다. md - 1GB 이하 파일 전송 중 네트워크가 10초 이하로 끊겼다가 복구되면 사용자는 파일을 처음부터 다시 선택하지 않고 이어서 전송할 수 있어야 한다. - 관리자는 예약 요청 상세 화면에서 승인, 보류, 거절 결정을 2단계 이하의 조작으로 수행할 수 있어야 한다. - 검색 요청의 95%는 정상 부하 조건에서 300ms 안에 첫 결과를 반환해야 한다. 문제는 요구사항 문서가 길어서 어려운 게 아니다. 검증할 수 없는 말이 요구사항처럼 남을 때 어렵다. “빠르게”, “안정적으로”, “쉽게”, “안전하게”는 방향은 맞지만 그대로는 테스트할 수 없다.

검증 불가가 선명해진 순간

이제 테스트할 수 있다. 안정성, 사용성, 빠름이라는 말이 조건과 기준으로 바뀌었기 때문이다. 좋은 acceptance criteria는 given/when/then으로 정리할 수 있다. 특히 요구사항에서는 재현 조건을 같이 적어야 의미가 있었다. ```md

• 요청 상세는 모바일 4G 환경에서 2초 안에 주요 상태가 보여야 한다.
• 상담 요청에는 민감 정보가 포함될 수 있으므로 공개 URL에서 원문을 노출하지 않는다.
• 관리자는 최근 30일 요청을 상태별로 필터링할 수 있어야 한다.
• 상태 변경 이벤트는 장애 조사 시 추적할 수 있어야 한다. md Given 사용자가 상담 요청을 보냈고 상태가 보류로 바뀌었다. When 사용자가 요청 상세 페이지를 연다. Then 현재 상태가 보류로 표시되고, 추가로 필요한 정보가 무엇인지 안내된다. 특히 요구사항에서는 재현 조건을 같이 적어야 의미가 있었다. ```md REQ-03: 사용자는 보류 사유를 확인할 수 있어야 한다.
• Design: request status detail card
• Test: pending status detail renders reason and next action
• Risk: 사유가 너무 내부 용어로 노출되면 사용자가 이해하지 못한다. ```

이 조건들은 사용자가 직접 “기능”이라고 부르지 않을 수 있다. 하지만 빠지면 제품은 곧바로 불안해진다. 특히 요구사항에서는 재현 조건을 같이 적어야 의미가 있었다. 요구사항를 설명할 때 서버/클라이언트/사용자 중 누구 문장으로 말하는지 먼저 고르면 논쟁이 줄었다.

검증 가능한 문장으로 경계 나누기

SRS는 software requirements specification이다. 소프트웨어가 만족해야 할 기능과 조건을 적는다. SyRS는 system requirements specification으로, 소프트웨어 밖의 장치, 사람, 외부 시스템까지 포함한 시스템 요구사항에 가깝다. FRD는 functional requirements document다. 기능 동작을 더 직접적으로 다룬다. 이 정도만 있어도 나중에 요구사항을 바꿀 때 어디를 봐야 하는지 알 수 있다. 특히 요구사항에서는 재현 조건을 같이 적어야 의미가 있었다. ```md - 파일 전송은 안정적이어야 한다. - 관리자 화면은 사용하기 쉬워야 한다. - 검색은 빠르게 동작해야 한다. 예를 들어 “상담 요청을 저장한다”는 기능 요구사항이다. 하지만 다음 질문은 NFR에 가깝다.

구현과 운영에 남긴 조건

Traceability Matrix는 요구사항과 설계, 구현, 테스트를 연결한다. 작은 팀에서는 표까지 만들 필요가 없을 수 있다. 하지만 결제, 권한, 의료/법률 문서, 보안처럼 실패 비용이 큰 영역에서는 “이 테스트가 어떤 요구사항을 지키는가”를 추적할 수 있어야 한다. 이 문장들은 좋은 의도를 담고 있지만 요구사항으로는 약하다. 무엇을 측정해야 하는지 알 수 없다.

더 나은 문장은 이렇게 바뀐다. 특히 요구사항에서는 재현 조건을 같이 적어야 의미가 있었다. ISO/IEC/IEEE 29148은 요구사항 공학과 요구사항 산출물의 기준을 다룬다. NASA의 요구사항 작성 가이드는 좋은 요구사항이 necessary, verifiable, attainable, clear, correct, complete, consistent, traceable해야 한다고 정리한다. 핵심은 검증 가능성이다. 요구사항 문서의 목적은 문장을 많이 쓰는 것이 아니다. 나중에 “이건 됐다 / 안 됐다”를 말할 수 있게 만드는 것이다.

특히 요구사항에서는 재현 조건을 같이 적어야 의미가 있었다. 이 문장은 테스트로 옮기기 쉽다. 동시에 제품 문장으로도 읽힌다. 개발자, 디자이너, 운영자가 같은 기준을 볼 수 있다. 특히 요구사항에서는 재현 조건을 같이 적어야 의미가 있었다. '요구사항 문서: “빠르게”를 검증 가능한 문장으로 바꾸기'을 관통하는 질문은 이 섹션에서도 같았고, 답만 더 구체적이 됐다.

관측 포인트

참고: NASA requirements guide — https://www.nasa. 참고: ISO/IEC/IEEE 29148 — https://standards.ieee.org/ieee/29148/6937/ Acceptance Criteria는 “이 정도면 통과”라는 기준이다. 구현자가 만든 내부 함수 목록이 아니라 사용자가 보는 결과와 경계 조건을 적어야 한다. NFR은 non-functional requirements다. 성능, 보안, 가용성, 확장성, 접근성, 관측 가능성 같은 품질 조건을 다룬다. 이름 때문에 기능보다 덜 중요한 것처럼 보이지만 실제 제품 실패는 NFR에서 자주 나온다. md - 1GB 이하 파일 전송 중 네트워크가 10초 이하로 끊겼다가 복구되면 사용자는 파일을 처음부터 다시 선택하지 않고 이어서 전송할 수 있어야 한다. - 관리자는 예약 요청 상세 화면에서 승인, 보류, 거절 결정을 2단계 이하의 조작으로 수행할 수 있어야 한다. - 검색 요청의 95%는 정상 부하 조건에서 300ms 안에 첫 결과를 반환해야 한다.

문제는 요구사항 문서가 길어서 어려운 게 아니다. 검증할 수 없는 말이 요구사항처럼 남을 때 어렵다. “빠르게”, “안정적으로”, “쉽게”, “안전하게”는 방향은 맞지만 그대로는 테스트할 수 없다.

마치며

이제 테스트할 수 있다. 안정성, 사용성, 빠름이라는 말이 조건과 기준으로 바뀌었기 때문이다. 좋은 acceptance criteria는 given/when/then으로 정리할 수 있다. md - 요청 상세는 모바일 4G 환경에서 2초 안에 주요 상태가 보여야 한다. - 상담 요청에는 민감 정보가 포함될 수 있으므로 공개 URL에서 원문을 노출하지 않는다. - 관리자는 최근 30일 요청을 상태별로 필터링할 수 있어야 한다. - 상태 변경 이벤트는 장애 조사 시 추적할 수 있어야 한다. 특히 요구사항에서는 재현 조건을 같이 적어야 의미가 있었다. ```md Given 사용자가 상담 요청을 보냈고 상태가 보류로 바뀌었다. When 사용자가 요청 상세 페이지를 연다. Then 현재 상태가 보류로 표시되고, 추가로 필요한 정보가 무엇인지 안내된다.