fe-agent/shrimp-rules.md

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 필수 필드

---
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 재사용 불가