스펙 주도 개발의 명세는 요구를 대문자 SHALL 로 쓰고, 조건을 문장 앞에 두고, 그 아래에 시나리오를 붙이는 정해진 모양을 하고 있습니다. 이 글은 그 세 가지 틀, RFC 2119·EARS·시나리오가 요구사항 문장에서 각각 어떤 모호함을 줄이는지 정리한 것입니다.
출발점은 명세가 구현이 아니라 바깥에서 보이는 행동을 적는 «행동 계약»이라는 생각입니다. 인용은 RFC 와 OpenSpec 의 개념 문서·명세 작성 문서 같은 공개 문서에서 영어 그대로 옮겼고, 예시는 가상의 «회의실 예약 서비스»로 적었습니다. 제 해석이 들어간 곳은 해석이라고 표시했습니다.
행동만 적기로 했다고 해서 문장이 저절로 명확해지지는 않습니다. 자연어는 같은 문장도 읽는 사람마다 다르게 읽히기 쉽습니다. 명세가 문장 틀을 정해 두는 것은 그 때문인데, 들여다보니 틀마다 줄이려는 모호함이 달랐습니다.
RFC 2119 — 의무의 강도를 정하는 어휘
대문자 SHALL 의 출처는 1997년 3월 S. Bradner 가 쓴 RFC 2119(BCP 14)입니다. 초록은 짧습니다. «In many standards track documents several words are used to signify the requirements in the specification.» 많은 표준 문서가 요구를 나타내려고 몇몇 낱말을 쓰는데, 이 문서는 그 낱말들을 IETF 문서에서 어떻게 해석할지 정한다는 것입니다. 표준 문서마다 «반드시»와 «권장»을 섞어 쓰면 구현하는 쪽마다 다르게 읽고, 그러면 서로 맞물려야 할 구현들이 어긋납니다.
| 낱말 | 원문 정의 | 풀이 |
|---|---|---|
MUST · SHALL |
«an absolute requirement of the specification» | 예외 없는 절대 요구 |
SHOULD |
«there may exist valid reasons in particular circumstances to ignore a particular item, but the full implications must be understood and carefully weighed» | 특정한 상황에서 따르지 않을 타당한 이유가 있을 수 있지만, 그 결과를 충분히 이해하고 따져 본 뒤에야 다르게 갈 수 있음 |
MAY |
«an item is truly optional» | 정말로 선택 |
2017년의 RFC 8174는 여기에 한 가지를 분명히 했습니다. 이 낱말들은 대문자로 쓸 때만 이런 특별한 뜻을 갖는다는 것입니다. 소문자 should 는 그냥 영어의 should 입니다. 명세의 SHALL 이 늘 대문자인 이유가 여기에 있습니다.
OpenSpec 은 이 어휘를 그대로 가져와 «RFC 2119 keywords (SHALL, MUST, SHOULD, MAY) communicate intent», 의도를 전하는 데 쓴다고 적습니다. 명세 작성 문서의 권고는 «Reach for MUST/SHALL by default.», 기본은 MUST 나 SHALL 이고, SHOULD 는 정당한 예외의 여지를 둔 강한 권고일 때만 쓰라는 것입니다. 제 생각에는 이 권고가 중요한 지점입니다. SHOULD 를 «되도록이면» 정도의 부드러운 말투로 쓰기 시작하면, 그 요구는 지켜지지 않아도 위반이 아닌 요구가 되어 버립니다.
EARS — 조건이 앉을 자리를 정하는 문형
RFC 2119 가 의무의 강도를 정한다면, EARS(Easy Approach to Requirements Syntax)는 문장의 모양을 정합니다. Alistair Mavin 과 동료들이 Rolls-Royce 에서 제트엔진 제어 시스템의 감항(airworthiness) 규정을 분석하면서 만들었고, 2009년 RE'09 학회에서 처음 발표했습니다. 자연어로 쓴 요구가 모호하고, 중복되고, 장황하고, 시험할 수 없게 되는 문제를 줄이려는 문형 틀입니다.
EARS 는 요구를 몇 가지 패턴으로 나눕니다. 원문의 틀은 이렇습니다.
Ubiquitous The <system name> shall <system response>
State driven While <precondition(s)>, the <system name> shall <system response>
Event driven When <trigger>, the <system name> shall <system response>
Optional feature Where <feature is included>, the <system name> shall <system response>
Unwanted behaviour If <trigger>, then the <system name> shall <system response>
Complex While 와 When 을 함께 씀틀을 보면 조건이 앉는 자리가 문장 맨 앞으로 정해져 있습니다. 상태는 While, 사건은 When, 선택 기능은 Where, 원치 않는 상황은 If 로 시작하니, 문장 구조만 보고도 조건과 반응을 가를 수 있습니다. 조건이 문장 끝에 붙거나 여러 절에 흩어져 있으면, 그 조건이 반응 전체에 걸리는지부터 헷갈립니다.
AWS 의 Kiro 는 요구 문서인 requirements.md 를 이 EARS 로 씁니다. Kiro 문서의 틀은 «WHEN [condition/event] THE SYSTEM SHALL [expected behavior]»이고, 예시는 «WHEN a user submits a form with invalid data THE SYSTEM SHALL display validation errors next to the relevant fields»입니다. EARS 의 사건 패턴에 RFC 2119 의 대문자 강도를 얹은 모양입니다. 회의실 예약 서비스로 옮기면 이렇게 됩니다.
Event driven When a user books a room, the booking system shall send a confirmation email.
State driven While a room is under maintenance, the booking system shall hide it from search results.
Unwanted behaviour If a booking overlaps an existing booking for the same room,
then the booking system shall reject it with a conflict message.시나리오 — 해석을 구체 사례로 묶기
강도와 조건을 정해도 남는 모호함이 있습니다. «겹친다»는 것이 정확히 무엇인지 같은 것입니다. 앞 예약이 10시에 끝나고 다음 예약이 10시에 시작하면 겹치는 걸까요. 이런 것은 문장을 아무리 다듬어도 읽는 사람마다 다르게 읽힐 수 있습니다. 시나리오는 그 자리에 구체적인 사례를 박아 둡니다.
OpenSpec 문서는 «Scenarios are the "when" — they provide concrete examples that can be verified.»라고 적습니다. 시나리오는 확인할 수 있는 구체 사례라는 뜻입니다.
명세 작성 문서는 나쁜 시나리오도 짚습니다. «A scenario that just restates the requirement in other words tests nothing.», 요구를 다른 말로 되풀이할 뿐인 시나리오는 아무것도 시험하지 않는다는 것입니다. 시나리오의 제목에도 경우의 이름을 적으라고 합니다. «Scenario: Rejects an expired token» 은 무엇을 다루는지 한눈에 알려 주지만, «Scenario: Test 2» 는 그렇지 않습니다.
#### Scenario: Back-to-back bookings do not overlap
- GIVEN a booking for Room A from 09:00 to 10:00
- WHEN a user books Room A from 10:00 to 11:00
- THEN the booking is accepted이 시나리오 하나로 «끝 시각과 시작 시각이 같으면 겹치지 않는다»는 해석이 고정됩니다. 행복한 경로만이 아니라 이런 경계의 경우를 적어야 시나리오가 제 몫을 한다는 생각이 들었습니다.
요구 하나의 크기에 대한 권고도 있습니다. «A good requirement is one behavior, stated so plainly you could hand it to someone else to test.» 좋은 요구는 행동 하나이고, 남에게 건네 시험하게 할 수 있을 만큼 평이해야 한다는 것입니다. «The system SHALL handle large uploads gracefully» 는 무엇을 보면 통과인지 알 수 없지만, «The system SHALL show an error banner when the upload exceeds 10 MB» 는 10MB 를 넘는 파일을 올려 보면 확인할 수 있습니다.
GIVEN·WHEN·THEN 문형 자체는 Dan North 가 2006년 «Introducing BDD»에서 소개한 행동 주도 개발(BDD)에서 왔습니다. 인수 기준을 이 문형으로 적는 이야기는 «기획 문서의 종류와 체계 (3): TRD·ADR·API Spec과 검증»에 적은 적이 있어 여기서는 줄입니다.
세 가지 틀은 세 가지 모호함을 줄입니다
셋을 나란히 놓고 보니, 각각 다른 종류의 모호함을 맡고 있다는 생각이 들었습니다. 아래 분류는 출처의 말이 아니라 제 해석입니다.
| 틀 | 줄이는 모호함 | 묻는 질문 |
|---|---|---|
| RFC 2119 | 강도의 모호함 | 이것은 반드시인가, 권장인가, 선택인가 |
| EARS | 조건의 모호함 | 언제, 어떤 상태에서 이 반응이 일어나는가 |
| 시나리오 | 해석의 모호함 | 이 낱말은 구체적으로 어떤 경우를 뜻하는가 |
셋은 서로 대신하지 않습니다. 대문자 SHALL 을 써도 조건이 흐릿할 수 있고, EARS 틀을 지켜도 «겹친다»의 뜻은 정해지지 않습니다. 그래서 OpenSpec 의 요구가 SHALL 문장 아래에 시나리오를 두는 모양을 하고 있는 것이라고 읽었습니다.
정리하면, 자연어로 쓴 요구에는 의무의 강도, 조건의 자리, 해석의 범위라는 세 가지 모호함이 있고, RFC 2119 의 대문자 어휘와 EARS 의 문형, 시나리오의 구체 사례가 그것을 하나씩 맡습니다. 명세가 왜 구현을 빼고 행동만 적는지, 왜 전체가 아니라 델타로 바꾸는지, 명세를 얼마나 오래 붙드는지는 «스펙 주도 개발에서 명세는 무엇을 적는가»에 정리했습니다.