팀 가이드 문서에서 평문 비번 제거

pdf2api 프로젝트의 CLAUDE.md 에 평문으로 작성되어 있던 DB 비번을 제거하고, secrets.env 참조로 변경했다. 한줄짜리 수정이지만, 온보딩부터 배포까지 전 라이프사이클에 걸친 보안 관행의 차이가 담긴 작업이다.

문서화의 편의성이 만드는 함정

팀 온보딩 문서나 로컬 설정 가이드(CLAUDE.md, README, .env.example 등)는 신입이 빠르게 개발 환경을 구성하려면 최대한 구체적이어야 한다. 그래서 자연스럽게 "DB 호스트는 localhost:5432, 사용자는 admin, 비번은..." 이렇게 실제 값을 쓰게 된다. 특히 개발 환경이 로컬 Postgres라면 더더욱.

문제는 이런 문서가 git 히스토리에 영구 기록된다는 것. 커밋을 밀면 누구든(팀원, 퍼블릭 레포라면 전 인터넷) 그 비번을 볼 수 있다. 한번 노출되면 그 커밋을 지워도 git 리바이스 기록까지 추적하는 스캔 도구들이 있어서 완전히 제거하기도 번거롭다. 그래서 처음부터 "문서엔 절대 비번/키를 넣지 않는" 규칙이 중요한 거다.

할 수 있었던 더 나은 방식들

실제로 이런 변경은 단순히 "비번 한 줄 삭제"가 아니라, 개인정보보호 정책, 팀 온보딩 프로세스, 코드 리뷰 체크리스트까지 아우르는 문제다.

이 프로젝트는 secrets.env 패턴을 선택했다. 파일명이 "secrets"라는 신호를 주므로, 팀원들이 "여기엔 비번이 들어간다"는 걸 알아채기 쉽다.

온보딩과 리뷰 체크리스트에 반영해야 할 것

근본 원인은 이 규칙이 신규 프로젝트 세팅 체크리스트나 커밋 전 코드 리뷰 항목에 명시되지 않았다는 뜻이다. 앞으로는:

• 신규 프로젝트 초기화 체크리스트: "민감 정보(비번, API 키, 토큰) 문서화 방식 결정" 항목 추가
• CLAUDE.md 작성 가이드: "secrets.env 나 env var 는 이름만, 실제 값은 작성하지 않기"
• PRE-COMMIT 훅 (선택): grep -r "password\|secret\|token" docs/ CLAUDE.md 같은 패턴 감지
• 팀 온보딩 시: "문서에 비번 보이면 리뷰 요청 전에 제거" 안내

나의 회고

이 커밋은 작지만, "우리가 뭘 놓쳤나"를 드러낸다. 특히 내가 팀 리딩을 하면서 느낀 점은:

• 편의성과 보안의 충돌: 신입이 빠르게 온보딩되려면 구체적인 예시가 필요하지만, 그 예시가 곧 보안 약점이 된다.
• 체크리스트의 중요성: "이정도면 자명한데?" 싶어도, 체크리스트가 없으면 개개인의 판단에 맡겨져 실수가 누적된다.
• 후속 조치: 이 커밋 후에는 팀 전체에 "문서 민감 정보 제거" 방침을 공지하고, 다른 프로젝트도 스캔해야 한다. 단순 수정이 아니라 프로세스 개선의 신호.

다음은 이런 류의 이슈를 미리 방지하는 자동화 도구 도입을 검토해볼 때.

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

• 모니터 쿠팡에서 보기 →
• 기계식키보드 쿠팡에서 보기 →
• 사무의자 쿠팡에서 보기 →

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