SQL 정리와 YAML↔JSON 변환을 묶어 API 문서 리뷰 왕복 줄인 방법

릴리즈 전날 밤에 가장 자주 터지는 건 코드가 아니라 문서입니다. 쿼리는 통과하고 서버도 200을 주는데, 문서 예시가 예전 형식이라 클라이언트가 잘못된 필드를 보내는 상황이 반복되죠. 저도 한 번은 YAML 설정 파일에서 탭 한 글자 때문에 배포 파이프라인이 멈춘 뒤에야 “문서 품질을 코드 품질처럼 다뤄야 한다”는 말을 실감했습니다.

문서 품질 문제는 왜 항상 늦게 드러날까

SQL·YAML·JSON은 팀 안에서 가장 많이 읽히는 기술 문서 형식입니다. 문제는 작성자에게는 자명한 규칙이, 다음 사람에게는 암묵지로 남는다는 점입니다. 리뷰어는 의미보다 표기 흔들림을 먼저 잡느라 시간을 쓰고, 실제 결함은 릴리즈 직전에 드러납니다. 그래서 “형식 규칙”과 “의도 설명”을 분리해 운영해야 합니다.

문서가 신뢰를 잃는 순간은 대체로 비슷합니다. 예시는 있는데 실제 응답과 안 맞고, SQL은 같은 조인을 팀원마다 다른 스타일로 적고, JSON은 사소한 콤마 실수로 파서에서 막힙니다. 하나씩은 작은 문제처럼 보여도, 합쳐지면 커뮤니케이션 비용이 눈에 띄게 커집니다.

YAML: 탭 한 글자가 파서 오류로 이어지는 이유

YAML은 사람이 읽기 쉬운 대신 들여쓰기 규칙에 매우 민감합니다. YAML 1.2.2 명세를 보면 들여쓰기는 공백 기반으로 다뤄지고, 탭을 들여쓰기 용도로 섞지 않도록 안내합니다. 실무에서는 에디터 자동완성, 복붙, 서로 다른 포맷터 설정 때문에 탭이 섞이기 쉽습니다.

현장에서 효과가 컸던 방법은 단순했습니다. 저장 시 탭을 공백으로 변환하고, PR 단계에서 YAML lint를 강제하며, 실패 메시지를 “몇 번째 줄에서 들여쓰기 불일치”처럼 사람이 바로 고칠 수 있게 바꿨습니다. 규칙 자체보다 피드백 문구를 읽기 쉽게 만든 것이 오히려 재발 방지에 도움이 됐습니다.

• 에디터 기본값: tab size와 insert spaces 강제
• CI 검사: YAML lint 실패 시 병합 차단
• 리뷰 포인트: 값 의미보다 들여쓰기 구조 먼저 확인

JSON: 큰따옴표·콤마·스키마 일관성은 취향이 아니라 계약

JSON은 “대충 비슷하면 되겠지”가 통하지 않는 형식입니다. RFC 8259 기준으로 객체의 키는 문자열이며 큰따옴표를 사용합니다. 트레일링 콤마를 허용하지 않는 파서도 여전히 많기 때문에, 팀 내에서 허용 범위를 느슨하게 두면 환경별 오류가 생깁니다.

스키마 일관성도 같은 급의 이슈입니다. 예시 문서에는 user_id가 문자열로 적혀 있는데 실제 응답은 숫자로 내려오면, 소비자 입장에서는 어느 쪽이 계약인지 판단하기 어렵습니다. 이때 “문서 예시는 참고”라는 말은 책임 회피로 들리기 쉽습니다. 계약 문서라면 예시와 스키마를 같은 버전으로 관리해야 합니다.

실무 체크포인트는 세 가지면 충분합니다. 키/문자열 큰따옴표 규칙, 콤마 위치 규칙, 그리고 스키마 타입 일치 여부. 이 세 축만 자동 검증해도 릴리즈 직전 JSON 파싱 이슈가 크게 줄어듭니다.

SQL: 표기 규칙 통일이 리뷰 속도를 올리는 진짜 이유

SQL 리뷰가 느린 팀은 쿼리가 어려워서라기보다 표기가 제각각인 경우가 많습니다. 키워드 대문자 여부, 식별자 네이밍, 조인 조건 줄바꿈 방식이 매번 달라지면 리뷰어는 논리 결함보다 스타일 비교에 에너지를 씁니다. 결국 중요한 질문인 “이 조인이 맞는가, 누락된 조건은 없는가”가 뒤로 밀립니다.

