13.2 요구사항 명세와 변경 — 모호한 기대를 검증 가능한 계약으로 바꾼다
발견한 목표와 제약은 그대로 구현할 수 없다. “빠르게”, “안전하게”, “사용하기 쉽게” 같은 표현은 사람마다 다른 시스템을 떠올리게 한다. 이 문서는 기능과 품질을 관찰 가능한 조건으로 명세하고, 요구사항의 출처에서 설계·검증까지 추적해 변경의 영향을 판단하는 방법을 다룬다.
학습 목표
- 기능 요구사항, 품질 요구사항, 제약과 acceptance criteria의 역할을 구분한다.
- 모호한 품질 목표를 측정 가능한 품질 속성 시나리오로 변환한다.
- 요구사항의 필요성·명확성·실현 가능성·일관성·검증 가능성을 검토한다.
- 양방향 추적성과 기준선을 사용해 요구사항 변경의 영향을 분석한다.
배경: 명세는 자세한 문장이 아니다
다음 요구사항은 자세해 보인다.
시스템은 최신 메시징 기술을 사용해 확장 가능하고 안정적인 실시간 주문 취소 기능을 제공해야 한다.
그러나 무엇을 만들고 어떻게 성공을 판단할지 알 수 없다. “최신”, “확장 가능”, “안정적”, “실시간”의 기준이 없고 메시징이라는 해법을 미리 고정했다. 상세한 형용사가 명세의 정확성을 보장하지 않는다.
명세(specification)는 이해관계자 사이의 기대를 구현·검증 가능한 경계 계약으로 바꾸는 일이다. 좋은 요구사항은 독자가 같은 의미를 복원하고, 충족 여부를 유한한 증거로 판단하며, 왜 필요한지 추적할 수 있어야 한다. 모든 세부를 미리 결정하라는 뜻은 아니다. 불필요한 세부를 고정하면 설계 공간만 줄어든다.
핵심 개념
요구사항의 종류는 질문이 다르다
| 종류 | 답하는 질문 | 주문 취소 예 |
|---|---|---|
| 기능 요구사항 | 시스템이 어떤 입력에 어떤 행위를 제공하는가? | 구매자는 출고 전 주문의 전체 취소를 요청할 수 있다 |
| 품질 요구사항 | 특정 환경에서 행위를 얼마나 잘 수행해야 하는가? | 결제사 장애 중에도 요청의 99.9%를 잃지 않고 2초 안에 접수를 알린다 |
| 제약 | 해법이 반드시 지켜야 할 외부 한계는 무엇인가? | 환불 기록은 규정상 정해진 기간 동안 변경 이력과 함께 보존한다 |
| 인터페이스 요구사항 | 외부 경계에서 교환할 계약은 무엇인가? | 물류 시스템은 출고 중지 요청에 접수·거절·미확정 상태를 반환한다 |
기능과 품질은 완전히 분리되지 않는다. “취소한다”는 기능도 시간, 오류, 권한과 상태 계약 없이는 의미가 불완전하다. 분류의 목적은 문서를 나누는 것이 아니라 질문 누락을 찾는 것이다.
use case와 acceptance criteria는 서로 다른 확대경이다
use case는 행위자와 시스템 사이의 목표 지향 상호작용, 정상 흐름과 대안·예외 흐름을 보여 준다. acceptance criteria는 특정 기능 조각을 받아들일 수 있는 관찰 가능한 조건을 좁게 정의한다.
Use case: 출고 전 주문 전체 취소
주 행위자: 구매 고객
사전 조건: 고객이 주문 소유자이며 주문이 취소 가능한 상태다.
기본 흐름:
1. 고객이 취소 사유와 함께 요청한다.
2. 시스템이 정책과 현재 출고 상태를 확인한다.
3. 시스템이 요청을 접수하고 고객에게 현재 상태를 반환한다.
대안 흐름:
- 이미 출고된 주문이면 거절 이유를 반환한다.
- 같은 요청이 반복되면 기존 취소 요청의 상태를 반환한다.
- 외부 결제 상태가 미확정이면 접수 상태를 유지한다.이 use case에서 acceptance criteria 하나를 구체화하면 다음과 같다.
Given 결제 완료됐지만 출고되지 않은 주문과 그 주문의 구매자가 있고
When 구매자가 같은 idempotency key로 취소를 두 번 요청하면
Then 시스템은 하나의 취소 요청만 기록하고
And 두 응답은 같은 취소 요청 식별자와 상태를 반환한다Given–When–Then 형식이 자동으로 좋은 요구사항을 만들지는 않는다. 내부 함수 호출과 화면 픽셀을 과도하게 명시하면 구현 결합만 높아진다. 이해관계자가 관찰할 행위와 중요한 경계 조건에 집중한다.
품질 속성 이름만으로는 설계를 이끌 수 없다
ISO/IEC 25010 같은 품질 모델은 성능 효율성, 신뢰성, 보안, 유지보수성 등 누락을 점검하는 어휘를 제공한다. 그러나 “고가용성”, “변경 용이성”이라는 이름만으로는 아키텍처를 평가할 수 없다. 같은 시스템도 어떤 자극과 환경을 상정하느냐에 따라 필요한 구조가 달라진다.
품질 속성 시나리오(quality attribute scenario)는 여섯 요소로 품질 목표를 구체화한다.
| 요소 | 질문 | 주문 취소 예 |
|---|---|---|
| source | 누가 또는 무엇이 자극을 만드는가? | 정상 인증된 고객 |
| stimulus | 어떤 사건이 발생하는가? | 결제사 응답이 30초간 지연되는 동안 취소 요청 |
| environment | 어떤 운영 조건인가? | 평상시 부하, 단일 결제사 지연 |
| artifact | 무엇이 영향을 받는가? | 취소 접수 API와 요청 저장소 |
| response | 시스템이 어떻게 반응하는가? | 요청을 내구성 있게 기록하고 접수 상태를 반환 |
| response measure | 무엇으로 충족을 판정하는가? | 월간 요청의 99.9%에서 2초 이내 응답, 접수된 요청 유실 0건 |
한 문장으로 합치면 다음과 같다.
평상시 부하에서 단일 결제사가 30초 동안 응답하지 않을 때, 인증된 고객이 취소를 요청하면 주문 시스템은 요청을 내구성 있게 기록하고 월간 요청의 99.9%에서 2초 안에 접수 상태를 반환하며 접수된 요청을 잃지 않는다.
이제 동기 대기, 비동기 처리, 시간 제한, 내구성 저장을 같은 조건에서 비교할 수 있다. 숫자는 장식이 아니다. 왜 2초와 99.9%인지, 측정 구간과 모집단은 무엇인지, 비용이 정당한지 이해관계자와 협상해야 한다.
품질 속성은 서로 거래된다
한 시나리오를 최적화하면 다른 속성에 비용을 줄 수 있다.
- 모든 취소를 동기 처리하면 상태 이해는 단순하지만 외부 지연이 응답성·가용성으로 전파된다.
- 비동기 처리하면 접수 응답과 장애 격리를 개선하지만 일시적 불일치와 운영 복잡성이 생긴다.
- 상세 감사 로그는 추적성을 높이지만 저장 비용, 개인정보 노출과 삭제 의무가 늘어난다.
- 고객지원의 강제 취소 권한은 복구 가능성을 높이지만 보안·감사 통제를 강화해야 한다.
따라서 품질 요구는 각각 독립된 체크박스가 아니다. 우선순위와 허용 가능한 열화를 함께 기록한다. 장애 환경에서 처리량을 낮추더라도 데이터 무결성을 지키는 선택처럼 어떤 상황에서 무엇을 포기할지가 설계를 이끈다.
좋은 요구사항의 검토 기준
요구사항 하나를 다음 질문으로 검토한다.
- 필요성: 어느 목표·이해관계자·제약에서 왔는가?
- 단일성: 독립적으로 검증할 수 없는 여러 의무를 한 문장에 묶지 않았는가?
- 명확성: 행위자, 조건, 용어와 경계가 같은 의미로 읽히는가?
- 실현 가능성: 기술·비용·시간 제약 안에서 가능한가? 확인할 실험은 무엇인가?
- 일관성: 다른 요구, 상태 모델, 외부 계약과 충돌하지 않는가?
- 검증 가능성: 유한한 관찰·분석·시연·테스트로 충족 여부를 판정할 수 있는가?
- 해법 중립성: 필요한 결과보다 구현을 불필요하게 고정하지 않는가?
- 추적성: 출처와 영향을 받는 설계·검증을 찾을 수 있는가?
“시스템은 모든 장애에서 데이터를 절대 잃지 않아야 한다”는 검증 범위가 무한하고 실현 가능성도 판단할 수 없다. 어떤 데이터가 언제 접수된 것으로 간주되는지, 포함할 장애 모델, 허용 가능한 복구 시점과 손실 범위를 명시해야 한다.
용어와 상태 모델은 명세의 일부다
같은 “취소”가 요청 접수, 정책 승인, 결제 환불, 물류 중지와 최종 완료를 모두 뜻하면 문장이 아무리 정확해도 모순이 생긴다. 용어집과 상태 모델로 의미를 고정한다.
PAID ── 취소 접수 ──▶ CANCEL_REQUESTED
│ │
│ ├── 결제·물류 보상 완료 ─▶ CANCELED
│ └── 정책/외부 거절 ─────▶ CANCEL_REJECTED
└── 출고 시작 ───────────▶ FULFILLING이 그림은 구현 상태 머신을 강제하기 위한 것이 아니라 허용 전이, 최종성, 경쟁 사건을 토론하는 분석 모델이다. 취소 접수와 취소 완료를 구분하면 API 응답과 운영 지표의 의미도 달라진다.
기준선 — 합의한 요구 집합을 비교점으로 만든다
요구사항 기준선(baseline)은 영원히 고정된 문서가 아니라 특정 시점에 합의해 설계·구현·검증의 비교점으로 삼는 집합이다. 이후 변경은 금지하지 않고 변경 전후를 식별한다.
기준선에는 최소한 다음이 필요하다.
- 요구사항 식별자와 현재 상태
- 출처·근거·우선순위·소유자
- 적용 버전 또는 릴리스
- 중요한 가정과 외부 의존성
- 연결된 설계 결정과 검증 방법
Git 커밋만으로 버전은 남길 수 있지만 변경 이유와 승인된 범위까지 자동으로 남지는 않는다. 도구보다 의미 있는 변경 단위를 정하는 것이 먼저다.
추적성 — 변경 질문에 답하는 그래프
추적성은 다음 두 방향을 모두 지원해야 한다.
- forward trace: 이 요구가 어떤 설계 요소, 코드, 테스트와 운영 지표로 실현되는가?
- backward trace: 이 설계 복잡성과 검증 비용은 어느 목표·요구 때문에 존재하는가?
작은 예시는 다음과 같다.
| 요구사항 | 출처 | 설계/결정 | 검증 |
|---|---|---|---|
| FR-CAN-01 중복 요청은 한 번만 처리 | 중복 환불 사고 INC-17 | 취소 요청 키의 유일성, ADR-004 | 동시 중복 요청 테스트, 중복 환불 지표 |
| QA-RES-02 99.9%가 2초 내 접수 | 고객 문의 분석 CS-12 | 내구성 큐와 즉시 접수 응답, ADR-004 | 장애 주입 부하 실험 |
| CON-AUD-01 환불 변경 이력 보존 | 감사 규정 FIN-3 | append-only 감사 이벤트 | 감사 샘플 추적 |
모든 줄을 모든 파일에 연결하면 유지 비용이 폭발한다. 아키텍처를 좌우하거나 규제·안전·재무 위험이 큰 요구부터 추적 깊이를 높인다. 링크의 개수보다 변경 질문에 답할 수 있는지가 중요하다.
변경 영향 분석 — 문장 수정 전에 파급을 찾는다
“전체 취소만 지원”을 “항목별 부분 취소 지원”으로 바꾼다고 하자. UI 필드 하나의 변경처럼 보이지만 다음을 질문해야 한다.
- 어떤 목표와 증거 때문에 변경하는가?
- 상태·불변식·데이터 소유권이 어떻게 달라지는가?
- 기존 요구와 외부 계약 중 무엇과 충돌하는가?
- 어떤 모듈·ADR·테스트·운영 절차가 영향을 받는가?
- 마이그레이션 중 이전 주문은 어떤 의미를 가지는가?
- 비용과 새 위험을 반영해 우선순위를 유지할 것인가?
추적 그래프는 후보를 찾게 하지만 영향의 의미를 자동 판정하지 않는다. 사람은 경계 계약과 불변식을 읽고 직접 판단해야 한다.
실무 관점
숫자가 있다고 검증 가능한 것은 아니다
“응답시간 200ms”에 측정 시작·종료, 요청 종류, 데이터 크기, 부하, 백분위가 없으면 팀마다 다른 결과를 낸다. 평균만 쓰면 극단적으로 느린 요청을 숨길 수 있다. 반대로 모든 품질 목표를 세밀한 SLO로 만들면 유지 비용이 커진다. 아키텍처를 바꾸는 중요한 품질 속성부터 측정 경계를 명확히 한다. 운영 SLI·SLO 설계는 챕터 14에서 심화한다.
acceptance criteria가 요구사항 전체를 대체하지 않는다
개별 스토리의 예시가 시스템 수준의 보안·복구·변경 용이성을 모두 표현하지 못한다. 예시 기반 조건과 품질 속성 시나리오, 상태·데이터 불변식, 외부 계약을 필요한 만큼 조합한다.
변경 관리가 승인 위원회와 동의어는 아니다
변경을 느리게 만드는 절차가 목적이 아니다. 영향과 결정권을 위험에 비례하게 만든다. 문구 수정과 결제 정합성 모델 변경을 같은 절차로 처리하지 않는다. 작은 팀도 기준선, 근거, 영향, 결정 결과를 pull request와 ADR로 가볍게 남길 수 있다.
요구사항 문서를 코드처럼 다룬다는 말의 한계
버전 관리, 리뷰, 자동 링크 검사는 도움이 된다. 그러나 컴파일 성공이 의미의 합의를 보장하지 않는다. 요구사항의 중요한 오류는 문법보다 이해관계자 누락, 잘못된 경계와 측정할 수 없는 기대에서 생긴다.
정리
- 명세는 자세한 문장이 아니라 같은 의미와 검증 결과를 복원할 수 있는 계약이다.
- 품질 모델은 누락을 찾는 어휘이고, 품질 속성 시나리오는 설계를 평가할 구체적 자극·반응·측정 기준이다.
- 요구사항은 필요성·명확성·실현 가능성·일관성·검증 가능성과 해법 중립성을 검토해야 한다.
- 기준선은 변경을 막지 않고 변경 전후를 비교하게 한다.
- 양방향 추적성은 요구에서 설계·검증으로, 설계 복잡성에서 원래 근거로 이동하게 한다.
확인 문제
- “시스템은 초당 10,000건을 처리해야 한다”에 어떤 정보가 더 있어야 아키텍처를 평가할 수 있는가?
- 부분 취소 요구가 추가됐을 때 traceability matrix가 알려 주는 것과 알려 주지 못하는 것은 무엇인가?
- “모든 취소 요청은 정확히 한 번 처리한다”를 검증 가능한 요구사항으로 바꿀 때 먼저 정의할 경계는 무엇인가?
정답과 해설
- 요청 종류와 혼합, payload·데이터 조건, 동시 사용자, 정상/장애 환경, 응답시간과 오류율 목표, 지속 시간과 측정 위치가 필요하다. 처리량만 만족하며 지연과 실패가 무한정 커지는 설계는 의도한 품질을 충족하지 않을 수 있다.
- 연결된 상태 모델, 모듈, ADR, 테스트 후보를 찾게 한다. 그러나 각 영향의 의미, 새 불변식, 마이그레이션 위험과 변경이 정당한지는 사람이 분석해야 한다.
- 요청의 동일성, 접수 시점, 처리 결과, 관찰 범위와 장애 모델을 정의해야 한다. 외부 결제사까지 포함해 절대적 exactly-once를 약속하기보다 내부 기록의 유일성과 외부 호출의 멱등 처리 같은 검증 가능한 계약으로 분해해야 한다.
참고 자료
- ISO/IEC/IEEE 29148:2018: 요구사항의 특성, 명세 정보 항목과 수명 주기 프로세스의 기준이다.
- ISO/IEC 25010:2023: 제품 품질 요구를 빠짐없이 검토하기 위한 9개 품질 특성의 참조 모델이다.
- Quality Attribute Workshop Collection: 이해관계자의 품질 목표를 시나리오로 생성·통합·우선순위화하는 자료다.
- Applicability of General Scenarios to the ATAM: 일반 품질 시나리오와 실제 ATAM 평가 시나리오의 관계를 분석한다.