요구사항에서 시작하기, 품질 속성과 드라이버 - 두 개의 아키텍처 정의서 ep.02

기능 목록은 무엇을 만들지 말해준다. 어떻게 지을지는 말해주지 않는다.

정의서를 쓸 때 흔한 출발점은 기능 목록입니다. 그런데 기능만 보면 구조가 나오지 않습니다. 구조를 끌어내는 것은 따로 있습니다. 품질 속성(quality attributes) 과 제약입니다. 이번 편은 그 출발점을 바로잡습니다.

기능은 구조를 결정하지 않는다

스폿의 기능은 단순합니다. 장소를 기록하고, 검색하고, 공유하고, 요약을 받습니다. 그런데 이 기능들은 모놀리스로도, 마이크로서비스로도, 서버리스로도 만들 수 있습니다. 기능만으로는 어느 구조를 골라야 할지 알 수 없습니다.

기능 요구사항과 품질 속성을 좌우로 비교하는 그림. 왼쪽 카드는 회색 톤의 '기능 요구사항 · 무엇을 하는가'로, 장소를 기록한다, 장소를 검색한다, 기록을 공유한다, 기록 요약을 받는다 네 항목이 체크 표시와 함께 나열되고, 아래에 '거의 어떤 구조로도 만족시킬 수 있다'고 적혀 있다. 오른쪽 카드는 틸색 테두리의 '품질 속성 · 얼마나 잘 하는가'로, 검색은 1초 안에 응답, 지도 API 장애에도 본 기능 생존, 이미지 트래픽 폭증에도 견딤, 위치 정보는 새지 않음 네 항목이 점 표시와 함께 나열되고, 아래에 '구조를 가르는 것은 이쪽이다'라고 적혀 있다. 캡션은 같은 기능을 만족하는 구조는 많고, 그중 하나를 고르게 만드는 것이 품질 속성이라고 말한다.

구조를 가르는 질문은 “무엇을 하는가”가 아니라 “얼마나 잘 하는가”입니다. 검색이 얼마나 빨라야 하는가, 외부 API가 죽으면 어디까지 버텨야 하는가, 위치 정보를 누가 볼 수 있는가. 이 질문들의 답이 구조를 결정합니다.

품질 속성으로 말하기

“빨라야 한다”는 요구사항은 검증할 수 없습니다. 무엇이 얼마나 빨라야 하는지가 빠졌기 때문입니다. 그래서 품질 속성은 시나리오(scenario) 로 적습니다.

널리 쓰이는 형식은 여섯 부분으로 나뉩니다. 자극의 출처, 자극, 대상, 환경, 응답, 그리고 응답의 측정값입니다. 전부 적을 필요는 없지만, 적어도 “어떤 상황에서, 무엇이, 얼마만큼”은 들어가야 합니다.

예를 들어 스폿의 가용성 시나리오는 이렇게 적힙니다. “정상 운영 중(환경) 지도 API가 응답하지 않을 때(자극), 시스템은 검색 기능만 저하시키고 나머지는 정상 동작시킨다(응답). 비검색 기능 가용성은 99.9% 이상이다(측정).” 이렇게 적으면 나중에 그 구조가 요구를 만족하는지 확인할 수 있습니다.

스폿의 드라이버

스폿의 품질 속성을 여섯 가지로 정리했습니다. 모두 같은 무게는 아닙니다. 이 중 우선순위가 높은 것이 아키텍처 드라이버(architecture driver), 즉 구조를 실제로 끌고 가는 것들입니다.

스폿의 여섯 가지 품질 속성을 보여주는 유틸리티 트리. 왼쪽에 틸색 테두리의 루트 박스 '스폿 아키텍처 드라이버'가 있고, 거기서 여섯 개의 곡선 연결선이 오른쪽 여섯 카드로 뻗는다. 각 카드는 품질 속성 이름과 시나리오를 담는다. 가용성은 지도 API가 죽어도 검색 외 기능은 계속 동작한다, 성능은 정상 부하에서 장소 검색 P95 응답이 1초 이내다, 확장성은 이미지 업로드가 10배로 늘어도 본문 응답이 흔들리지 않는다, 보안은 비공개 위치 기록은 작성자 본인만 조회할 수 있다, 유지보수성은 지도 벤더를 바꿔도 호출부 코드 변경이 어댑터 안에 갇힌다, 비용은 LLM 요약 호출 비용을 월 한도 안에서 통제한다.

