기여 — 커밋 & 브랜치

이 저장소의 커밋/브랜치 규칙입니다. 원본은 루트 AGENTS.md 의 "커밋 & 브랜치 규칙" 이며, 이 페이지는 그 내용을 풀어 설명합니다.

커밋 메시지 — Conventional Commits

한 줄, 명령형(동사 먼저).

type(scope?): subject

• type: feat · fix · perf · refactor · test · docs · build · chore
• scope(선택): 변경 범위 — feat(api): …, fix(web): …
• subject: 명령형 동사로 시작(add/fix/remove…), 마침표 없음, 40–51자 목표
• 한 줄만 — 본문은 꼭 필요할 때만
• AI 작성자 푸터 금지 — Co-Authored-By 등 추가하지 않음
• 원자적 — 한 커밋 = 하나의 논리적 변경. 버그 수정과 그 회귀 테스트는 같은 커밋
• 시크릿 금지 — 키/비밀번호를 커밋에 넣지 않음(.dev.vars + wrangler secret)

커밋 자동 검증 (commit-msg 훅)

위 규칙은 .githooks/commit-msg 훅이 자동으로 강제합니다 — 외부 의존(commitlint 등) 없는 순수 POSIX sh 스크립트입니다. 커밋할 때마다 subject 를 검사해 다음이면 거부합니다: Conventional Commits 형식 불일치, subject 가 마침표로 끝남, 길이 72자 초과, 메시지에 Co-Authored-By / "Generated with"(AI 작성자 푸터) 포함. 길이가 권장 40–51자 밖이면 경고만 하고 통과시키며, Merge/Revert 커밋은 검증을 건너뜁니다.

훅은 루트 package.json 의 prepare 스크립트(git config core.hooksPath .githooks)로 배선됩니다 — pnpm install 시 자동 실행되므로 모든 기여자에게 동일하게 활성화됩니다. 수동으로 켜려면 저장소 루트에서 다음을 한 번 실행하세요:

git config core.hooksPath .githooks

Claude Code 에서는 /commit 스킬(.claude/skills/commit/)이 같은 규칙으로 커밋 워크플로 (관련 파일 스테이징 → 변경 범위 lint/test → subject 작성 → 원자적 커밋)를 안내합니다. 부작용이 있는 워크플로이므로 모델이 임의 호출하지 않도록 명시 호출 전용으로 설정돼 있습니다.

브랜치 — trunk-based GitHub flow

main (트렁크, 항상 배포 가능)
 └─ feat/optimistic-plan   ← 짧은 수명 브랜치
 └─ fix/pomodoro-timer        작게 자주 커밋 → PR → squash 머지 → 삭제

• main 이 트렁크이며 항상 배포 가능. main push → CI(.github/workflows/deploy.yml)가 prod 자동 배포(Worker prod + Pages neul-*-prod + Drizzle migrate + 인프라).
• 작업은 main 에서 딴 짧은 수명 브랜치(feat/…, fix/…, chore/…)에서. 작게 자주 커밋하고 PR 을 일찍 연다.
• PR → 리뷰 → main 으로 squash 머지 후 브랜치 삭제. 장수 브랜치/대형 머지 지양(1–2일 이내 통합).

prod 전 dev 검증

main(prod) 머지 전에 dev 환경에서 먼저 검증합니다. 4개 surface 모두 neul-<surface>-<dev|prod> 규칙을 따릅니다:

원격 e2e 는 같은 Playwright 스펙을 배포본에 재사용합니다:

E2E_BASE_URL=https://neul-web-dev.pages.dev \
E2E_API_URL=https://neul-api-dev.neul-study.workers.dev \
pnpm e2e:web

수동 배포 명령과 배포 맵은 배포 및 DEPLOY.md 를 참고하세요.