# 🤖 프론트엔드 에이전트 자동화 시스템 가이드

이 문서는 `gameservice-fe-agent` 패키지에 탑재된 두 가지 핵심 자동화 프로세스—**프로젝트 자율 인지(Dreaming) 시스템** 및 **AI 개발 스쿼드(Squad) 오케스트레이션**의 개념과 실행 방법을 상세히 가이드합니다.

이 도구들은 일회성(Stateless) AI 코드 작성의 한계를 넘어, **지속성 있는 컨벤션 수호자(Convention Guardian)**로 동작하고 복잡한 컴포넌트를 **병렬 전문 역할 분담 스쿼드**를 통해 해결하는 것을 목적으로 합니다.

---

## 🧠 1. "AI 코더"에서 "상태 저장형 컨벤션 가디언"으로 (Dreaming)

### 💡 도입 배경 및 개념
일반적인 LLM 코딩 에이전트는 프롬프트를 보낼 때마다 컨텍스트가 초기화되는 **단발성(Stateless)** 모델로 동작합니다. 이 때문에 기존 프로젝트의 폴더 구조, 이미 만들어진 커스텀 Composable(useXxx), 활성화된 Pinia 스토어 목록, 패키지 버전 등을 매번 인지하지 못해 불필요한 코드를 중복 구현하거나 기존 컨벤션을 깨는 실수를 저지릅니다.

**Dreaming 자동화 시스템**은 에이전트가 "코드베이스 전체를 정기적으로 자율 성찰(Self-reflection)"하도록 만드는 로컬 구현체입니다. `dreaming.js`를 구동하면 프로젝트의 상태를 휴리스틱하게 분석하여 `.claude/project/dreaming-context.md` 파일에 기록하고, `CLAUDE.md` 수입 선언을 통해 에이전트가 시작부터 이 최신 상태를 인지하게 만듭니다.

### 🛠 실행 및 연동 방법

#### ① 실행 명령어
프로젝트 루트 경로에서 아래 스크립트를 구동합니다:
```bash
node .claude/skills/dreaming/scripts/dreaming.js
```

#### ② 자동 수행되는 태스크
1. `package.json` 파싱: 프레임워크 버전, 핵심 기술 스택(Nuxt, Pinia, Tailwind, Vitest 등), 실행 가능한 스크립트 명령어 수집.
2. 디렉토리 구조 스캔: 활성화된 디렉토리와 소속 파일 개수, 구조적 예시 목록 도출.
3. **Pinia 스토어 자율 추출:** `stores/` 내부의 파일들을 분석하여 각 스토어의 ID, 반응형 상태(state/computed), 비즈니스 함수(actions) 목록을 정밀 인지.
4. **커스텀 Composable 자율 추출:** `composables/` 내부의 `useXxx` 스타일 컴포저블을 검출해 노출 함수 리스트 확보.
5. **유닛 테스트 통계 파싱:** 구축된 테스트 파일 목록 및 통계 추출.
6. **마크다운 출력 및 자동 임포트:** 수집된 정보를 마크다운 리포트로 자동 빌드해 `.claude/project/dreaming-context.md` 파일에 덮어쓰고, 루트의 `CLAUDE.md`에 `@.claude/project/dreaming-context.md` 임포트 구문이 없으면 이를 자동으로 연결합니다.

### 📌 시니어 FE 관점의 기대 효과
* **중복 코드 생성 전면 억제:** 에이전트가 이미 존재하는 Pinia 스토어나 커스텀 훅을 즉시 찾아내기 때문에, 동일한 API 바인딩이나 헬퍼 함수를 이중으로 작성하지 않습니다.
* **프로젝트 맞춤형 가상 주니어화:** 며칠 쉬고 오거나 세션이 만료되더라도, 에이전트가 단 1초 만에 프로젝트의 최신 스냅샷을 뇌리에 새긴 상태(Stateful)로 지능적인 보조를 시작합니다.

---

## 👥 2. "AI 한 명과 대화"가 아닌 "AI 개발 스쿼드(Squad) 오케스트레이션"

### 💡 도입 배경 및 개념
아무리 성능이 뛰어난 모델이라도 템플릿 마크업 작성, 복잡한 Tailwind 스타일링, WCAG 2.1 AA 접근성 마크업, 그리고 Vitest 단위 테스트 작성을 한 번에 지시하면 문맥 누락이나 결함(Bug)이 발생하기 마련입니다.

**스쿼드 오케스트레이션**은 하나의 피처 요청을 **3인의 가상 전문 개발 에이전트**로 쪼개어 단계별/병렬 협업 파이프라인으로 수행하는 시스템입니다. 시니어 프론트엔드 엔지니어(Gil)는 코드 작성에 시간을 소모하는 대신, 이 전문 에이전트들을 조율하고 합산 결과물의 비즈니스 사양과 렌더링을 최종 승인하는 **오케스트레이터(Orchestrator)**의 최고 존엄 지위를 갖게 됩니다.