표로 정리하면 시나리오와 측정이 한눈에 들어옵니다.

품질 속성	시나리오 (자극 → 응답)	측정
가용성	지도 API 응답 불가 → 검색만 저하, 나머지 정상	비검색 기능 가용성 99.9%
성능	정상 부하의 검색 요청 → 즉시 응답	검색 P95 1초 이내
확장성	이미지 업로드 10배 증가 → 본문 응답 유지	P95 열화 10% 이내
보안	타인이 비공개 기록 접근 시도 → 차단	무단 조회 0건
유지보수성	지도 벤더 교체 → 어댑터만 수정	변경이 어댑터 모듈에 한정
비용	LLM 호출 급증 → 한도 내 제어	월 비용 상한 준수

드라이버가 구조를 끌고 간다

드라이버는 그냥 목록이 아닙니다. 각각이 구조적 압력이 되어 구체적인 설계 결정으로 이어집니다. 그리고 그 결정의 근거가 다음 단계에서 ADR의 맥락 항목이 됩니다.

품질 드라이버가 설계 결정으로 이어지는 매핑 그림. 왼쪽 열은 품질 드라이버, 오른쪽 열은 설계 결정으로 ep.04 ADR과 연결된다. 다섯 행이 화살표로 연결된다. 가용성 핵심 경로 격리는 서킷 브레이커와 캐싱으로 이어지며 ADR-003, 비용 부가 기능 분리는 큐 기반 비동기 처리로 이어지며 ADR-002, 유지보수성 벤더 락인 회피는 어댑터로 외부 API 격리로 이어지며 ADR-001, 확장성 이미지 트래픽은 오브젝트 스토리지 분리로 이어지며 ADR-004, 보안 위치 민감정보는 OAuth 위임과 접근 통제로 이어지며 ADR-005다. 캡션은 드라이버가 구조를 끌고 가며 각 결정의 근거가 곧 ADR의 맥락 항목이 된다고 말한다.

여기서 외부 API를 둘로 나눈 설계가 의미를 갖습니다. 지도 API는 핵심 경로라 가용성 드라이버가 서킷 브레이커를 부르고, LLM API는 부가 기능이라 비용·가용성 드라이버가 비동기 큐를 부릅니다. 같은 “외부 의존성”인데도 드라이버가 다르니 결정이 갈립니다.

두 문서에서의 품질 요구사항

품질 속성은 두 문서가 가장 먼저 갈라지는 지점입니다.

	내부 공유용	SI 납품용
표현	우선순위 높은 3-4개에 집중, 시나리오 중심	비기능 요구사항(NFR) 전 항목, ID 부여
측정값	팀이 합의한 목표치, 자주 갱신	계약·RFP 기준값으로 고정, 검수 대상
추적	결정과 느슨하게 연결	요구사항 ID와 설계와 테스트가 추적 가능하게 연결

내부용은 “지금 우리가 신경 쓰는 품질”을 적습니다. 우선순위가 바뀌면 문서도 바뀝니다. 납품용은 “계약이 요구한 품질”을 빠짐없이 적습니다. 빠지면 감리에서 지적됩니다. 같은 가용성 99.9%라도, 한쪽에서는 팀의 목표이고 다른 쪽에서는 요구사항 NFR-007 같은 추적 단위입니다.

참고 자료

Len Bass, Paul Clements, Rick Kazman. Software Architecture in Practice. (품질 속성 시나리오)
arc42. arc42 Documentation Template. https://arc42.org
ISO/IEC 25010. Systems and software Quality Requirements and Evaluation (SQuaRE) — Product quality model.

다음 편 예고

ep.03 - 뷰를 그리다, C4와 4+1

드라이버가 정해졌으면 이제 시스템을 그릴 차례입니다. 같은 시스템도 논리·프로세스·배포 관점에서 다르게 보입니다. 다음 편에서는 C4 네 단계와 4+1 뷰로 스폿을 여러 장에 나눠 그리고, 두 문서가 같은 그림을 어떻게 다르게 싣는지 봅니다.