# 프로젝트 개요

이 저장소는 **풀스택 모노레포 기본 템플릿**이다. 누구나 클론하여 바로 개발을 시작할 수 있도록 공통 규칙과 언어별 규칙을 정의한다.

| 디렉터리    | 스택           | 역할                     | 개발 규칙 (스킬)                          |
| ----------- | -------------- | ------------------------ | ----------------------------------------- |
| `backend/`  | NestJS (TS)    | REST API 서버            | `/nestjs` → @.claude/skills/nestjs/SKILL.md  |
| `frontend/` | Vue 3 (TS)     | 웹 프론트엔드            | `/vue3` → @.claude/skills/vue3/SKILL.md      |
| `flutter/`  | Flutter (Dart) | 모바일 앱                | `/flutter` → @.claude/skills/flutter/SKILL.md |
| 루트        | Docker Compose | 로컬/운영 오케스트레이션 | `/docker` → @.claude/skills/docker/SKILL.md  |

세 클라이언트는 동일한 **표준 응답 포맷**과 **에러 코드 맵**을 공유한다 (아래 공통 규칙 참조).

> 규칙은 `.claude/` 아래로 모듈화되어 있다.
> - `.claude/rules/` — 세 플랫폼 공통 규칙 (코딩·응답 포맷·에러 코드·API 설계·로깅·커밋·보안·환경변수·테스트)
>   새 규칙 파일을 추가하면 **반드시 아래 `@` import 목록에도 등록**한다(등록하지 않으면 로드되지 않는다).
> - `.claude/skills/` — 도메인별 개발 규칙 (스킬). 슬래시 명령(`/nestjs` 등) 또는 해당 디렉터리 작업 시 자동 적용
> - `.claude/agents/` — 역할별 규칙 (에이전트 팀원). 역할을 지정해 호출할 때 적용
>   **`@` import 하지 않는다** — 규칙이 아니라 호출 시점에 로드되는 역할 정의다 (아래 목록 참조)
> - `.claude/settings.json` — Claude Code 권한·환경 설정

---

## 공통 규칙 (모든 디렉터리 적용)

@.claude/rules/coding-common.md
@.claude/rules/response-format.md
@.claude/rules/error-codes.md
@.claude/rules/api-design.md
@.claude/rules/logging.md
@.claude/rules/git-convention.md
@.claude/rules/security.md
@.claude/rules/env-structure.md
@.claude/rules/testing.md
@.claude/rules/checklist.md

---

## 도메인별 개발 규칙 (스킬)

- 백엔드(NestJS): @.claude/skills/nestjs/SKILL.md
- 프론트엔드(Vue 3): @.claude/skills/vue3/SKILL.md
- 모바일(Flutter): @.claude/skills/flutter/SKILL.md
- 실행/배포(Docker): @.claude/skills/docker/SKILL.md

---

## 역할별 규칙 (에이전트 팀원)

세 층의 역할 분담은 다음과 같다. **규칙은 한 곳에만 적는다** — 역할 파일은 규칙을 참조만 한다.

```
.claude/rules/    무엇을 지키는가   — 전원 공통 (위 @import 목록)
.claude/skills/   어떻게 만드는가   — 스택별
.claude/agents/   누가 맡는가       — 역할별
```

| 역할 | 파일 | 코드 수정 |
| --- | --- | --- |
| 백엔드 개발 | `.claude/agents/backend-dev.md` | O |
| 프론트엔드 개발 | `.claude/agents/frontend-dev.md` | O |
| 모바일 개발 | `.claude/agents/mobile-dev.md` | O |
| 테스터 | `.claude/agents/tester.md` | O (테스트 한정) |
| 리뷰어 | `.claude/agents/reviewer.md` | X |
| 인프라/릴리스 | `.claude/agents/release-ops.md` | O (인프라 한정) |
| 사용자 관점 | `.claude/agents/persona-user.md` | X |
| 관리자 관점 | `.claude/agents/persona-admin.md` | X |

공통 계약(경계·인계 형식·완료 기준)은 [`.claude/agents/README.md`](.claude/agents/README.md) 참조.
역할을 지정하지 않으면 평소대로 동작한다 — 모든 작업을 역할로 나눌 필요는 없다.