기술 용어집을 프로젝트 맥락으로 쓰는 이유

문서화와 인수인계 시리즈 5/9

프로젝트 문서에 용어집이 필요한가?

처음에는 과해 보일 수 있다. CORS, Lambda, CloudFront, API Gateway 같은 용어는 검색하면 정의가 나온다. 공식 문서도 있고, 블로그 글도 많다.

하지만 프로젝트 안에서의 용어집은 일반 사전과 역할이 다르다.

일반 사전은 "무엇인가"를 설명한다.

프로젝트 용어집은 "이 프로젝트에서 왜 중요한가"를 설명한다.

문제 상황

운영 콘솔 문서를 정리하면서 여러 기술 용어가 반복해서 등장했다.

• CORS
• preflight
• API Gateway
• Lambda Function URL
• Lambda Layer
• CloudFront
• Cache TTL
• invalidation
• SSO cookie
• withCredentials
• Source of Truth
• job table
• connection pool
• cold start

각 용어는 따로 보면 어렵지 않다. 하지만 프로젝트 맥락 안에서는 서로 연결되어 있다.

예를 들어 CORS는 단순한 브라우저 오류가 아니다. SPA 도메인과 API 도메인이 분리되었기 때문에 발생하는 설계 요소다.

Lambda Layer도 단순한 라이브러리 묶음이 아니다. 배포 파일을 가볍게 만들고, 함수 코드만 빠르게 업데이트하기 위한 운영 전략이다.

이 차이를 문서에 남기지 않으면 새 담당자는 용어의 일반 정의는 알아도, 이 시스템에서 왜 문제가 되는지는 다시 파악해야 한다.

좋은 용어집의 구조

프로젝트 용어집은 다음 구조가 좋다.

### 용어

- 정의: 일반적인 의미
- 이 프로젝트에서의 의미: 왜 중요한지
- 함께 봐야 할 것: 관련 설정, 파일, 문서

예를 들어 CORS는 이렇게 쓸 수 있다.

### CORS

- 정의: 브라우저가 다른 출처의 API 호출을 제한하고, 서버가 허용 헤더로 예외를 알려주는 보안 표준.
- 이 프로젝트에서의 의미: React SPA 도메인과 API 도메인이 달라 모든 JSON API 호출에 CORS 설정이 필요하다.
- 함께 봐야 할 것: API Gateway OPTIONS 설정, Lambda 응답 헤더, 프론트엔드 credentials 옵션.

이렇게 쓰면 용어가 지식이 아니라 운영 힌트가 된다.

일반 정의만으로 부족한 이유

예를 들어 preflight를 검색하면 다음 정도의 설명을 찾을 수 있다.

브라우저가 본 요청 전에 OPTIONS 메서드로 서버에 허용 여부를 확인하는 요청

정확한 설명이다. 하지만 운영 담당자에게는 다음 정보가 더 필요하다.

• 우리 API에서는 언제 preflight가 발생하는가
• 이 요청은 Lambda까지 가는가
• API Gateway에서 처리하는가
• 누락되면 어떤 오류가 나는가
• 테스트는 어떻게 하는가

그래서 프로젝트 용어집에는 이렇게 덧붙여야 한다.

이 프로젝트의 API는 대부분 JSON 요청이므로 preflight가 자주 발생한다. OPTIONS 요청은 API Gateway MOCK Integration에서 처리하고, Lambda를 호출하지 않는 것이 원칙이다. 특정 path에서 CORS 오류가 나면 OPTIONS method와 integration이 누락되었는지 먼저 확인한다.

이 한 문단이 장애 대응 시간을 줄인다.

용어집은 온보딩 문서다

새로운 담당자가 프로젝트에 들어왔을 때 가장 힘든 것은 낯선 용어가 아니라, 익숙한 용어가 이 프로젝트에서 어떤 의미로 쓰이는지 모르는 것이다.

예를 들어 Source of Truth라는 말은 많이 쓴다. 하지만 시스템마다 원천 데이터는 다르다.

한 콘솔에서는 스프레드시트가 Source of Truth일 수 있다.

다른 콘솔에서는 RDB가 Source of Truth일 수 있다.

