팀 협업 규칙, 개발 환경 설정, Claude Code 사용법을 한 곳에 정리합니다.
Java 21이 설치되어 있어야 합니다.
git clone <repo-url>
cd doori-backend
./gradlew clean build
./gradlew bootRun- 로컬에서 최소 1회
./gradlew clean build성공 후 작업 시작 권장
이 프로젝트는 팀 협업 규칙을 자동화하는 Claude Code 커스텀 커맨드를 제공합니다.
Node.js 18 이상 필요
npm install -g @anthropic-ai/claude-codeclaude최초 실행 시 Claude.ai 계정 로그인 또는 API 키 입력 안내가 표시됩니다.
프로젝트 루트에서 아래 커맨드를 사용할 수 있습니다.
| 커맨드 | 실행 위치 | 하는 일 |
|---|---|---|
/start 타입 이슈번호 |
프로젝트 루트 | 이슈 조회 → 규칙에 맞는 브랜치 자동 생성 → 구현 계획 분석 |
/commit |
프로젝트 루트 | 변경사항 확인 → 자동 검증 → 규칙에 맞는 커밋 메시지 제안 후 커밋 |
/pr |
프로젝트 루트 | 브랜치 푸시 → Draft PR 자동 생성 |
/review |
프로젝트 루트 | PR 올리기 전 사전 코드 리뷰 (심각도 분류 포함) |
주의사항
- 반드시 프로젝트 루트 디렉토리에서
claude명령으로 실행해야 커스텀 커맨드가 로드됩니다. /commit은./gradlew test실행 여부를 판단합니다. 로컬 빌드가 가능한 상태여야 합니다.- 각 커맨드의 상세 동작 규칙은
.claude/rules/파일을 참조하세요. README와는 별개로 관리됩니다.
이슈 작업을 시작할 때 이슈 조회, 브랜치 생성, 계획 수립을 한 번에 처리합니다.
사용법:
/start feat 12
/start fix 34동작:
- GitHub Issue #12 조회
- 이슈 제목을 기반으로 브랜치명 생성 (예:
feat/12-login-api) - 브랜치 자동 생성 및 전환
- 구현 계획 분석 결과 출력
- 변경할 파일 목록
- 새로 만들 파일 목록
- 구현 순서
- response-exception.md 체크리스트
- 예측되는 주의사항
지원하는 타입: feat, fix, chore, docs, refactor
flowchart LR
A["📋 이슈 생성"] --> B["🌿 브랜치 생성"]
B --> C["💻 개발 & 커밋"]
C --> D["📝 PR 생성"]
D --> E["🔍 CI & 리뷰"]
E --> F["✅ 머지"]
F --> G["🎉 완료"]
- GitHub Issues에서
Task템플릿으로 등록 - 이슈 생성 시 Notion DB에 일감 자동 생성 (상태:
시작전)
- 이슈 번호가 포함된 브랜치로 생성
git checkout -b feat/12-login-api포맷은 네이밍 규칙 섹션 참조
Claude Code 팁:
/start feat 12커맨드로 GitHub 이슈 조회 → 브랜치 자동 생성 → 구현 계획 분석을 한 번에 처리
- 작업 시작 전 Notion 일감 속성 업데이트: 담당자, 마감일, 상태
- 커밋 메시지 포맷은 네이밍 규칙 섹션 참조
Claude Code 팁:
/commit커맨드로 변경사항 자동 검증 및 규칙에 맞는 커밋 메시지 생성
- 처음에는 Draft PR 권장
- PR 템플릿의 연관 이슈 항목에
Fixes #이슈번호입력 - Draft 상태에서 CI와 Auto Review 피드백 우선 반영
현재 CI 기준 기본 확인 명령:
| 항목 | 명령어 |
|---|---|
| Build + Test | ./gradlew clean build --no-daemon |
| Test only | ./gradlew test |
Claude Code 팁:
/pr커맨드로 브랜치 푸시 → Draft PR 자동 생성을 한 번에 처리
- 최소 1명 Approve 후 머지
- 리뷰 반영 커밋 후 CI 재통과 확인
Claude Code 팁:
/review커맨드로 PR 올리기 전 사전 셀프 리뷰 (심각도 분류 포함)
main머지 시 Notion 상태완료로 자동 동기화- 연결 이슈 자동 닫힘
형식:
[이모티콘 타입] 작업 내용
예시:
[✨ Feat] 로그인 API 구현
[🔨 Fix] 홈 피드 조회 시 500 에러 수정
[🧹 Chore] 공통 예외 응답 포맷 정리
[📝 Docs] 배포 가이드 문서화
[♻️ Refactor] 인증 필터 구조 분리
타입 가이드:
| 타입 | 이모티콘 | 용도 |
|---|---|---|
| Feat | ✨ | 새 기능 |
| Fix | 🔨 | 버그 수정 |
| Chore | 🧹 | 설정/빌드/의존성/운영 작업 |
| Docs | 📝 | 문서 작업 |
| Refactor | ♻️ | 동작 변경 없는 구조 개선 |
형식:
타입/이슈번호-작업-내용
예시:
feat/12-login-api
fix/34-feed-500-error
chore/5-exception-format
규칙:
- 소문자와 하이픈(
-)만 사용 - 이슈 번호는 필수 (Notion 추적 기준)
- 브랜치에는 이모티콘을 넣지 않음 (터미널/자동화 호환성)
형식:
[이모티콘 타입] 작업 내용 (#이슈번호)
예시:
[✨ Feat] 로그인 API 구현 (#12)
[🔨 Fix] 홈 피드 조회 시 500 에러 수정 (#34)
규칙:
- 원칙적으로 이슈 제목과 동일한 문맥 유지
- PR 본문에
Closes #이슈번호또는Fixes #이슈번호반드시 포함
형식:
타입: 이모티콘 작업 내용
예시:
feat: ✨ 로그인 API 구현
fix: 🔨 피드 조회 500 에러 수정
chore: 🧹 예외 응답 코드 정리
docs: 📝 README 업데이트
refactor: ♻️ 인증 로직 분리
타입은 이슈 제목과 동일하게 매핑합니다.
이슈: [✨ Feat] 로그인 API 구현
브랜치: feat/12-login-api
PR: [✨ Feat] 로그인 API 구현 (#12)
커밋: feat: ✨ 로그인 API 구현
GitHub 이벤트와 Notion 상태를 자동으로 동기화합니다.
| 이벤트 | Notion 상태 |
|---|---|
| 이슈 생성 | 시작전 |
| PR 오픈 (Draft 포함) | 리뷰중 |
| PR 머지 | 완료 |
이슈를 not planned로 종료 |
취소됨 |
취소됨 상태 이슈 재오픈 |
시작전 |
메모:
진행중전환은 수동 업데이트 (팀이 실제 작업 시작 시 직접 변경)- 작업 시작 전에 담당자/마감일/상태를 정확히 맞추면 추적 품질이 크게 올라갑니다
| 필드명 | 타입 | 비고 |
|---|---|---|
작업 이름 |
Title | 이슈/PR 제목 동기화 |
Github 이슈 번호 |
Number | GitHub issue number 키 |
Github 이슈 URL |
URL | GitHub issue 링크 |
Github PR |
URL | GitHub PR 링크 |
상태 |
Status/Select | 시작전/진행중/리뷰중/완료/취소됨 |
사람 |
People | NOTION_PEOPLE_MAP 기반 동기화 |
마감일 |
Date | 이슈 본문 마감일 (YYYY-MM-DD) 파싱 |
세 가지 핵심 원칙으로 팀 협업을 관리합니다.
-
제목, 브랜치, PR 네이밍은 항상 규칙 우선
- 자동화가 읽을 수 있는 정보 형식 유지
-
자동화가 읽을 수 있는 정보를 누락하지 않기
- 이슈 번호는 필수
- PR 본문에
Fixes/Closes #이슈번호필수 - Notion 동기화 실패 방지
-
머지 전 "리뷰 반영 + CI 통과"를 완료 기준
- 리뷰 지적사항 반영 후 재커밋
- CI 재통과 확인 후 머지