🏆 [도전 과제] 고급 워크플로우 종합 실습

가장 기본적인 앱부터 시작해, MCP·서브에이전트·커스텀 커맨드·훅·스킬까지 단계적으로 쌓아 올리는 본격 개발 워크플로우

앞의 실전 1·2가 "앱을 만든다"에 집중했다면, 이 장의 주인공은 앱이 아니라 워크플로우다. 플래시카드(단어장) 학습 앱을 하나의 그릇으로 삼아, 쉬운 개발에서 시작해 Claude Code의 고급 기능을 한 단계씩 얹어가며 익힌다.

#Stage 0. 오리엔테이션

#무엇을 만드나 — 플래시카드 학습 앱

영어 단어처럼 앞면(질문) / 뒷면(정답)으로 외우는 카드 학습 앱이다. 기능이 서로 독립적이라(덱 관리·퀴즈·통계·가져오기), 뒤에서 병렬 개발과 서브에이전트 분담을 실습하기에 딱 좋다.

#무엇을 배우나 — 단계별 로드맵

flowchart TB
    S1[Stage 1<br/>기본 앱] --> S2[Stage 2<br/>MCP 부착]
    S2 --> S3[Stage 3<br/>요구사항→태스크 관리]
    S3 --> S4[Stage 4<br/>병렬·서브에이전트]
    S4 --> S5[Stage 5<br/>커스텀 커맨드·훅]
    S5 --> S6[Stage 6<br/>스킬]
    S6 --> S7[Stage 7<br/>워크플로우 종합]
    style S1 fill:#e3f2fd
    style S2 fill:#e8f5e9
    style S3 fill:#fff3e0
    style S4 fill:#f3e5f5
    style S5 fill:#fce4ec
    style S6 fill:#e0f7fa
    style S7 fill:#ede7f6

#Stage 1. 기본 앱 만들기

가장 먼저, 딱 동작하는 최소 버전을 만든다. 욕심내지 않는다.

#PRD 한 장

PRD.md:

# 제품: 미니 플래시카드

## 목적
- 외우고 싶은 내용을 카드(앞면/뒷면)로 만들어 학습

## 핵심 기능 (v1)
- 카드 추가: 앞면(질문) + 뒷면(정답) 입력
- 카드 목록 보기
- 카드 클릭 시 뒤집기(앞↔뒤)
- 카드 삭제

## 기술 스택
- HTML + CSS + Vanilla JavaScript
- 저장: localStorage

## 화면
- 상단: 앞면/뒷면 입력칸 + "추가" 버튼
- 본문: 카드 그리드 (클릭하면 뒤집힘)

#한 줄 프롬프트 → 협업 루프

@PRD.md 를 읽고, 명세대로 단일 HTML 파일 플래시카드 앱을 만들어줘.
카드 뒤집기는 부드러운 3D 플립 애니메이션으로, 스타일은 깔끔하게.

처음 결과가 완벽하지 않으면 Part 7의 협업 루프로 작게 다듬는다.

#Stage 2. MCP 단계적으로 붙이기

여기서 MCP는?

MCP는 앱 안에 넣는 기능이 아니라, 개발하는 동안 Claude Code를 더 똑똑하게 만드는 외부 도구다. 한 번에 다 붙이지 말고 필요해질 때 하나씩 추가한다.

#2-1. Context7 — 최신 문서를 보며 개발

claude mcp add context7 -- npx -y @upstash/context7-mcp

#2-2. Playwright — 브라우저에서 동작 자동 검증

claude mcp add playwright -- npx -y @playwright/mcp

#2-3. GitHub — 저장소·이슈 관리

claude mcp add --transport http github https://api.githubcopilot.com/mcp/ -H "Authorization: Bearer <GitHub PAT>"

<GitHub PAT> 자리에는 GitHub Settings → Developer settings → Personal access tokens에서 발급한 토큰을 넣는다. (예전 @modelcontextprotocol/server-github 패키지는 지원 중단되어 GitHub 공식 원격 MCP로 대체됐다.)