S3 JSON 파일은 원천이 아니라 캐시일 수도 있다.

이걸 모르면 잘못된 곳을 수정한다. 캐시 파일을 직접 고쳐놓고 원본 데이터를 수정했다고 착각할 수 있다.

용어집은 이런 오해를 줄인다.

용어집은 면접 준비에도 도움이 된다

프로젝트 맥락으로 정리한 용어집은 면접 준비에도 좋다.

하지만 목적은 면접이 아니다.

예를 들어 cold start를 이렇게 설명할 수 있다.

Cold start는 Lambda 실행 환경이 새로 만들어질 때 발생하는 추가 지연이다. 이 프로젝트에서는 즉답이 중요한 대시보드 조회를 상주 API 서버로 분리했고, 사용자가 약간의 지연을 받아들일 수 있는 리포트 생성 작업은 Lambda로 처리했다.

이 답변은 일반 정의보다 낫다. 왜냐하면 개념과 실무 판단이 함께 들어 있기 때문이다.

면접에서 좋은 답은 외운 정의가 아니라, 경험 속에서 개념을 어떻게 적용했는지 보여주는 답이다.

프로젝트 용어집은 그 재료가 된다.

용어집에 넣기 좋은 항목

운영 콘솔 프로젝트라면 다음 범주로 나눌 수 있다.

네트워크와 브라우저

• Origin
• CORS
• preflight
• cookie
• credentials
• HTTPS

AWS 서비스

• S3
• CloudFront
• API Gateway
• Lambda
• Lambda Layer
• CloudWatch
• IAM

운영 패턴

• Source of Truth
• cache
• invalidation
• job queue
• worker
• polling
• idempotency

데이터와 성능

• connection pool
• RDS Proxy
• cold start
• throttling
• backpressure
• eventual consistency

배포와 보안

• stage
• environment variable
• secret
• signed cookie
• WAF
• least privilege

용어집은 한 번에 완성하지 않아도 된다. 문서를 쓰다가 반복적으로 등장하는 용어를 하나씩 추가하면 된다.

좋은 용어 설명의 길이

용어집은 너무 길면 읽히지 않는다.

각 용어는 다음 정도가 적당하다.

• 한 줄 정의
• 프로젝트 맥락 2~3줄
• 필요하면 관련 문서 링크

예시:

### Lambda Layer

- 정의: Lambda 함수 본체와 별도로 배포하는 공용 라이브러리 묶음.
- 이 프로젝트에서의 의미: 엑셀 생성 라이브러리와 DB 드라이버를 Layer로 분리해 함수 코드 배포 파일을 가볍게 유지한다.
- 관련 문서: Lambda 배포 최적화 가이드

이 정도면 충분하다.

용어집을 블로그로 바꾸는 방법

내부 용어집을 그대로 공개할 필요는 없다.

대신 다음처럼 글로 바꿀 수 있다.

• CORS는 에러가 아니라 브라우저 보안 모델이다
• Lambda Layer는 배포 속도를 줄이는 운영 도구다
• Source of Truth를 잘못 정하면 운영 데이터가 꼬인다
• CloudFront 캐시는 성능 기능이면서 운영 리스크다
• Job table은 비동기 작업의 대화 기록이다

용어 하나가 글 하나의 주제가 될 수 있다.

중요한 것은 실제 리소스명을 제거하고, 개념과 판단 기준만 남기는 것이다.

정리

프로젝트 용어집은 사전이 아니다.

검색하면 나오는 정의를 다시 쓰는 문서도 아니다.

좋은 용어집은 다음을 연결한다.

• 일반적인 기술 개념
• 이 프로젝트에서의 역할
• 운영 중 확인해야 할 지점
• 나중에 설명할 수 있는 판단 근거

용어를 안다는 것은 정의를 외우는 것이 아니다. 내가 만든 시스템 안에서 그 용어가 어떤 문제를 해결하고, 어떤 위험을 만드는지 설명할 수 있는 것이다.

그 설명을 미리 쌓아두는 문서가 프로젝트 용어집이다.

---

관련 자료: Ops Console Documentation Kit