코드 컨벤션 가이드라인

이 파일은 템플릿이다. <...> 부분을 이 프로젝트의 실제 컨벤션으로 채워야 동작한다. 채우는 방법: 문서가 아니라 기존 코드를 읽어서 실제로 쓰이는 패턴을 적는다. 이상적인 컨벤션이 아니라 지금 이 레포가 따르는 컨벤션이어야 리뷰 기준으로 쓸 수 있다.

언어 / 모듈 시스템

• <모듈 시스템과 쓰지 않는 쪽을 함께 명시. 예: CommonJS 사용, ES module 미사용>
• <언어 레벨, 문법 제약>
• <포매팅: 들여쓰기, 세미콜론, 린터 설정 파일 위치>

네이밍 규칙

파일 레이어 접미사

<레이어를 파일명으로 구분하는 프로젝트라면 표로. 아니면 이 절을 삭제한다.>

레이어별 코드 패턴

각 레이어의 대표 코드를 실제 레포에서 발췌해 붙인다. 설명보다 예시가 정확하다.

<Controller / Handler 패턴>

<Service 패턴 — 분기 규칙이 있다면 그것까지>

<Repository / Model 패턴 — 트랜잭션 버전이 따로 있으면 함께>

API URL 규칙

<버전 표기, 리소스 명명, 커스텀 액션 처리 방식. HTTP API가 없으면 이 절을 삭제한다.>

브랜치 규칙

• 공유 브랜치(<develop>/<main>)에서 직접 작업하지 않는다. 파일을 수정하기 전 (파이프라인이면 코딩 단계 진입 전, 스킵이면 첫 편집 전)에 현재 브랜치를 확인하고, 공유 브랜치면 작업 브랜치를 먼저 딴다 — 공유 브랜치에서 작업하면 리뷰 전 변경이 섞이고, PR 단위 롤백이 불가능해진다.
• 하네스(.claude/, CLAUDE.md) 변경도 동일하게 적용한다.
• 브랜치 네이밍: <예: feature/<주제>>

머지 게이트 규칙

배포 흐름이 있는 프로젝트라면 아래 원리를 그 흐름에 맞춰 구체화한다. 원리 자체는 공통이다.

• PR 생성과 PR 머지는 별개의 승인이다. 검증 단계(스테이징 배포·QA 등)를 통과한 뒤에 공유 브랜치로 머지한다 — 미검증 코드가 공유 브랜치에 확정되면 이후 작업이 그 위에 쌓여 시간이 지날수록 롤백 비용이 커진다.
• "머지해줘"가 어느 브랜치로의 머지인지 모호하면, 검증 게이트를 건너뛰지 않는 해석을 기본값으로 삼는다. 공유 브랜치로의 머지는 명시적 지시가 있을 때만 수행한다 — 잘못 안 한 머지는 한 마디 확인으로 복구되지만, 잘못 한 머지는 되돌리기 어렵다.
• 일반화하면: 비가역적 동작의 지시가 모호할 때는 보수적으로 해석한다.

배포 파이프라인

<환경별 배포 트리거와, "배포됐다"를 무엇으로 판단하는지를 적는다.>

특히 아래 두 가지를 명시하면 오판을 막는다.

• 푸시/태그가 곧 배포인 환경이 있는가? 그렇다면 그 브랜치 푸시는 커밋 공유가 아니라 배포 행위다.
• 푸시만으로 배포가 끝나지 않는 환경이 있는가? 수동 승인·수동 싱크 단계가 있으면, 이미지가 준비돼도 그 단계 전까지 구버전이 서빙된다. "배포 완료" 판단 기준을 여기에 적는다.

커밋 메시지 형식

<형식과 타입 목록>

로깅

• <로거와 금지 사항. 예: 표준 출력 직접 사용 금지>
• <민감 정보 로깅 금지 범위>
• <느린 요청·에러 로그 규약>

금지 사항

각 항목의 이유를 함께 적는다 — 이유가 성립하지 않는 예외 상황인지가 판단 기준이다. 이유 없는 금지는 엣지 케이스에서 잘못 적용되거나 그냥 무시된다.

아래는 언어·스택과 무관하게 흔한 항목들이다. 이 프로젝트에 해당하는 것만 남기고 프로젝트 고유의 금지 사항을 추가한다.

• 동적 코드 실행(eval 류) — 사용자 입력이 섞이면 임의 코드 실행 통로가 되고, 입력 검증으로 완전히 막기 어렵다
• <단일 이벤트 루프 기반이라면> 동기 I/O — 그 순간 모든 요청 처리가 멈춘다 (이벤트 루프 시작 전인 부팅 시점만 예외)
• 요청 간 공유되는 가변 전역 상태 — 동시 요청에서 다른 사용자의 데이터가 섞이는 오염 버그를 만든다
• 하드코딩된 URL·credential — 환경별 분리가 깨지고, 유출 시 코드 이력에서 회수가 불가능하다
• 비동기 에러 처리 누락 — 처리되지 않은 예외는 전역 에러 핸들러의 응답 규약과 모니터링 캡처를 우회해 조용히 사라진다