CLAUDE.md 가이드

## 1. 핵심 정체성
 
MoAI는 Claude Code의 전략적 오케스트레이터입니다.
 
### HARD 규칙 (필수)
- [HARD] 언어 인식 응답: 사용자의 conversation_language로 응답
- [HARD] 병렬 실행: 독립적인 도구 호출은 병렬 실행
- [HARD] XML 태그 비표시: 사용자 대면 응답에 XML 비표시
- [HARD] Markdown 출력: 모든 커뮤니케이션에 Markdown 사용

# Plan: SPEC 문서 생성 (30K 토큰)
> /moai plan "기능 설명"
 
# Run: DDD 구현 (180K 토큰)
> /moai run SPEC-XXX
 
# Sync: 문서 동기화 (40K 토큰)
> /moai sync SPEC-XXX

language:
  conversation_language: ko           # 사용자 응답 언어
  agent_prompt_language: en           # 에이전트 내부 언어
  git_commit_messages: en             # Git 커밋 메시지
  code_comments: en                   # 코드 주석
  documentation: en                   # 문서 파일

# 프로젝트 로컬 설정
 
## 문서 작성 가이드라인
 
### MDX 렌더링 오류 방지
- 강조 표시와 괄호 사이에 반드시 공백
 
### Mermaid 다이어그램 방향
- 모든 다이어그램은 세로 방향 (flowchart TD)
 
## 개인 메모
- DB 마이그레이션 전 백업 필수
- API 엔드포인트 네이밍: kebab-case 사용

.claude/rules/moai/
├── core/                          # 핵심 원칙
│   └── moai-constitution.md       # TRUST 5, 핵심 규칙
├── development/                   # 개발 표준
│   ├── skill-authoring.md         # 스킬 작성 가이드
│   └── coding-standards.md        # 코딩 표준
├── workflow/                      # 워크플로우
│   ├── workflow-modes.md          # Plan/Run/Sync 정의
│   └── spec-workflow.md           # SPEC 워크플로우
└── languages/                     # 언어별 규칙 (16개)
    ├── python.md
    ├── typescript.md
    ├── javascript.md
    └── ...

---
paths:
  - "**/*.py"
  - "**/pyproject.toml"
---
 
# Python 코딩 규칙
- ruff 포맷터 사용
- type hints 필수
- docstring은 Google 스타일

# 프로젝트 로컬 설정
 
## React 규칙
- 컴포넌트는 반드시 함수형으로 작성
- Props 인터페이스는 컴포넌트 파일 상단에 정의
- 상태 관리는 Zustand 사용
- CSS는 Tailwind CSS만 사용
 
## 네이밍 규칙
- 컴포넌트: PascalCase (UserProfile.tsx)
- 유틸리티: camelCase (formatDate.ts)
- 상수: UPPER_SNAKE_CASE (MAX_RETRY_COUNT)
- API 엔드포인트: kebab-case (/api/user-profiles)
 
## 금지 사항
- any 타입 사용 금지
- console.log 프로덕션 코드에 금지
- default export 금지 (named export만 사용)

# 프로젝트 로컬 설정
 
## Python 규칙
- FastAPI 사용
- 비동기 함수 우선 (async/await)
- Pydantic v2 모델 사용
- SQLAlchemy 2.0 스타일
 
## 데이터베이스 규칙
- 마이그레이션 전 반드시 백업
- 인덱스는 쿼리 패턴 분석 후 추가
- soft delete 패턴 사용 (is_deleted 플래그)
 
## API 규칙
- RESTful 엔드포인트 네이밍
- 응답 형식 통일: {"data": ..., "message": ...}
- 에러 코드 표준화