claude-workspace/CLAUDE.md

CLAUDE.md – 프로젝트 가이드

이 파일은 AI 코딩 어시스턴트(Claude, Cursor 등)가 이 저장소에서 작업할 때 따라야 할 규칙과 컨텍스트를 정의합니다. 반드시 숙지 후 작업하세요.

---

프로젝트 개요

항목	내용
프로젝트명	(프로젝트명을 여기에 입력하세요)
목적	(프로젝트의 목적을 한 줄로 설명하세요)
기술 스택	Python 3.11 · FastAPI · PostgreSQL 15 · React 18 · TypeScript
아키텍처	모놀리스 (추후 마이크로서비스 전환 예정)
주요 언어	한국어 (코드 내 주석 및 커밋 메시지는 영어 사용)

---

디렉터리 구조

.
├── backend/
│   ├── api/          # FastAPI 라우터 (엔드포인트 정의)
│   ├── models/       # SQLAlchemy DB 모델
│   ├── schemas/      # Pydantic 요청/응답 스키마
│   ├── services/     # 비즈니스 로직 레이어
│   └── core/         # 설정, 의존성 주입, 미들웨어
├── frontend/
│   └── src/
│       ├── components/  # 재사용 가능한 UI 컴포넌트
│       ├── pages/       # 라우트 단위 페이지
│       ├── hooks/       # 커스텀 React Hooks
│       └── api/         # API 클라이언트 (axios/fetch 래퍼)
├── tests/
│   ├── unit/
│   ├── integration/
│   └── e2e/
├── docs/             # 설계 문서
├── .env.example      # 환경 변수 템플릿 (실제 값 절대 포함 금지)
└── Makefile

---

코딩 컨벤션

Python (Backend)

• PEP 8 준수, type hints 필수 (매개변수 및 반환값 모두)
• Docstring: Google 스타일
• 함수는 단일 책임 원칙(SRP) 준수, 50줄 초과 지양
• 예외 처리 시 bare except: 금지, 반드시 구체적인 예외 타입 명시

JavaScript / TypeScript (Frontend)

• ESLint + Prettier 설정 준수 (npm run lint 통과 필수)
• 컴포넌트는 함수형만 사용, 클래스 컴포넌트 금지
• any 타입 사용 금지, 불가피한 경우 unknown 후 타입 가드 사용
• 상태 관리: 로컬 상태는 useState, 전역 상태는 별도 문서 참조

Git 브랜치 전략 (Gitflow)

main          ← 프로덕션 배포 전용 (직접 푸시 절대 금지)
develop       ← 통합 개발 브랜치
feature/*     ← 기능 개발 (예: feature/user-auth)
hotfix/*      ← 프로덕션 긴급 수정
release/*     ← 릴리즈 준비

커밋 메시지 (Conventional Commits)

feat: 새로운 기능 추가
fix: 버그 수정
docs: 문서 수정
test: 테스트 코드 추가/수정
refactor: 리팩터링 (기능 변경 없음)
chore: 빌드, 설정 파일 수정

---

환경 변수 및 시크릿 관리

• 모든 시크릿은 .env 파일에서 관리 (.gitignore에 반드시 포함)
• .env.example에 키 이름만 기재, 실제 값은 절대 커밋 금지
• AI가 코드를 작성할 때 API Key, 비밀번호, 토큰을 하드코딩하지 말 것
• 환경 변수 접근: os.getenv("KEY_NAME") 또는 pydantic BaseSettings 사용

---

외부 시스템 연동

시스템	URL	용도
이슈 트래커	https://redmine.cloud-handson.com	작업 이슈 관리
CI/CD	https://jenkins.cloud-handson.com	자동 빌드/배포
Git 서버	https://gittea.cloud-handson.com	소스 코드 관리
지식베이스	Obsidian Vault (/Users/joungmin/Documents/Obsidian Vault)	설계 문서 동기화, para document 관리법 사용

MCP 툴

외부 시스템은 MCP(Model Context Protocol) 툴을 통해 직접 제어할 수 있습니다. API 호출 대신 MCP 툴을 우선 사용하세요.

Jenkins (mcp__jenkins__*)

툴	설명
get_jobs	잡 목록 조회
get_job_config	잡 config.xml 조회
create_job	새 잡 생성 (config.xml 필요)
edit_job	잡 설정 수정 (config.xml 필요)
delete_job	잡 삭제
trigger_build	빌드 트리거
get_build_status	빌드 상태 조회
get_build_log	빌드 로그 조회

Redmine (mcp__redmine__*)

툴	설명
getIssues / getIssue	이슈 목록/상세 조회
createIssue	이슈 생성
updateIssue	이슈 수정
deleteIssue	이슈 삭제
getProjects / getProject	프로젝트 조회
createProject / updateProject	프로젝트 생성/수정
getTimeEntries / createTimeEntry	시간 기록 조회/생성
getWikiPage / updateWikiPage	위키 페이지 조회/수정
search	전체 검색
getCurrentUser	현재 로그인 사용자 조회

---

개발 방법론

• 스프린트: 2주 주기 스크럼
• 워크플로: Redmine 이슈 생성 → 브랜치 생성 → PR 작성 → 코드 리뷰 → Jenkins CI 통과 → develop 머지
• 테스트 커버리지 목표: unit 80%+, integration 60%+
• PR 머지 전 최소 1명의 코드 리뷰 승인 필요

---

금기 사항 (AI 포함 모든 기여자 준수)

• main 브랜치 직접 푸시 절대 금지
• API Key, 비밀번호 등 시크릿 하드코딩 절대 금지
• TODO 주석은 반드시 Redmine 이슈 번호와 함께 작성 (# TODO(#123): 설명)
• 테스트 없이 핵심 비즈니스 로직 변경 금지
• print() 디버그 코드를 프로덕션 코드에 남기지 말 것 (logger 사용)

---

주요 명령어

# 개발 서버 시작 (backend + frontend 동시 실행)
make dev

# 테스트 실행
make test

# 특정 테스트만 실행
pytest tests/unit/ -v

# 린트 검사
make lint

# 린트 자동 수정
make lint-fix

# DB 마이그레이션 생성
alembic revision --autogenerate -m "description"

# DB 마이그레이션 적용
alembic upgrade head

---

참조 문서

문서	경로	내용
디자인 패턴 가이드	SOFTWARE_GUIDE.md	생성·구조·행위 패턴 정의, 빠른 선택 가이드 포함

새 모듈·클래스 설계 시 SOFTWARE_GUIDE.md의 빠른 선택 가이드를 먼저 확인하세요.

---

AI 작업 지침

AI가 이 저장소에서 코드를 생성하거나 수정할 때 반드시 따라야 할 규칙입니다.

1. 기존 패턴 우선: 새 코드 작성 전 인접 파일의 구조와 패턴을 파악하고 일관성 유지
2. 최소 변경 원칙: 요청된 변경 범위를 벗어나는 수정은 하지 말 것
3. 테스트 동반 작성: 새 함수/로직 작성 시 대응하는 단위 테스트 함께 제안
4. 불확실 시 질문: 요구사항이 모호하면 임의로 결정하지 말고 반드시 확인 요청
5. 보안 우선: 인증/인가 로직은 임의로 우회하거나 단순화하지 말 것

---

팀 연락처

역할	담당자
PM / Tech Lead	JM