본문으로 건너뛰기
series develop backend infra devops architecture documentation adr

SI 납품용으로 변환하기, 화석을 인정하는 문서 만들기 - 두 개의 아키텍처 정의서 ep.07

어떤 문서는 살리는 것이 답이 아니다. 잘 죽이는 것이 답이다.

지난 편에서 내부용 정의서를 거짓말하지 않는 살아있는 문서로 만들었습니다. 이번 편은 정반대입니다. 그 문서를 SI 납품용으로 변환합니다. 납품용은 살릴 수 없는 문서, 처음부터 화석이 운명인 문서입니다. 마지막 과제는 그 죽음을 부정하지 않고 인정하는 것입니다.

살릴 수 없는 문서

ep.06의 살아있는 문서는 코드와 한 저장소에 살며 계속 갱신됐습니다.

그러나 SI 납품용 정의서는 그렇게 둘 수 없습니다. 특정 시점에 산출물로 제출되고, 그 시점이 계약과 검수의 기준이 되기 때문입니다. 제출 이후에도 계속 바뀐다면 무엇을 검수했는지가 불분명해집니다.

그래서 납품용 정의서는 화석이 될 수밖에 없습니다. 여기서 중요한 태도 전환이 일어납니다. 화석을 거짓말처럼 막아야 할 실패로 보지 않고, 납품이라는 행위의 본질로 받아들이는 것입니다. 박제임을 인정하면, 박제를 잘하는 방법에 집중할 수 있습니다.

추적성: 끊긴 곳이 없어야 한다

납품용 정의서의 심장은 추적성입니다. 모든 요구사항이 어떤 설계로 충족되고 어떤 테스트로 검증되는지가 끊김 없이 이어져야 합니다.

요구사항과 설계·결정과 테스트를 잇는 추적성 매트릭스. 세 열로 구성된다. 왼쪽 요구사항 열에는 REQ-001 가용성(지도 장애 시 검색 외 생존), REQ-002 성능(검색 P95 1초 이내), REQ-003 보안(비공개 기록 소유자 제한), REQ-004 비용(LLM 호출 한도 통제)이 있다. 가운데 설계·결정 열에는 각각 ADR-003과 컨테이너 뷰(서킷 브레이커+캐싱), 캐싱과 런타임 뷰(캐시 적중 경로), ADR-005 접근 통제(OAuth+행 수준 권한), ADR-002 비동기 큐(큐+워커 처리)가 있다. 오른쪽 테스트 열에는 각각 TC-AV-01(지도 API 차단 시나리오), TC-PF-01(부하 시 응답 측정), TC-SE-01(타인 조회 차단 검증), TC-CO-01(한도 초과 시 동작)이 있다. 각 행은 요구사항에서 설계를 거쳐 테스트로 화살표로 이어진다. 캡션은 모든 요구사항이 설계·결정을 거쳐 테스트로 이어져야 하며, 끊긴 행이 없어야 감리 종료 단계를 통과한다고 설명한다.

내부용에서는 ADR이 “왜 그렇게 했나”의 일지였습니다. 납품용에서는 같은 ADR이 추적표의 한 칸이 됩니다.

요구사항 REQ-001이 ADR-003으로 충족되고 TC-AV-01로 검증된다는 연결이 명시되어야, 감리원이 “이 요구사항은 어떻게 충족됩니까”라고 물을 때 답할 수 있습니다.

살아있는 문서를 화석으로

변환은 무언가를 더하고 무언가를 고정하는 작업입니다.