```
                  ┌──────────────────────┐
                  │ Gil (Orchestrator)   │
                  └──────────┬───────────┘
                             │ (스쿼드 생성 지시)
                             ▼
┌────────────────────────────────────────────────────────┐
│               squad-orchestrator.js                    │
└────────────┬───────────────┬───────────────┬───────────┘
             │               │               │
             ▼               ▼               ▼
     ┌──────────────┐┌──────────────┐┌──────────────┐
     │  Role 1      ││  Role 2      ││  Role 3      │
     │  UI/마크업   ││  웹 접근성   ││  QA/단위테스트│
     │  스페셜리스트 ││  스페셜리스트 ││  스페셜리스트 │
     └───────┬──────┘└───────┬──────┘└───────┬──────┘
             │               │               │
             ▼               ▼               ▼
     [구조 & 뼈대 빌드] [ARIA & 키보드 주입] [Vitest 케이스 PASS]
```

### 🛠 실행 및 연동 방법

#### ① 스쿼드 조직하기 (인터랙션/CLI 겸용)
새로운 피처나 컴포넌트를 설계할 때 아래 스크립트를 구동합니다:

* **대화형 모드로 조직하기:**
  ```bash
  node .claude/skills/squad-orchestration/scripts/squad-orchestrator.js
  ```
  명령어 실행 후 터미널의 질문에 따라 컴포넌트 이름과 요구 스펙을 입력하면 스쿼드가 즉시 조직됩니다.

* **CLI 인자로 한 번에 조직하기:**
  ```bash
  node .claude/skills/squad-orchestration/scripts/squad-orchestrator.js --name "UserScoreCard" --spec "유저 프로필과 전적, 랭킹을 보여주고 점수에 따라 테두리 색상이 바뀌는 컴포넌트 구현"
  ```

#### ② 스쿼드 파일 구성 및 역할
명령이 끝나면 루트에 `squad/<ComponentName>/` 폴더가 자동 생성됩니다.
* **`tasks/01_markup_agent.md` (Role 1):** Vue 3 템플릿, 데이터 상태 설계, Tailwind 반응형 레이아웃 구성 집중 지시서.
* **`tasks/02_a11y_agent.md` (Role 2):** WCAG 2.1 AA 기준 준수, ARIA 역할(role), 스크린 리더용 라벨링, 키보드 인터랙션 집중 보완 및 Surgical 정밀 수정 지시서.
* **`tasks/03_test_agent.md` (Role 3):** 생성된 컴포넌트 사양 검증을 위한 `*.spec.ts` 단위 테스트 코드 및 Mock 데이터 구축 지시서.
* **`run-squad.js`:** Claude Code CLI를 연속 구동하여 세 단계의 코딩 에이전트를 차례로 자동 실행하고, 마지막에 Vitest 테스트 엔진을 가동하여 검증을 완수해 내는 마스터 러너 스크립트.

#### ③ 스쿼드 자동 파이프라인 가동
스쿼드가 세팅되면, 해당 컴포넌트 폴더 내의 마스터 스크립트를 즉시 가동하여 오토파일럿 개발을 시작할 수 있습니다:
```bash
node squad/<ComponentName>/run-squad.js
```

### 📌 시니어 FE 관점의 기대 효과
* **결점 제로(Defect-Free) 컴포넌트 완성:** 각 역할군이 하나의 관점(UI 구조 -> 접근성 -> 테스트 품질)에 완벽히 몰입하여 단계별로 코드를 가꾸고 다듬기 때문에, 품질적으로 완벽무결한 컴포넌트가 조립됩니다.
* **테스트 주도 개발(TDD)의 정수 체득:** 최종 테스트가 완료될 때까지 에이전트 루프가 가동되므로, 코드를 올리기도 전에 모든 단위 동작과 가시적인 비즈니스 엣지 케이스들의 통과를 보장받은 채 개발이 마무리됩니다.

---

## 🚀 실무 도입 시 베스트 프랙티스

1. **지속성 확보를 위한 git ignore 추가 권장:**
   `squad/` 폴더 내의 작업 지시서나 가이드 파일들은 개발 도중의 중간 생성물(Task sheets)에 해당하므로, 프로젝트의 메인 git 히스토리를 깔끔하게 유지하기 위해 `.gitignore`에 `squad/` 경로를 추가하는 것을 추천합니다.
   
2. **개발 전 dreaming 구동 루틴화:**
   새로운 브랜치를 따거나 대규모 PR을 머지받았을 때는 에이전트에게 일을 시키기 전 `node .claude/skills/dreaming/scripts/dreaming.js`를 한 번 실행해 주는 것이 좋습니다. 에이전트의 뇌 스냅샷을 1초 만에 최신화해 줍니다.