벤더 API 규격서 한곳에서 관리하기

이커머스 플랫폼에서는 여러 외부 벤더와 API 연동을 하게 된다. 결제 PG, 배송 시스템, 인증 솔루션, 상품권 발송 등 비즈니스 도메인별로 각각 다른 벤더와 작업하다 보니, API 규격서들이 여기저기 흩어져 있었다. 이번 작업은 그 모든 벤더 연동규격서를 .claude/pdf 디렉토리에 한곳으로 모으고, 신규 벤더 2종을 추가하는 문서화 작업이었다.

왜 문서 중앙화가 필요했나

팀 규모가 커지면서 점점 더 많은 개발자가 벤더 연동 작업을 한다. 그런데 규격서가 이메일 첨부, 협업 도구의 여러 폴더, 개별 개발자 PC, 공유 드라이브 등 사방팔방에 흩어져 있으면 어떻게 될까?

• 새 팀원 온보딩: "이 벤더의 API 문서가 어디 있어?" 물어봐야 함
• 코드리뷰 시 참고: 리뷰어가 해당 벤더 규격서를 찾으려고 한참 헤맴
• 버전 관리: 어느 것이 최신 규격서인지 불명확 (v1.61? v2.5.0? 헷갈림)
• 변경 이력 추적: "이 부분 규격이 언제 바뀌었지?" git 히스토리에서 파악 불가능

.claude/pdf 디렉토리로 통합하면, 팀원들이 (특히 신입이나 신규 프로젝트 진입자들이) git 저장소에서 바로 최신 규격서를 찾을 수 있다. 더 나아가 프롬프트 기반 개발 환경에서 AI 어시스턴트가 규격서를 참고해 코드 생성을 도와주거나 연동 로직을 제안하는 것도 가능해진다.

어떻게 구조를 짰나

벤더별로 디렉토리를 나누고, 그 안에 필요한 모든 연동 자료를 모았다:

각 벤더마다 다른 포맷을 사용하고 있었다:
- Excel: 상품권 발송처럼 데이터 테이블이 중심인 경우
- PDF: 대부분의 결제/배송 시스템 (공식 규격서 형식)
- Markdown: 간단한 스펙 정리 (git 저장소와 동기화 용이)
- JSON: API Postman Collection (개발팀에서 즉시 import 가능)

다중 포맷 관리의 교훈

이 작업을 진행하면서 느낀 몇 가지:

1. 포맷 다양성은 피할 수 없다
벤더들이 각각 제공하는 형태가 다르니, 원본 그대로 보관하되 팀이 쉽게 접근할 수 있는 곳에 두는 게 핵심이다. Excel과 PDF를 모두 받았다면 둘 다 저장해두고, 필요한 사람이 각자의 선호 포맷을 사용하도록 하는 게 낫다.

2. 버전 정보를 파일명에 명시
_v1.61(20251027)_, _ver1.7), _v2.5.0_ 같은 버전과 갱신 날짜가 파일명에 포함된 것을 보니, 누군가는 이미 이 필요성을 강하게 느끼고 있었다는 뜻이다. 앞으로 규격서 업데이트가 생기면 이 패턴을 일관되게 유지해야 팀원들이 "아, 최신판이 몇 개월 전에 나왔네"라고 금방 파악할 수 있다.

3. 신규 벤더 추가의 신호
이 커밋 시점에 벤더 2종이 새로 추가됐다는 것은 비즈니스가 확장되고 있다는 뜻이다. 매번 벤더가 추가될 때마다 "규격서는 이 디렉토리에 넣고, 버전은 파일명에, 가능하면 여러 포맷을 보관하자"는 선례가 생기면, 앞으로의 추가 작업들이 훨씬 수월해진다.

팀 리더 입장에서

이런 문서화 작업이 단순해 보일 수 있지만, 결국 개발 생산성과 직결된다:

• 신입 개발자가 결제 연동 모듈 건드릴 때 규격서를 찾는 데 5분이 아니라 10초
• 코드리뷰어가 "이 파라미터가 규격서의 어느 부분인가?"라고 물어볼 때 즉시 경로 제시 가능
• 버전 업그레이드 검토할 때 "현재 v1.61 쓰고 있고, 최신은 v2.5.0" 한눈에 파악
• 온보딩 문서를 쓸 때 "벤더 규격서는 .claude/pdf에 모두 있습니다"로 끝낼 수 있음

결국 좋은 문서 관리는 팀의 컨텍스트 스위칭 비용을 줄이는 가장 저렴한 투자다. 다음 벤더 추가나 규격서 갱신이 생길 때도, 이번에 만든 구조를 따라가면 된다.

🛒 이 글과 어울리는 추천 상품

• 모니터 쿠팡에서 보기 →
• 외장SSD 쿠팡에서 보기 →
• 기계식키보드 쿠팡에서 보기 →

*위 링크는 쿠팡파트너스 활동의 일환이며, 일정액의 수수료를 제공받을 수 있습니다.