이 디렉토리는 레이어 비종속(cross-cutting) 문서를 보관한다. 각 레이어 내부 규약은 해당 레이어의
CLAUDE.md를 참고한다.
product-overview.md— 제품 비전, 페르소나, 핵심 차별점architecture.md— 시스템 아키텍처, 컴포넌트 책임 분담data-flow.md— 핵심 시나리오별 데이터 흐름
database.md— DDL, ENUM, 인덱싱, Flyway 정책api-conventions.md— REST API 설계 규약, 에러 코드, 페이지네이션messaging.md— RabbitMQ 큐/익스체인지, 메시지 스키마, 재시도 정책storage.md— S3(MinIO) 키 컨벤션, 버킷 설계event-stream.md— SSE 이벤트 스펙
design-system.md— 토큰, 컬러, 타이포그래피, 컴포넌트 인벤토리ui-patterns.md— 반복되는 UX 패턴, 상태 처리 (loading/empty/error)frontend-types.md— TypeScript 타입 네이밍·레이어별 흐름·정의 위치
security.md— 인증·인가, 토큰 암호화, 개인정보 처리observability.md— X-Trace-Id, 로깅 레벨, AI 요청 로깅environment.md— 환경 변수, 로컬/스테이징/운영 분리
coding-conventions.md— 언어별 공통 코딩 규약git-conventions.md— 브랜치 전략, 커밋 컨벤션, PR 템플릿testing-strategy.md— 테스트 피라미드, 핵심 시나리오 정의glossary.md— 도메인 용어집 (한/영 대응)
| 레이어 | 진입 문서 | 역할 |
|---|---|---|
| 루트 | /CLAUDE.md |
전체 오버뷰 + 인덱스 |
| 프론트 | /frontend/CLAUDE.md |
React/FSD 구조 |
| 백엔드 | /backend/CLAUDE.md |
Spring Boot Core 서버 |
| AI | /ai/CLAUDE.md |
FastAPI/LangChain 서버 |
| 인프라 | /infra/CLAUDE.md |
Docker Compose, PG/RabbitMQ/MinIO |
각 레이어 하위 디렉토리에도 슬라이스/도메인별
CLAUDE.md가 존재할 수 있다. 작업할 디렉토리에서 가장 가까운CLAUDE.md를 우선 참고한다.
- 단일 출처 원칙(Single Source of Truth): 같은 정보를 두 곳에 쓰지 않는다. 다른 문서를 링크로 참조한다.
- 레이어 종속성 방향: 횡단 관심사 → 레이어 → 슬라이스. 상위 문서는 하위를 모르고, 하위는 상위를 참조한다.
- 변경 시 함께 갱신: 코드 변경이 컨벤션·아키텍처·DB 스키마에 영향을 주면 해당 문서도 같은 PR에 포함한다.
- 예시 우선: 추상적 설명보다 실제 코드 스니펫·DDL·요청 예시로 보여준다.
- 한국어 우선: 도메인 용어는 한국어로, 기술 용어·식별자(클래스명·테이블명·ENUM)는 영문 그대로 둔다.