요구사항을 “상세하게 써 달라”는 말에는 합격선이 없다. 그래서 받는 쪽은 늘 어디까지 써야 하는지 모른 채 쓰고, 주는 쪽은 다 쓴 다음에야 부족하다고 말한다.
그런데 합격선을 아예 문서에 적어 둔 곳이 셋 있다. 한국 공공 발주 가이드, 미국 항공우주국, 그리고 롤스로이스 엔지니어들이 만든 문장 규칙이다. 셋이 서로를 모르고 만들어졌는데 재는 지점이 겹치지 않고 갈린다. 그래서 셋을 한 문장에 차례로 대 보면 그 문장이 쓸 만한지 꽤 정확하게 나온다.
이름부터 정리하고 가자
같은 것을 부르는 말이 너무 많아서 첫 회의부터 어긋난다. 제안요청서는 발주 문서 전체다. 사업 개요와 일정, 평가 기준까지 들어간다. 요구사항 정의서는 그 안에 들어가는 요구사항 목록이고, 공공사업에서는 「요구사항 내용 작성표」라는 정해진 서식으로 쓴다.
기술요구서라고 부르는 자리도 많다. 다른 문서가 아니라 같은 것을 부르는 관행어다. 소프트웨어공학 교과서에서는 요구사항 명세서, 영어로는 SRS라고 부른다. 제품팀이 쓰는 PRD는 결이 조금 다른데 그 구분은 개발 회의 용어를 정리한 글에 적어 뒀다.
이름이 무엇이든 안에 들어가는 것은 문장이다. 그래서 이 글은 서식이 아니라 문장을 다룬다. 빈 서식을 받아도 칸을 무엇으로 채울지 모르면 아무것도 달라지지 않는다.
첫째 자, 그 문장으로 규모를 셀 수 있나
한국 공공사업에는 이 합격선이 숫자로 박혀 있다. 과기정통부 쪽에서 낸 공공SW사업 제안요청서 작성을 위한 요구사항 상세화 실무 가이드는 요구사항을 “기능점수(간이법) 산정이 가능하도록” 상세화하라고 적어 뒀다. 기능점수는 소프트웨어의 규모를 세는 단위다. 즉 그 문장을 읽고 이게 몇 인분짜리 일인지 셀 수 있어야 통과다.
이 기준이 좋은 이유는 사람마다 다르게 읽히지 않아서다. “회원 관리 기능을 구현한다”는 셀 수 없다. “회원 정보를 등록, 수정, 삭제, 조회한다”는 셀 수 있다. 같은 말 같은데 뒤엣것에는 셀 것이 네 개 들어 있다.
가이드는 그 깊이도 네 단계로 갈라 놓았다. 1단계가 단위 업무시스템, 2단계가 주요 업무 기능, 3단계가 세부기능, 4단계가 세부기능의 활동이다. 그리고 요구사항의 제목은 3단계에서 뽑고 내용은 4단계로 쓰라고 한다. 제목이 “회원 관리”면 내용은 “등록, 수정, 삭제, 조회”까지 내려가야 한다는 뜻이다.
같은 문서에 이 기준을 한 줄로 줄여 놓은 문장이 있다. 요구사항 상세화의 핵심은 “컨셉”이 아니라 “동작되는 기능”을 적는 것이라고. 개선 전 상태를 뭐라고 적어 뒀는지도 같이 보면 뜻이 분명해진다. “목적과 방향성 등 개념, 컨셉 수준 제시”였다.
이 가이드는 2021년판이고, 근거는 소프트웨어 진흥법 제44조 2항이다. 발주할 때 사업자가 과업 규모를 산정할 수 있도록 요구사항을 상세하게 작성해 공개하라고 되어 있다. 규모를 셀 수 있게라는 말이 법에 먼저 있고 가이드가 그걸 기능점수로 옮긴 셈이다. 그 뒤에 개정판이 나왔는지는 확인하지 못했다.
둘째 자, 나중에 재 볼 수 있나
셀 수 있다고 다 되는 게 아니다. 다 만든 다음에 합격인지 불합격인지 판정할 수 있어야 한다. 미국 항공우주국이 시스템 엔지니어링 핸드북 부록에 좋은 요구사항 쓰는 법을 따로 붙여 놨는데, 여기서 제일 쓸모 있는 건 쓰지 말라고 나열해 둔 단어 목록이다.
flexible, easy, sufficient, safe, adequate, user-friendly, usable, appropriate, fast, robust, quickly, easily, clearly. 그리고 as appropriate, etc., and/or, but not limited to. 우리말로 옮기면 유연하게, 쉽게, 충분히, 적절히, 빠르게, 안정적으로, 사용자 친화적으로, 기타 등등이다.
이 단어들의 공통점은 검수 자리에서 판정이 안 된다는 것이다. “빠르게 응답해야 한다”를 놓고 만든 쪽은 됐다고 하고 시킨 쪽은 안 됐다고 한다. 둘 다 문서를 근거로 든다. 문서가 판정을 못 하게 쓰여 있으니 판정은 목소리 큰 쪽이 이긴다.
같은 문서에 조동사 셋을 갈라 놓은 대목도 있다. shall은 요구사항, will은 사실이나 목적 서술, should는 목표다. 우리말에는 이 구분이 없어서 더 위험하다. “제공한다”, “제공할 예정이다”, “제공하면 좋다”가 한 표 안에 섞여 들어가고, 검수 때 셋이 같은 무게로 읽히지 않는다.
하나 더. 요구사항에는 구현 방법을 적지 말라고 되어 있다. 무엇을 할지가 요구사항이고 어떻게 만들지는 만드는 쪽 몫이다. 이걸 섞어 쓰면 나중에 더 나은 방법이 나와도 문서 때문에 못 바꾸는 일이 생긴다.
셋째 자, 언제 그런지가 문장 앞에 있나
셋째는 문장의 모양이다. EARS는 롤스로이스 엔지니어들이 제트엔진 제어 시스템의 감항 규정을 분석하다가 만든 문장 틀이고 2009년에 처음 발표됐다. 요구사항은 다섯 가지 중 하나라고 보고, 각각의 첫머리에 붙일 단어를 정해 뒀다.
| 어떤 요구인가 | 문장 틀 | 예 |
|---|---|---|
| 늘 그래야 함 | 시스템은 ~한다 | 이 화면은 3초 안에 첫 그림을 그린다 |
| 어떤 상태일 때 | ~인 동안, 시스템은 ~한다 | 카드가 안 꽂혀 있는 동안, 화면에 “카드를 넣으세요”를 표시한다 |
| 어떤 일이 생기면 | ~하면, 시스템은 ~한다 | 무음을 고르면, 모든 소리 출력을 끈다 |
| 그 기능이 있을 때만 | ~가 있는 경우, 시스템은 ~한다 | 선루프가 있는 경우, 운전석 문에 조작판을 둔다 |
| 일이 잘못되면 | 만약 ~하면, 시스템은 ~한다 | 만약 카드번호가 유효하지 않으면, “다시 입력하세요”를 표시한다 |
틀 자체가 대단한 건 아니다. 쓸모는 다른 데 있다. 다섯 개를 놓고 보면 빠뜨린 줄이 눈에 띈다. 대부분의 요구사항 정의서는 첫 줄과 셋째 줄만 들어 있고 마지막 줄이 없다. 잘못됐을 때 무엇을 하는지가 안 적혀 있다는 뜻이고, 그게 개발 막바지에 “이 경우는 얘기 안 했는데요”로 돌아온다.
조건을 문장 뒤가 아니라 앞에 붙이는 것도 이유가 있다. 뒤에 붙이면 읽는 사람이 조건을 만나기 전에 이미 기능을 머릿속에 그려 버린다.
세 자를 한 문장에 대 보면
이 블로그의 이미지 만드는 도구를 고칠 때 스스로에게 건 요구가 하나 있다. 카드 이미지 크기를 바꿀 수 있게 고치되, 기존 1200×630 결과물은 예전 파일과 픽셀 단위로 동일해야 한다는 것이었다.
세 자를 대 보면 이렇다. 셀 수 있나. 바꿀 대상이 하나고 지켜야 할 것이 하나니 규모가 잡힌다. 재 볼 수 있나. 예전 파일과 새 파일을 바이트로 비교하면 답이 나온다. 언제 그런가. 1200×630으로 뽑을 때라고 앞에 붙어 있다.
실제로 고친 뒤에 예전 카드를 다시 뽑아 비교했고 차이가 0이었다. 여기서 중요한 건 차이가 0이었다는 사실이 아니라, 0인지 아닌지를 아무하고도 상의하지 않고 알 수 있었다는 점이다. “기존 카드가 망가지지 않게 해 주세요”라고 적었으면 그 확인을 할 방법이 없었다.
같은 도구를 고치면서 반대 경우도 나왔다. 채널마다 쓸 배너를 공용으로 하나만 만들자는 것까지는 정해졌는데, 그 파일을 어디에 둘지가 안 정해져 있었다. 요구사항 안에 빈칸이 하나 있었던 것이다.
앞서 나온 나사 문서에 이 상황을 다루는 대목이 있다. 정해지지 않은 값을 TBD로 적어 두는 대신 TBR로, 그러니까 “정해야 할 것”으로 적고 언제 누가 정할지를 같이 남기라는 것이다. 빈칸을 비워 두지 말라는 게 아니라 빈칸에 이름을 붙이라는 말이다. 이름이 없는 빈칸은 아무도 자기 일이라고 생각하지 않는다.
기능만 적고 나머지를 빠뜨리는 문제
요구사항 정의서를 처음 쓰면 화면과 기능만 적게 된다. 앞의 공공 가이드는 여기서 도움이 되는데, 소프트웨어사업에서 나올 수 있는 요구사항을 15가지로 갈라 놓았기 때문이다. 이 중 기능은 하나뿐이다.
기능, 성능, 시스템 장비구성, 인터페이스, 데이터, 테스트, 보안, 품질, 제약사항, 프로젝트 관리, 프로젝트 지원, 유지관리 수행, 유지관리 인력, 컨설팅, 공사. 각각에 SFR, PER 같은 세 글자 코드가 붙어 있어서 요구사항 번호만 봐도 종류를 안다.
이 목록을 외울 필요는 없다. 다 쓴 다음에 훑어보며 한 줄도 없는 칸을 찾는 용도로 쓰면 된다. 대개 테스트와 유지관리 쪽이 비어 있고, 그 두 칸이 비어 있으면 검수 기준과 인수인계가 통째로 협상거리가 된다.
서식 자체는 일곱 칸이다. 분류, 고유번호, 명칭, 상세설명, 산출정보, 관련 요구사항, 그리고 요구사항 출처. 마지막 칸이 눈에 띈다. 이 요구를 누가 왜 원했는지를 적으라는 칸인데, 이게 있으면 나중에 요구가 바뀔 때 누구와 이야기해야 하는지가 문서에 남는다.
어디부터 고칠까
이미 쓴 문서가 있다면 다 고치지 말고 두 가지만 훑어보길 권한다. 첫째, 위 금지어 목록에 걸리는 줄을 찾아 숫자나 판정 방법으로 바꾼다. 둘째, 잘못됐을 때 어떻게 되는지를 적은 줄이 몇 개인지 센다. 두 번째가 0이면 그게 지금 제일 큰 구멍이다.
새로 쓴다면 순서를 뒤집는 편이 빠르다. 서식을 먼저 열지 말고 문장부터 쓴다. 문장 하나에 세 자를 대 보고 통과한 것만 표에 옮긴다. 서식을 먼저 열면 칸을 채우는 일이 목표가 되고, 칸은 아무 말이나 넣어도 채워진다.
마지막으로 밝힐 것이 있다. 나는 공공사업 발주도 수주도 해 본 적이 없다. 위의 기준은 공개된 가이드와 법조문, 그리고 나사와 EARS 문서를 읽고 정리한 것이고, 예로 든 요구사항은 공문서가 아니라 이 블로그를 굴리면서 내가 나에게 쓴 작업 지시에서 가져왔다. 크기는 훨씬 작지만 판정이 되느냐 안 되느냐는 똑같이 갈렸다. 프로젝트 전체를 어느 순서로 굴리는지가 더 급하다면 개발 순서를 정리한 글 쪽이 먼저다.