연결된 MCP는 /mcp로 상태를 확인한다.

#Stage 3. 요구사항 → 태스크 관리 & TODO 리스트

이제 한 번에 끝낼 수 없는 큰 요구사항을 던진다.

새 요구사항 (v2)

1. 퀴즈 모드: 카드를 무작위로 보여주고 정답 맞히기, 점수 표시

2. 학습 통계: 덱별 정답률·학습 횟수 대시보드

3. 가져오기/내보내기: CSV로 카드 일괄 추가·백업

#플랜 모드로 먼저 계획

Shift + Tab으로 플랜 모드 진입 후:

위 3가지 요구사항을 구현할 계획을 세워줘. 아직 코드는 작성하지 마.
각 기능을 독립적인 작업 단위로 쪼개서 TODO 리스트로 정리해줘.

#작업 분해 → TODO 리스트로 추적

AI는 큰 요구사항을 작은 작업 목록으로 분해하고, 진행하면서 하나씩 체크해 나간다. 진행 상황은 Ctrl + T(작업 목록)으로 언제든 확인할 수 있다.

flowchart LR
    R[큰 요구사항<br/>3가지] --> P[플랜 모드<br/>계획 수립]
    P --> T["TODO 리스트<br/>□ 퀴즈 모드<br/>□ 통계 대시보드<br/>□ CSV 가져오기"]
    T --> D[하나씩 구현<br/>→ 검증 → 체크]
    D -->|반복| T
    style R fill:#fff3e0
    style P fill:#f3e5f5
    style T fill:#e3f2fd
    style D fill:#e8f5e9

#Stage 4. 병렬 처리 & 서브에이전트

Stage 3에서 쪼갠 세 기능은 서로 독립적이다. 이런 작업은 서브에이전트로 분담해 동시에 진행하면 빠르다.

서브에이전트란

"특정 작업에 특화된, 독립된 컨텍스트를 가진 AI 인스턴스" (개념은 Part 7-9 참고)

#전용 서브에이전트 정의 (선택)

.claude/agents/ 아래에 역할별 에이전트를 정의할 수 있다.

---
name: feature-builder
description: 명세를 받아 독립 기능 하나를 구현하는 개발자
tools: Read, Write, Edit, Bash
model: sonnet
---

당신은 프런트엔드 개발자입니다. 주어진 기능 명세 하나를 받아,
기존 코드 스타일에 맞춰 구현하고 동작을 확인한 뒤 결과를 보고하세요.

#병렬로 분담시키기

퀴즈 모드 / 통계 대시보드 / CSV 가져오기 — 이 세 기능은 서로 독립적이야.
각각 별도의 서브에이전트로 병렬로 구현해줘.

#결과를 모아 검증

병렬 구현이 끝나면 리뷰 전용 서브에이전트로 품질을 점검한다.

code-reviewer 서브에이전트로 방금 추가된 세 기능을 리뷰해줘.
버그·중복 코드·엣지 케이스를 중점적으로 봐줘.

#Stage 5. 커스텀 슬래시 커맨드 & 훅

반복 작업은 커스텀 커맨드로, 자동으로 강제하고 싶은 규칙은 훅으로 만든다.

#커스텀 슬래시 커맨드

자주 하는 작업을 /명령어로 만든다. .claude/commands/<이름>.md에 적는다.

.claude/commands/new-deck.md:

---
description: 주제를 받아 새 학습 덱과 예시 카드 5장을 생성합니다
argument-hint: "[주제]"
allowed-tools: Read, Edit
---

"$ARGUMENTS" 주제로 새 덱을 만들고,
초보자용 플래시카드 5장(앞면=질문, 뒷면=정답)을 채워줘.
기존 localStorage 데이터 구조에 맞춰 추가할 것.

이제 /new-deck 비즈니스 영어 처럼 쓰면 인자($ARGUMENTS)가 전달된다.