팀 기준을 정할 때는 거창한 문서보다 합의 가능한 최소 규칙이 좋습니다. 예를 들어 키워드는 대문자, 테이블 별칭은 2~3글자, 조인 조건은 ON 절에서 컬럼을 한 줄씩 정렬. 이 정도만 고정해도 diff가 안정되어 리뷰가 빨라지고, 신규 인원 온보딩도 쉬워집니다.

또 하나, 규칙 문서에는 “금지”만 쓰지 말고 “왜”를 붙이세요. “암시적 조인 금지”라고만 적는 것과 “조인 누락을 코드리뷰에서 빨리 찾기 위해 명시적 조인 사용”이라고 적는 것은 현장 수용성이 다릅니다.

API 문서 드리프트: 예시 데이터와 실제 스키마를 정기 대조하기

API 문서가 오래될수록 예시 데이터가 현실과 멀어집니다. 새 필드는 추가됐는데 예시는 예전 그대로이고, nullable 여부가 바뀌었는데 설명이 남아 있지 않죠. 이런 드리프트는 장애처럼 즉시 폭발하지 않아서 더 위험합니다. 사용자는 조용히 우회 코드를 만들고, 기술 부채가 누적됩니다.

해결은 “정기 대조 루틴”을 팀 캘린더에 박아두는 것입니다. 배포 때만 보는 방식으로는 놓치는 항목이 반드시 생깁니다. 주기적으로 실제 응답 샘플을 수집하고, 문서 예시 및 스키마 정의와 비교해 불일치 항목을 이슈로 남기면 품질이 안정됩니다. 핵심은 담당자를 지정해 루틴을 끊기지 않게 만드는 일입니다.

자동 검증과 사람 설명을 분리하면 왜 안정될까

문서 품질을 높이겠다고 모든 걸 한 파일에 몰아넣으면 운영이 무거워집니다. lint/format/schema check 같은 자동 검증은 기계가 담당하고, 배경 맥락·예외 상황·도메인 용어 설명은 사람이 읽는 문서로 분리하는 편이 훨씬 효율적입니다. 역할이 분리되면 리뷰 기준도 선명해집니다.

자동 검증 레이어에서는 “맞다/틀리다”를 빠르게 판정하고, 서술 레이어에서는 “왜 이렇게 설계했는지”를 남깁니다. 이 구조를 잡아두면 누가 작성하든 결과물의 바닥 품질이 일정하게 유지됩니다. 특히 담당자가 바뀌는 분기마다 차이가 크게 납니다.

• 자동 레이어: YAML lint, JSON schema check, SQL formatter/linter
• 설명 레이어: 필드 의미, 예외 케이스, 변경 이력과 영향 범위
• 운영 레이어: 릴리즈 전 체크리스트 + 정기 대조 일정

팀에 바로 적용하는 2주 실행안

큰 개편보다 “작게 시작해 끊기지 않게”가 현실적입니다. 아래 순서대로 2주만 운영해도 체감이 옵니다.

1. 1~2일차: YAML/JSON/SQL 최소 스타일 가이드 한 장 작성
2. 3~5일차: 저장소에 lint·format·schema check 연결, 실패 메시지 한국어 보강
3. 2주차 초반: API 예시와 실제 응답 대조 항목 10개 선정
4. 2주차 후반: 불일치 수정 + 문서 변경 이력 템플릿 적용

중요한 건 도구 선택보다 합의된 운영 리듬입니다. 사람마다 선호 에디터와 포맷터가 달라도, 저장소 기준이 같으면 결과물은 같아집니다. 규칙은 팀을 묶고, 설명은 팀을 설득합니다. 둘 중 하나라도 빠지면 오래 못 갑니다.

마무리: 문서를 코드처럼 다루되, 사람의 읽기 경험을 놓치지 않기

YAML의 공백 들여쓰기, JSON의 큰따옴표와 콤마 규칙, SQL 표기 통일은 사소한 취향 논쟁이 아닙니다. 리뷰 시간을 줄이고 배포 리스크를 낮추는 기본 장치입니다. 여기에 API 문서 드리프트 점검 루틴을 더하면 “문서가 현실을 반영한다”는 신뢰가 생깁니다.

결국 품질은 한 번의 정리로 완성되지 않습니다. 자동 검증으로 바닥을 단단히 만들고, 사람이 읽는 설명으로 맥락을 채우는 운영을 반복해야 합니다. 오늘 당장 할 일은 거창하지 않습니다. 탭을 공백으로 바꾸고, JSON 스키마를 고정하고, SQL 표기 기준을 한 페이지로 정리해 팀 저장소 루트에 두는 것부터 시작해 보세요.

사실 앵커 확인 링크: YAML 1.2.2, RFC 8259