115 lines
5.0 KiB
Markdown
115 lines
5.0 KiB
Markdown
# Development Guidelines
|
|
|
|
## 프로젝트 개요
|
|
|
|
- **목적**: Smilegate FE팀의 AI 활용 표준화 로드맵 관리 및 커스텀 에이전트 운영 도구
|
|
- **핵심 산출물**: `docs/ROADMAP.md` — FE AI 표준화 13주 실행 로드맵 (Sprint 0-6)
|
|
- **기술 스택**: Nuxt 4, TypeScript strict, Tailwind CSS v4, shadcn-vue, Pinia, Vitest
|
|
- **이 디렉토리는 Nuxt 앱이 아님** — 앱 코드(Vue 컴포넌트, 페이지 등)를 이 디렉토리에 생성하지 않는다
|
|
|
|
---
|
|
|
|
## 프로젝트 구조
|
|
|
|
```
|
|
fe-agent/
|
|
├─ .claude/
|
|
│ ├─ agents/ # 커스텀 에이전트 정의 파일 (YAML frontmatter + 프롬프트)
|
|
│ │ └─ frontend-roadmap-architect.md # 로드맵 설계 전문 에이전트
|
|
│ ├─ agent-memory/ # 에이전트별 영구 메모리
|
|
│ │ └─ frontend-roadmap-architect/
|
|
│ │ └─ MEMORY.md # 에이전트 영구 메모리 (200줄 이내 유지)
|
|
│ └─ settings.local.json
|
|
├─ docs/
|
|
│ └─ ROADMAP.md # FE AI 표준화 실행 로드맵 (핵심 문서)
|
|
├─ shrimp_data/ # shrimp-task-manager 내부 데이터 (직접 편집 금지)
|
|
├─ .mcp.json # MCP 서버 설정
|
|
└─ shrimp-rules.md # 이 파일 (AI Agent 운영 규칙)
|
|
```
|
|
|
|
---
|
|
|
|
## 파일 상호작용 규칙
|
|
|
|
### ROADMAP.md 수정 시
|
|
- `docs/ROADMAP.md`의 로드맵 구조(스프린트, 마일스톤, 팀 구성, KPI)가 변경되면 `.claude/agent-memory/frontend-roadmap-architect/MEMORY.md`의 해당 섹션을 동기화한다
|
|
- 새 스프린트 추가 → MEMORY.md의 "로드맵 설계 패턴" 섹션 업데이트
|
|
- 기술 스택 변경 → MEMORY.md의 "프로젝트 컨텍스트" 섹션 업데이트
|
|
|
|
### 에이전트 추가 시
|
|
- `.claude/agents/[에이전트명].md` 파일 생성
|
|
- `.claude/agent-memory/[에이전트명]/MEMORY.md` 파일 동시 생성 (초기에는 빈 메모리 파일)
|
|
- 에이전트 파일은 반드시 YAML frontmatter(`name`, `description`, `model`, `color`) 포함
|
|
|
|
### 에이전트 정의 수정 시
|
|
- `.claude/agents/[에이전트명].md` 역할/능력 변경 시 MEMORY.md의 관련 컨텍스트 항목을 함께 검토
|
|
- `description` 필드 변경은 에이전트 트리거 조건에 직접 영향 — 주의하여 수정
|
|
|
|
---
|
|
|
|
## 언어 및 커뮤니케이션 규칙
|
|
|
|
- **모든 문서**: 한국어로 작성
|
|
- **코드 주석**: 한국어
|
|
- **커밋 메시지**: 한국어 (`feat: 로드맵 Sprint 3 태스크 추가`)
|
|
- **변수/함수명**: 영어 (코드 표준 준수)
|
|
- **에이전트 프롬프트**: 한국어 (YAML frontmatter의 `description`은 영어 허용)
|
|
|
|
---
|
|
|
|
## 로드맵 문서 작성 규칙
|
|
|
|
- 태스크는 **1-3일** 단위로 분해 (3일 초과 시 재분해)
|
|
- 스프린트 구성: 목표 → 태스크 목록 → 완료 기준(DoD) → 리스크 및 의존성 순서 준수
|
|
- 우선순위는 MoSCoW 분류(`Must` / `Should` / `Could`) 명시
|
|
- 새 태스크 ID 생성 규칙: `T[스프린트번호]-[순번]` (예: `T3-5`)
|
|
- 부록 "원본 문서 항목 → 태스크 매핑표"에 새 태스크 반영 시 매핑표도 갱신
|
|
|
|
---
|
|
|
|
## 에이전트 정의 파일 작성 규칙
|
|
|
|
### YAML Frontmatter 필수 필드
|
|
```yaml
|
|
---
|
|
name: 에이전트명 (영어 kebab-case)
|
|
description: "트리거 조건 포함 상세 설명 (영어 또는 한국어)"
|
|
model: opus | sonnet | haiku
|
|
color: red | blue | green | yellow | purple | orange
|
|
---
|
|
```
|
|
|
|
### 프롬프트 작성 원칙
|
|
- 에이전트의 **역할**, **전문성**, **산출물 형식**, **자기 검증 체크리스트**를 포함
|
|
- 에스컬레이션 조건(모호한 요구사항 처리 방법)을 명시
|
|
- `memory: project` 설정 시 `.claude/agent-memory/[에이전트명]/` 디렉토리 생성 필수
|
|
|
|
---
|
|
|
|
## AI 의사결정 기준
|
|
|
|
### 문서 수정 요청이 모호할 때
|
|
1. `docs/ROADMAP.md` 현재 내용 확인
|
|
2. 변경 범위가 단일 태스크인지 스프린트 전체인지 파악
|
|
3. 의존성 있는 다른 태스크에 영향 여부 판단 후 수정
|
|
|
|
### 새 에이전트 추가 vs 기존 에이전트 수정
|
|
- 역할이 완전히 다른 경우 → 새 에이전트 파일 생성
|
|
- 기존 에이전트의 전문성 범위 확장인 경우 → 기존 파일 수정
|
|
|
|
### MEMORY.md 업데이트 시점
|
|
- 로드맵 구조 변경 → 즉시 동기화
|
|
- 일회성 작업 결과 → 저장하지 않음
|
|
- 팀 컨벤션/의사결정 확정 → 저장
|
|
|
|
---
|
|
|
|
## 금지사항
|
|
|
|
- **`shrimp_data/` 직접 편집 금지** — shrimp-task-manager가 내부적으로 관리하는 디렉토리
|
|
- **앱 코드 생성 금지** — Vue 컴포넌트, Nuxt 페이지 등은 이 디렉토리가 아닌 실제 Nuxt 프로젝트에서 작업
|
|
- **MEMORY.md 200줄 초과 금지** — 초과 시 세부 내용은 별도 토픽 파일로 분리 후 링크
|
|
- **명시적 요청 없이 커밋/푸시 금지**
|
|
- **에이전트 파일에서 `any` 타입 사용 금지** (TypeScript 코드 포함 시)
|
|
- **로드맵 태스크 ID 중복 사용 금지** — 삭제된 태스크 ID 재사용 불가
|