gil/game-fe-agent
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
8876998acd3a85547b3b81897edbcf5657bbffc3
game-fe-agent/skills/squad-orchestration/docs/automation-guide.md
gil 8876998acd 📝 docs: 여러 문서 및 파일 삭제
2026-05-21 21:56:04 +09:00

8.9 KiB
Raw Blame History

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

이 문서는 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 수입 선언을 통해 에이전트가 시작부터 이 최신 상태를 인지하게 만듭니다.

🛠 실행 및 연동 방법

① 실행 명령어

프로젝트 루트 경로에서 아래 스크립트를 구동합니다:

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 겸용)

새로운 피처나 컴포넌트를 설계할 때 아래 스크립트를 구동합니다:

  • 대화형 모드로 조직하기:

    node .claude/skills/squad-orchestration/scripts/squad-orchestrator.js

    명령어 실행 후 터미널의 질문에 따라 컴포넌트 이름과 요구 스펙을 입력하면 스쿼드가 즉시 조직됩니다.

  • CLI 인자로 한 번에 조직하기:

    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 테스트 엔진을 가동하여 검증을 완수해 내는 마스터 러너 스크립트.

③ 스쿼드 자동 파이프라인 가동

스쿼드가 세팅되면, 해당 컴포넌트 폴더 내의 마스터 스크립트를 즉시 가동하여 오토파일럿 개발을 시작할 수 있습니다:

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초 만에 최신화해 줍니다.