CLAUDE.md로 팀 배포 자동화 방향을 문서화한 이유
목차
작은 팀 프로젝트에서 CLAUDE.md를 만들고, 풀오토 배포 아이디어를 문서화하기 시작했다.
왜 지금 문서화인가
처음엔 자잘한 사이드 프로젝트라 생각했다. 코드만 돌아가면 된다고. 하지만 팀이 커지고, 온보딩 담당자가 생기고, 배포 파이프라인을 개선하려니까 문제가 터졌다. "이 부분은 왜 이렇게 했지?" "배포할 때 어떤 체크를 하는 거지?" 이런 질문들이 자꾸 반복됐다.
코드 자체는 이미 Git 히스토리와 주석에 남아 있지만, 아키텍처의 의도, 운영 결정, 자동화 전략 같은 건 어디에도 없었다. 메모장에 쓰인 문장들, 슬랙 채널에 흩어진 아이디어들, 누군가의 머릿속에만 있는 "다음 단계" 계획들. 이게 제일 큰 낭비다.
CLAUDE.md를 프로젝트에 추가하기
CLAUDE.md는 Claude Code 환경에서 코드베이스의 맥락을 제공하는 문서다. 단순한 README가 아니라, "이 프로젝트의 구조가 어떻게 되어 있고, 어떤 결정들이 어떤 이유로 내려졌는가"를 AI와 팀원이 함께 이해할 수 있게 한다.
내가 문서를 처음 만들 때 담은 핵심들:
- 프로젝트 개요: 뭘 하는 건지, 어떤 팀이 운영하는지
- 기술 스택과 선택 이유: 왜 이 도구를 썼는지의 트레이드오프
- 폴더 구조: 코드가 어디에 있고, 각 계층이 뭘 담당하는지
- 배포 프로세스: 현재 상태 + 개선하고 싶은 부분
마지막이 중요한데, 현재 상태만 쓰면 안 된다는 뜻이다. "지금은 수동 배포인데, 풀오토를 만들고 싶다" 이렇게 쓰면 나중에 온보딩할 사람도, 자동화 담당자도 "아, 이건 개선 대상이구나" 하고 빨리 파악한다.
풀오토 배포 아이디어 내장하기
이번 문서화가 단순 기록을 넘어선 건, 브레인스토밍 결과를 그대로 담았다는 점이다. "풀오토 배포를 어떻게 할까" 스케치를 문서에 넣었다.
## 향후 자동화 계획
- 깃 푸시 → 자동 테스트 → 테스트 통과 시 스테이징 배포
- 스테이징 검증 → 수동 승인 → 프로덕션 배포
- 배포 실패 시 슬랙 알림 + 롤백 자동화
이렇게 하면 뭐가 달라지나?
첫째, 누가 이 문서를 읽고 CI/CD 자동화를 손댈 때, 이미 방향성이 정해져 있다. 나갈 방향을 고민할 필요 없이 "아, 다음 단계는 여기구나" 하고 구현만 하면 된다.
둘째, 팀 회의에서 "배포 자동화 언제쯤 하지?" 이런 질문이 나올 때, 이미 우선순위와 계획이 문서에 있다. "이미 계획에 있는데, 현재 상황상 이걸 먼저 하는 게 낫지 않을까?" 이렇게 대화가 깊어진다.
셋째, 사이드 프로젝트라도 체계적으로 커진다. 어떤 신입이 온보딩될 때 "CLAUDE.md 봐" 한 줄이면 프로젝트의 과거, 현재, 미래를 이해한다.
문서화 vs 실행 속도
자잘한 팀이라 "문서 쓸 시간에 기능 만들지?" 할 수 있다. 내가 처음엔 그랬다. 근데 팀이 2명 이상이 되고, 운영이 2주 이상 지속되면, 문서가 없는 것의 비용이 기하급수적으로 늘어난다.
- 온보딩에 드는 시간 (구두 설명 반복)
- 결정 재논의 (왜 이렇게 했는지 기억 안 날 때)
- 자동화 지연 (구조를 다시 파악하고 시작)
이걸 다 감수하느니, 처음부터 CLAUDE.md 한 페이지를 만드는 게 낫다. 특히 배포나 운영 같은 영역은, 아이디어만 정리해도 실행이 50% 빨라진다.
마치며
결국 이번 커밋은 "문서 하나 만들었다"는 게 아니라, 프로젝트가 다음 단계로 성장했다는 신호다. 혼자 하던 작업에서 팀 프로젝트로, 임시방편에서 지속 가능한 구조로.
CLAUDE.md가 모든 걸 해결하진 못하지만, 최소한 같은 질문이 반복되지 않는다. 그리고 배포 자동화 같은 큰 작업도 "언제 할까"가 아니라 "어떻게 할까"로 넘어간다.
🛒 이 글과 어울리는 추천 상품
*위 링크는 쿠팡파트너스 활동의 일환이며, 일정액의 수수료를 제공받을 수 있습니다.
댓글 0
첫 댓글 달아줘.