"무엇을 썼는가"보다 "왜 선택했는가"를 기록하기

운영 콘솔 아키텍처 시리즈 9/9

아키텍처 문서를 쓸 때 가장 쉬운 방식은 구성도를 그리고 사용한 기술을 나열하는 것이다.

React, S3, CloudFront, API Gateway, Lambda, RDB, Express.

이 정보도 필요하다. 하지만 시간이 지나면 더 중요한 질문이 남는다.

왜 그렇게 했는가?

문제 상황

운영 콘솔은 한 번 만들고 끝나는 도구가 아니다. 기능이 추가되고, 사용자 범위가 바뀌고, 데이터가 늘고, 장애가 발생한다. 그때마다 처음 설계한 사람이 모든 맥락을 기억하고 있을 수는 없다.

특히 다음 질문은 반복해서 돌아온다.

• 왜 콘솔을 하나로 합치지 않았는가
• 왜 RDB를 쓰지 않았는가
• 왜 Lambda 앞에 API Gateway를 뒀는가
• 왜 일부 API는 상주 서버로 처리했는가
• 왜 리포트 생성을 비동기로 만들었는가

이 질문에 답하려면 사용한 기술 목록이 아니라 당시의 제약과 선택지를 기록해야 한다.

선택지

첫 번째 방식은 README에 현재 구조만 적는 것이다. 빠르게 쓸 수 있지만, 의사결정의 배경은 사라진다.

두 번째 방식은 장애나 변경이 있을 때마다 회고 문서를 쓰는 것이다. 유용하지만 사후 기록에 가깝다.

세 번째 방식은 Architecture Decision Record, 즉 ADR 형태로 중요한 결정을 남기는 것이다. 결정이 내려진 시점의 맥락과 대안을 함께 기록한다.

운영 콘솔 문서에는 ADR 방식을 적용했다.

문서 구조

내가 가장 유용하게 느낀 템플릿은 단순하다.

## 결정 제목

### 배경

어떤 문제를 풀고 있었는가?

### 고려한 선택지

선택 가능한 대안은 무엇이었는가?

### 결정

무엇을 선택했는가?

### 선택한 이유

왜 이 선택이 현재 조건에 맞았는가?

### 포기한 것

이 선택으로 잃은 것은 무엇인가?

### 다시 검토할 조건

언제 이 결정을 바꿔야 하는가?

중요한 것은 "포기한 것"과 "다시 검토할 조건"이다. 좋은 아키텍처 결정은 모든 면에서 좋은 선택이 아니다. 지금의 제약에서 가장 합리적인 선택일 뿐이다.

예시 1. 정적 호스팅 결정

나쁜 기록은 이렇게 끝난다.

React SPA는 S3와 CloudFront에 배포한다.

이 문장은 결과만 있다. 나중에 누군가 "왜 EC2가 아니지?"라고 물으면 다시 설명해야 한다.

조금 더 나은 기록은 다음처럼 쓴다.

React SPA는 S3와 CloudFront에 배포한다.

운영 콘솔은 서버 사이드 렌더링이 필요 없고, 빌드 결과물이 정적 파일이다.
EC2와 Nginx를 사용하면 OS 패치, 웹 서버 설정, 인스턴스 장애 대응 책임이 생긴다.
트래픽 규모와 운영 인력을 고려하면 S3와 CloudFront가 더 단순하다.

단, SPA 라우팅 fallback과 CloudFront 캐시 무효화는 배포 과정에서 반드시 처리해야 한다.

이렇게 쓰면 결정의 배경과 주의점이 함께 남는다.

예시 2. RDB를 쓰지 않은 결정

기술 문서에는 도입한 기술만 기록하기 쉽다. 하지만 도입하지 않은 기술도 기록해야 한다.

신청 관리 콘솔에는 RDB를 두지 않는다.

데이터 원천은 이미 스프레드시트에 있고, 애플리케이션은 이를 읽기 좋게 캐싱해 보여주는 역할이다.
데이터 규모가 작고 변경 빈도가 낮으므로 객체 저장소의 JSON 스냅샷으로 충분하다.

복잡한 검색, 동시 수정, 관계형 조회가 필요해지면 RDB 도입을 다시 검토한다.

이 기록은 미래의 변경 기준을 함께 제공한다. 데이터가 커지거나 검색 요구가 늘면, 그때는 결정을 바꿀 수 있다.

용어집을 따로 둔 이유

ADR과 별도로 용어집도 유용했다. CORS, preflight, cold start, connection pool, Source of Truth 같은 단어는 팀원마다 이해 수준이 다를 수 있다.

단순한 사전 정의보다 프로젝트 맥락을 붙이는 것이 중요하다.

### Preflight

브라우저가 본 요청 전에 보내는 OPTIONS 요청이다.
이 콘솔에서는 JSON API와 인증 헤더를 사용하기 때문에 자주 발생한다.
OPTIONS는 API Gateway에서 처리하고, 실제 Lambda는 본 요청만 처리하도록 구성한다.

이렇게 쓰면 용어 설명이 곧 운영 맥락이 된다.

얻은 것

문서가 온보딩 자료가 됐다. 새로 합류한 사람이 전체 코드를 읽기 전에 왜 이런 구조인지 먼저 이해할 수 있다.

"무엇을 만들었다"보다 "왜 이렇게 설계했다"를 말할 수 있다.

장애 대응에도 도움이 된다. 예를 들어 CORS 문제가 생겼을 때, 과거 문서에 "OPTIONS는 Gateway에서 처리한다"는 결정이 있으면 확인할 위치가 좁아진다.

포기한 것

문서를 쓰는 시간은 분명히 든다. 모든 작은 결정을 ADR로 남기면 문서가 너무 많아진다.

그래서 기준이 필요하다. 다음 중 하나에 해당하면 기록할 만하다.

• 나중에 다시 질문받을 가능성이 높은 결정
• 비용, 보안, 장애 영향 범위와 관련된 결정
• 선택하지 않은 대안이 충분히 그럴듯한 결정
• 되돌리기 어려운 결정
• 팀원이 오해하기 쉬운 결정

다시 설계한다면

처음부터 문서 파일의 이름 규칙을 정하겠다. 예를 들어 001-static-hosting.md, 002-api-gateway.md처럼 번호를 붙이면 결정의 흐름을 추적하기 쉽다.

또한 각 ADR에 상태를 두겠다.

Proposed
Accepted
Superseded
Deprecated

시간이 지나 결정이 바뀌었을 때 예전 문서를 지우지 않고, 어떤 결정이 무엇으로 대체됐는지 남길 수 있다.

정리

아키텍처 문서는 사용한 기술 목록이 아니다. 당시의 제약, 선택지, 결정, 포기한 것, 다시 검토할 조건을 남기는 기록이다.

"무엇을 썼는가"는 구성도를 보면 알 수 있다. 하지만 "왜 그렇게 했는가"는 기록하지 않으면 사라진다. 운영 콘솔처럼 오래 쓰는 도구일수록, 의사결정 기록은 코드만큼 중요한 운영 자산이 된다.

함께 볼 GitHub 저장소

• ops-console-architecture-playbook