살아있는 내부용 문서를 납품용 화석으로 변환하는 그림. 왼쪽에는 틸색 테두리의 내부용 살아있는 문서가 있고 계속 갱신된다고 적혀 있다. 가운데 박제라는 앰버색 화살표가 특정 시점이라는 설명과 함께 오른쪽으로 향한다. 오른쪽에는 앰버색 테두리에 퇴적층과 검수 도장이 있는 납품용 화석 문서가 있고 시점 이후 고정이라고 적혀 있다. 오른쪽 위 패널은 변환 시 추가되는 것으로 버전·승인 이력(누가 언제), 비어 있던 섹션 모두 채움, 요구사항 ID와 설계와 테스트 매핑, 검수 기준과 인수 조건을 든다. 오른쪽 아래 패널은 동결되는 것으로 모든 뷰는 제출 시점 스냅샷, 다이어그램은 정돈해 고정, ADR은 결론 목록과 근거로 정리를 든다. 캡션은 살아 있던 문서를 죽이는 작업이 아니라 특정 시점의 진실을 증빙으로 봉인하는 작업이며, 감리와 검수는 이 봉인된 시점을 기준으로 적합 여부를 판정한다고 설명한다.

더하는 것은 증빙입니다.

버전과 승인 이력은 “누가 언제 이 문서를 책임졌는가”를 남기고, 내부용에서 생략했던 섹션을 모두 채웁니다. 비어 있는 칸은 내부용에서는 합리적 생략이지만 납품용에서는 누락입니다. 고정하는 것은 시점입니다. 코드에서 생성하던 다이어그램도 제출 시점 스냅샷으로 정돈해 박제하고, append-only 로그였던 ADR은 결론 중심 목록으로 정리합니다.

공공 SI라는 맥락

납품용 정의서가 화석이어야 하는 이유는 공공 SI의 제도적 맥락에서 더 분명해집니다.

공공부문 정보시스템은 표준 기반 위에서 구축됩니다.

전자정부 표준프레임워크(eGovFrame)는 행정기관·공공기관 정보시스템 구축의 표준 기반 기술로, 2009년 개발된 이후 지속적으로 보급되어 온 공공부문 대표 개발 프레임워크입니다. 이 프레임워크는 행정안전부와 한국지능정보사회진흥원(NIA)이 주관합니다. 2025년에는 신규 버전 5.0이 공개되었습니다.

산출물의 적정성은 감리로 점검됩니다.

전자정부법에 따라 일정 규모 이상의 공공 정보화 사업은 정보시스템 감리를 의무적으로 받아야 합니다. 감리의 근거는 행정안전부가 고시한 「정보시스템 감리기준」과 「행정기관 및 공공기관 정보시스템 구축·운영 지침」 등입니다. 종료 단계 감리에서는 요구사항별로 적합·부적합·점검제외를 판정하고, 부적합이나 점검제외로 분류된 항목은 시정조치를 거치며, 그래도 해소되지 않으면 발주자가 검수 단계에서 판단합니다.

이 구조가 납품용 정의서의 성격을 결정합니다.

정의서는 특정 시점의 산출물로 제출되고, 감리와 검수는 그 시점을 기준으로 적합 여부를 따집니다. 그러니 정의서는 그 시점에 박제되어야 하고, 추적표는 끊긴 곳이 없어야 합니다. (감리 대상 기준이나 적용 절차의 세부는 사업 규모·유형과 관련 고시 개정에 따라 달라질 수 있으므로, 실제 사업에서는 해당 시점의 전자정부법령과 고시를 확인하는 것이 안전합니다.)

SI 납품용 정의서 목차

위 원칙을 목차로 옮기면 이렇습니다.

ep.06의 내부용 목차와 같은 재료를 쓰지만, 문서 정보와 추적표와 인수인계가 더해지고 모든 섹션이 채워집니다.

# 스폿(Spot) 아키텍처 정의서 (납품용)

문서 정보
- 버전 / 작성일 / 작성자 / 검토자 / 승인자
- 변경 이력 (버전별 일시 · 내용 · 승인)

1. 개요 (목적 · 범위 · 용어 정의)
2. 시스템 개요와 제약
3. 요구사항
   - 기능 요구사항
   - 비기능 요구사항 (NFR, ID 부여)
4. 아키텍처 뷰 (제출 시점 스냅샷)
   - 컨텍스트 / 컨테이너 / 컴포넌트 (C4 L1부터 L3)
   - 런타임 뷰 / 배포 뷰
