3eb685c6f8
- Add MCP servers for Redmine, Jenkins, Gitea, Obsidian - Add setup_mcp.sh to generate .mcp.json from .env (no secrets in VCS) - Add .env.example with required variable names for team onboarding - Add .gitignore to exclude secrets (.env, .mcp.json, settings.local.json) - Fix obsidian_mcp_server.py stdio_server async context manager usage Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
208 lines
6.9 KiB
Markdown
208 lines
6.9 KiB
Markdown
# 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 사용)
|
||
|
||
---
|
||
|
||
## 주요 명령어
|
||
|
||
```bash
|
||
# 개발 서버 시작 (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) | 생성·구조·행위 패턴 정의, 빠른 선택 가이드 포함 |
|
||
|
||
> 새 모듈·클래스 설계 시 `SOFTWARE_GUIDE.md`의 **빠른 선택 가이드**를 먼저 확인하세요.
|
||
|
||
---
|
||
|
||
## AI 작업 지침
|
||
|
||
> AI가 이 저장소에서 코드를 생성하거나 수정할 때 반드시 따라야 할 규칙입니다.
|
||
|
||
1. **기존 패턴 우선**: 새 코드 작성 전 인접 파일의 구조와 패턴을 파악하고 일관성 유지
|
||
2. **최소 변경 원칙**: 요청된 변경 범위를 벗어나는 수정은 하지 말 것
|
||
3. **테스트 동반 작성**: 새 함수/로직 작성 시 대응하는 단위 테스트 함께 제안
|
||
4. **불확실 시 질문**: 요구사항이 모호하면 임의로 결정하지 말고 반드시 확인 요청
|
||
5. **보안 우선**: 인증/인가 로직은 임의로 우회하거나 단순화하지 말 것
|
||
|
||
---
|
||
|
||
## 팀 연락처
|
||
|
||
| 역할 | 담당자 |
|
||
|------|--------|
|
||
| PM / Tech Lead | JM |
|