#훅 (Hooks)

훅은 특정 시점에 자동으로 실행되는 스크립트다. .claude/settings.json의 hooks에 등록한다.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write" }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/protect-env.sh" }
        ]
      }
    ]
  }
}

#Stage 6. 스킬 사용하기

스킬(Skill)이란

"설명·지침·보조 파일·스크립트를 묶어 재사용하는 '전문 능력' 패키지." 커스텀 커맨드의 확장형으로, 설명만 보고 AI가 알아서 불러 쓰거나, 사용자가 /이름으로 직접 부를 수도 있다.

#내장 스킬 활용

Claude Code에는 바로 쓸 수 있는 스킬들이 있다. 예를 들어 변경된 코드를 점검할 때:

/code-review

방금 만든 퀴즈·통계·가져오기 기능의 변경분을 리뷰해 버그와 개선점을 찾아준다.

#커스텀 스킬 만들기

.claude/skills/<이름>/SKILL.md로 만든다. (단순 커맨드와 달리 보조 문서·스크립트를 함께 번들할 수 있다.)

.claude/skills/card-quality/SKILL.md:

---
name: card-quality
description: 플래시카드 품질을 검사한다. 카드가 너무 길거나 모호하거나 중복일 때 점검·개선 제안
---

localStorage의 모든 카드를 점검하세요:

1. 앞면이 너무 길거나(20자 초과) 모호한 카드 찾기
2. 뒷면이 비어 있거나 앞면과 거의 같은 카드 찾기
3. 중복 카드 찾기
4. 각 문제에 대해 개선안을 제시

#Stage 7. 본격 개발 워크플로우 종합

지금까지 쌓은 모든 요소를 하나의 루프로 묶으면, 나만의 표준 개발 워크플로우가 된다.

flowchart TB
    subgraph 기억 & 규칙
      C[CLAUDE.md] 
      H[훅 — 자동 검증]
    end
    subgraph 실행
      PRD[요구사항/PRD] --> PLAN[플랜 모드<br/>계획]
      PLAN --> TODO[작업 분해]
      TODO --> PAR[서브에이전트<br/>병렬 구현]
      PAR --> REV[리뷰 스킬·에이전트<br/>검증]
    end
    subgraph 도구
      MCP[MCP — 문서·테스트·저장소]
      CMD[커스텀 커맨드]
    end
    C -.맥락.-> PLAN
    MCP -.지원.-> PAR
    CMD -.단축.-> TODO
    REV --> COMMIT[커밋 · 배포]
    H -.강제.-> COMMIT
    style PRD fill:#fff3e0
    style PLAN fill:#f3e5f5
    style TODO fill:#e3f2fd
    style PAR fill:#fce4ec
    style REV fill:#e8f5e9
    style COMMIT fill:#ede7f6

#표준 루프 정리

1. 요구사항 → PRD.md에 정리

2. 플랜 모드로 계획 확인 → 승인

3. 작업 분해(TODO) → 독립 작업은 서브에이전트 병렬

4. MCP·커스텀 커맨드로 개발 가속

5. 리뷰 스킬/에이전트로 검증, 훅이 규칙을 자동 강제

6. 통과하면 커밋·배포 (부록 1. Vercel 활용)

#정리

• 이 실습의 핵심은 앱이 아니라 "쉬운 개발 → 고급 기능 → 표준 워크플로우"로 올라가는 과정이다

• MCP는 필요할 때 하나씩, 태스크 관리로 큰 요구사항을 쪼개고, 서브에이전트로 독립 작업을 병렬화한다

• 커스텀 커맨드·훅·스킬로 반복과 검증을 자동화하면, 사람은 요구사항 정의와 최종 검증에만 집중하게 된다

• 도구가 늘어날수록 중요한 건 변하지 않는다 — 작게 만들고, 자주 검증하고, 되돌릴 수 있게 둔다.