5. 아키텍처 결정 (ADR 요약 목록 + 근거)
6. 횡단 관심사 (보안 · 개인정보 준수 포함)
7. 요구사항 추적표 (REQ ↔ 설계 ↔ 테스트)
8. 인수인계 및 운영 이관 사항
부록. 자동 생성 산출물 (API 명세 / 스키마 / 의존성)

화석을 닫다

이렇게 첫 번째 죽음, 화석을 닫습니다. 거짓말을 막을 때와는 정반대 방법입니다. 거짓말은 문서를 살려서 닫았고, 화석은 죽음을 인정해서 닫습니다.

시리즈를 닫는 대칭 그림. 위쪽 왼쪽 틸색 패널은 두 번째 죽음 거짓말로, 코드는 변하고 문서는 멈춰 둘이 어긋나며, 닫는 법은 문서를 살려서 닫는다(ep.06)이고 손으로 동기화할 표면을 없애 거짓말할 자리를 지운다고 적혀 있다. 위쪽 오른쪽 앰버색 패널은 첫 번째 죽음 화석으로, 특정 시점에 고정되어 그대로 굳으며, 닫는 법은 죽음을 인정해서 닫는다(ep.07)이고 박제임을 받아들이고 시점·추적·검수로 증빙한다고 적혀 있다. 아래쪽에는 재탄생 흐름이 있다. 납품용 화석 문서(시점 스냅샷+추적표)가 인수인계를 거쳐 유지보수·운영팀으로, 다시 심음을 거쳐 새 살아있는 문서(ep.06 원칙으로 다시 운영, 새싹 아이콘)로 이어진다. 캡션은 내부용에서 살아 있던 문서가 납품용에서 화석이 되고 인수인계를 통해 유지보수팀의 살아있는 문서로 다시 태어나며, 정의서는 두 번 다 죽지만 두 죽음을 모두 닫으면 문서는 끊기지 않고 이어진다고 말한다.

그리고 화석은 끝이 아닙니다. 잘 만든 납품용 정의서는 인수인계의 출발점이 됩니다.

유지보수·운영팀이 그 화석을 넘겨받아 자기 저장소에 옮기고, ep.06의 원칙으로 다시 살아있는 문서로 운영하기 시작합니다.

내부용에서 살아 있던 문서가 납품용에서 화석이 되었다가, 인수인계를 통해 또 다른 살아있는 문서로 다시 태어납니다.

시리즈를 닫으며

여덟 편을 관통한 질문은 하나였습니다. 아키텍처 정의서는 왜 그렇게 자주 쓸모를 잃는가.

답은 정의서가 두 가지로 죽기 때문이었습니다. 납품용은 시점에 고정되어 화석이 되고, 내부용은 코드와 어긋나 거짓말이 됩니다. 그래서 우리는 문서를 독자와 수명이라는 두 축으로 다시 보고, 표준(42010·arc42·C4·ADR)이라는 공통 도구를 익히고, 드라이버에서 뷰와 결정과 횡단 관심사로 재료를 쌓은 뒤, 같은 재료로 두 개의 정의서를 만들었습니다.

내부용은 거짓말할 자리를 없애 살렸고, 납품용은 죽음을 인정해 박제했습니다. 정의서는 두 번 다 죽지만, 두 죽음을 각자의 방식으로 닫으면 문서는 끊기지 않고 다음 사람에게 이어집니다.

좋은 정의서는 영원히 사는 문서가 아니라, 잘 죽고 잘 이어지는 문서입니다.

참고 자료

  • 전자정부 표준프레임워크 오픈커뮤니티. https://open.egovframe.org
  • 행정안전부. 「정보시스템 감리기준」(고시) / 「행정기관 및 공공기관 정보시스템 구축·운영 지침」.
  • 전자정부법 및 같은 법 시행령 (정보시스템 감리 관련 조항).
  • ISO/IEC/IEEE 42010. Systems and software engineering — Architecture description.
  • Michael Nygard. (2011). Documenting Architecture Decisions.