웹POS·B2B 연동 규격서를 레포로 통합 관리

웹POS 및 B2B 연동 규격서 두 종을 프로젝트 레포에 커밋했다.

단순히 PDF 파일 두 개를 docs/ 폴더에 넣은 작업처럼 보이지만, 팀장 입장에서 이 커밋은 꽤 무게감이 있다. 외부 연동 규격서는 팀 내 누구라도 필요할 때 즉시 꺼내볼 수 있어야 하고, 버전 관리도 되어야 한다. 지금까지 이 파일들이 어딘가의 메신저 채팅방이나 개인 드라이브에 묻혀 있었다면, 이번 커밋은 그 산재 상태를 정리하는 첫 삽이다.

왜 규격서를 레포에 넣는가

외부 시스템과 연동할 때 가장 많이 발생하는 비효율 중 하나가 "규격서 어디 있어요?" 질문이다. 신규 팀원이 온보딩할 때, 혹은 QA 중 이슈가 터졌을 때 규격서를 찾아 헤매는 시간은 생각보다 길다. 특히 웹POS나 B2B 연동처럼 암호화 헤더, API 버전, 필드 포맷이 상세하게 명시된 문서는 개발 중에 수시로 참조해야 하는데, 이게 팀원마다 각자 다른 버전을 갖고 있으면 사고의 씨앗이 된다.

이번에 커밋된 파일들은 아래와 같다.

두 파일 모두 암호화 관련 내용이 포함된 버전이라는 점이 눈에 띈다. 연동 규격서에서 암호화 항목은 실수가 생기면 장애로 직결되는 부분이라, 팀 전체가 동일한 버전을 보고 있다는 게 특히 중요하다. 구버전 규격서를 기준으로 개발한 코드가 실제 연동 시 헤더 포맷 불일치로 튕겨나오는 상황은 한 번쯤은 겪어봤을 거다.

문서도 코드처럼 버전 관리

파일명에 버전 정보(v1.61, v2.5.0)와 날짜(20251027)가 이미 포함되어 있어서 히스토리 추적이 어느 정도 된다. 이게 사소해 보이지만 실은 팀 운영에서 꽤 중요한 습관이다.

404_pjt/docs/
├── 웹인증(웹POS)연동규격서_v1.61(20251027)_암호화포함.pdf
└── 즐거운B2B_연동규격서(암호화헤더추가) v2.5.0_api_ver.pdf

나중에 규격서가 v1.62나 v2.6.0으로 업데이트되면 이전 파일과 함께 docs/ 하위에 남겨두거나, 또는 구버전을 명확히 아카이빙하는 방향으로 정책을 잡아두는 게 좋다. 그냥 파일을 덮어쓰면 "예전 버전 어떻게 됐지?" 질문이 다시 나온다.

팀원 입장에서 규격서 관리 측면에서 바라는 것들을 정리해보면:

• 최신 버전 규격서가 어디 있는지 한 곳에서 찾을 수 있어야 함
• 파일명에 버전/날짜가 명시되어 있어야 혼동 없음
• 규격서가 업데이트됐을 때 팀에 공유가 되어야 함 (커밋 알림, PR, 슬랙 등)
• 암호화 키나 민감 정보가 포함된 문서는 접근 권한 관리 필요

마지막 항목이 이번 커밋에서 한 번 더 확인이 필요한 부분이다. 두 파일 모두 "암호화 포함" 또는 "암호화 헤더 추가"가 파일명에 명시되어 있는데, 이 규격서 자체에 실제 키값이나 민감 정보가 담겨 있다면 레포 접근 권한이 적절히 설정되어 있는지 체크해야 한다. 404_pjt 레포가 내부 전용 private 레포라면 크게 문제없지만, 혹시라도 공개 범위가 넓다면 한 번 짚고 넘어가는 게 맞다.

회고

문서 커밋은 "별거 아닌 작업"처럼 느껴지는데, 팀장 입장에서 보면 이게 팀의 정보 허브를 정돈하는 작업이다. 연동 개발 중 "규격서 어디 있어요?"라는 질문이 한 번이라도 줄어든다면 이 커밋은 충분히 가치 있다. 앞으로 연동 규격서가 추가되거나 버전업될 때도 동일한 docs/ 경로에 일관되게 쌓아가는 문화를 유지하는 게 목표다.

끝.