이 lesson 을 다 읽고 나면 아래 3가지를 자신 있게 할 수 있습니다.

• ▸✅ SPEC → Plan → Tasks → Implement 흐름
• ▸✅ Agent 모드 안전 사용 (dry-run · 승인 게이트)
• ▸✅ Git 커밋 단위 + AI 가 만든 코드의 PR 설명법

학습 목표를 체크리스트로 두고 다 답할 수 있게 되면 lesson 을 닫으세요.

한 줄: 단순 작업 = 빠른 vibe / 복잡 작업 = 먼저 SPEC.

언제 SPEC 우선:

• ▸🟢 대규모 기능 (1주+ 작업)
• ▸🟢 다인 협업 (PR 리뷰어 필요)
• ▸🟢 보안·결제·인증
• ▸🟢 백엔드 API 계약
• ▸🟢 데이터 스키마 변경

언제 Vibe 우선:

• ▸🟢 UI 컴포넌트 (보일러플레이트)
• ▸🟢 작은 버그 수정
• ▸🟢 리팩토링·이름 변경
• ▸🟢 테스트 작성
• ▸🟢 문서·주석

Spec-Kit 워크플로우 (GitHub, 2025):

/specify  → spec.md  (요구사항)
/plan     → plan.md  (구현 전략)
/tasks    → tasks.md (체크리스트)
/implement→ 실제 코드 작성

Anthropic Skills + Claude Code 와 결합 시 자동화.

에이전트 = LLM 이 도구 호출·결과 확인·다음 행동 결정 을 자율적으로 반복.

기본 루프:

1. 목표 받기
2. 계획 (subtask 분해)
3. 도구 호출 (편집·실행·테스트)
4. 결과 평가
5. 다음 행동 결정 → 2 로 (또는 종료)

에이전트가 잘하는 작업:

• ▸🟢 반복 작업: 100 파일 일괄 변경
• ▸🟢 탐색: 코드베이스 이해·디버깅 가설 검증
• ▸🟢 수동적 작업: 마이그레이션·테스트 작성·문서 업데이트
• ▸🟢 밤·주말 작업: 사용자 자고 있을 때 PR 자동 생성

제약:

• ▸🔴 완전 자율 X — 5-10 분마다 사용자 승인 권장
• ▸🔴 비싼 호출 (Opus 1M 컨텍스트 = $90/M)
• ▸🔴 위험한 동작 (rm -rf·DB DROP) 직접 실행 위험
• ▸🔴 환각 — 가짜 함수 호출·문서 생성

안전장치:

• ▸권한 모드: ask (모든 행동 승인) → acceptEdits (편집만) → plan (수정 X)
• ▸샌드박스: Docker·worktree 분리
• ▸체크포인트: 매 commit 후 review
• ▸롤백 준비: git reset 으로 복구 가능

> 💡 2025 추세: GitHub Actions + Claude Code 결합 → 밤에 PR 자동 생성·테스트 패턴 확산.

TDD 사이클: Red (실패 테스트) → Green (통과 코드) → Refactor (정리)

AI 의 역할:

AI 가 잘하는 테스트:

• ▸🟢 단위 테스트 (input/output 단순)
• ▸🟢 엣지 케이스 (null·빈 배열·매우 큰 수)
• ▸🟢 보일러플레이트 (jest·vitest·pytest setup)

AI 가 못하는 테스트:

• ▸🔴 복잡한 통합 테스트 (DB·외부 API·인증 흐름)
• ▸🔴 비즈니스 요구사항 (도메인 지식 필요)
• ▸🔴 성능 테스트 (실제 환경 필요)
• ▸🔴 flaky test 진단 (타이밍·환경 의존)

Cursor·Claude Code 활용:

"이 함수 (/src/auth.ts) 의 vitest 테스트 작성:
- 성공 케이스 (유효 이메일·비번)
- 실패 (빈 입력·짧은 비번·잘못된 이메일)
- 엣지 (이메일 100자·비번 1000자·SQL injection 시도)
- 모킹: db, bcrypt"

> 💡 Iron Law: AI 가 만든 테스트도 내가 읽고 이해. 통과만 보고 신뢰 X.

원칙:
1. 작은 커밋 — 1 커밋 = 1 변경 의도. AI 리뷰가 효과적
2. 명확한 메시지 — Conventional Commits (feat·fix·refactor)
3. PR 자동화 — Copilot Review·CodeRabbit 등 자동 1차 리뷰
4. 자동 테스트 — CI 가 통과해야 머지

AI Git 도구:

AI 시대 PR 템플릿:

## 변경
- 무엇·어디·왜

## AI 협업
- 사용 도구: Cursor Composer / Claude Code
- AI 생성 비율: ~60% (보일러플레이트), 40% 직접
- 검증: 통합 테스트 통과·수동 dogfood

## 테스트
- vitest pass: 12/12
- 수동: dev 서버에서 입력·예외 확인

흔한 함정:

• ▸❌ AI 가 만든 코드 전부 한 커밋 — 리뷰 불가
• ▸❌ AI 가 다른 곳도 임의 수정 — review 시점에 놀람
• ▸❌ 컴파일 오류만 보고 머지 — 비즈니스 동작 미검증
• ▸✅ Plan 모드로 시작 → 작은 단위 변경 → 즉시 커밋

SPEC 작성이 왜 토큰을 절약하나

옛 방식: 매 대화마다 "이런 기능 만들어줘 → AI 가 질문 → 답변 → AI 가 구현" 반복. 같은 컨텍스트 N번 반복.

SPEC-Driven: 먼저 spec.md 한 번 작성 → 이후 모든 대화는 그 spec 참조. 컨텍스트 1번 + 작은 후속 대화.

실전 흐름

1단계: AI 와 함께 spec.md 작성

나: 결제 시스템 만들고 싶어. spec 부터 짜자.
   - 결제 게이트웨이: 토스
   - 상품: 단일 구매 + 정기 구독
   - 환불·정산 로직 필요
   AI 가 명세 작성해줘.

AI: (spec.md 작성)
  # 결제 시스템 명세

  ## 요구사항
  1. 결제 게이트웨이 통합 (토스)
  2. 상품 종류: SINGLE / SUBSCRIPTION
  3. 환불 처리 (7일 이내)
  4. 정산 (매월 1일)

  ## API 엔드포인트
  - POST /api/payments/init
  - POST /api/payments/confirm
  - POST /api/payments/refund
  ...

이 spec.md 가 프로젝트 루트 에 저장.

2단계: 구현 — 반복 설명 없이

나: spec.md 의 POST /api/payments/init 구현해줘.

AI: (spec 읽고 정확히 구현)

매번 "토스 게이트웨이·구독·환불 정책" 반복 안 함. spec 한 번 + 짧은 요청 만.

3단계: 코드 리뷰 — spec 기준

나: 구현이 spec.md 와 일치하나? 차이 있으면 알려줘.

AI: (spec 과 코드 대조)
  ✅ /init 엔드포인트 — spec 일치
  ⚠️ /refund — spec 은 7일이지만 코드는 14일로 됨
  ❌ /confirm — spec 의 webhook 검증 단계 누락

Spec-Kit (GitHub, 2025)

GitHub 이 만든 SPEC-Driven 표준 도구. 4 단계 자동화:

/specify  → spec.md 자동 생성 (요구사항)
/plan     → plan.md 자동 생성 (구현 전략)
/tasks    → tasks.md 자동 생성 (체크리스트)
/implement → 실제 코드 작성

Claude Code·Cursor 와 결합하면 명세 → 코드 까지 한 흐름.

SPEC vs Vibe — 다시 정리

한 번 정리

• ▸큰 작업 → 먼저 SPEC, 그 후 구현 = 토큰 절약 + 일관성
• ▸작은 작업 → 그냥 Vibe 도 OK
• ▸Spec-Kit 으로 명세 → 코드 자동화

핵심 한 줄

에이전트 = AI 가 자율로 파일 수정·명령 실행 함. 잘못 쓰면 내 코드·DB·운영 환경 까지 망가질 수 있음. 안전 사용 5원칙.

⚠️ 절대 하지 마세요

1. --dangerously-skip-permissions 금지

Claude Code 옵션 중 모든 권한 자동 승인 모드가 있습니다. 빠르긴 하지만 AI 가 rm -rf 같은 위험한 명령 도 질문 없이 실행. 운영 코드·DB 망가짐.

✅ 항상 기본 모드 (Ask 또는 Plan) 로 시작.

2. 권한 모드 단계 — 점진적 허용

추천 흐름: Plan 으로 시작 → 검토 → Ask 로 단계별 → 필요 시 AcceptEdits

3. Git commit 자주 — 롤백 포인트

# 작업 시작 전
git add -A && git commit -m "checkpoint: 에이전트 작업 시작 전"

# 에이전트 작업 후
git diff   # 변경 확인
git add -p # 부분 staging (의도하지 않은 변경 제외)
git commit -m "feat(auth): JWT refresh 추가"

# 망쳤으면
git reset --hard HEAD~1   # 직전 커밋으로

매 의미 단위 마다 commit. 망친 부분만 부분 롤백 가능.

4. 별도 worktree 로 격리

git worktree add ../myapp-experiment my-feature
cd ../myapp-experiment
claude    # 격리된 폴더에서 작업

원본 코드 손상 0%. 망치면 git worktree remove ../myapp-experiment 로 끝.

5. Docker 컨테이너 — 진짜 격리

docker run --rm -it -v $(pwd):/app -w /app node:20 bash
# 안에서 claude 실행
# 컨테이너 안에서만 명령 실행 → 호스트 안전

위험한 작업 (DB 마이그레이션·시스템 명령) 은 반드시 컨테이너에서.

위험한 명령어 블랙리스트

에이전트가 실행하기 전 한 번 더 확인:

• ▸rm -rf (특히 * 또는 / 포함)
• ▸git reset --hard (커밋 잃음)
• ▸git push --force (원격 덮어쓰기)
• ▸DROP TABLE·TRUNCATE (DB 데이터 삭제)
• ▸npm publish (실수 publish)
• ▸curl ... | sh (외부 스크립트 실행)
• ▸sudo 가 붙은 모든 명령

사고 났을 때 — 빨리 복구

1. 즉시 정지 — Ctrl+C
2. 변경 확인 — git status·git diff
3. 롤백 — git reset --hard HEAD 또는 git stash
4. DB 면 — 마지막 백업 확인
5. 사후 분석 — ~/.claude/projects/ 의 transcript 검토

한 번 정리

• ▸절대 모든 권한 자동 허용 X
• ▸Plan → Ask → AcceptEdits 단계적
• ▸git commit 자주 + worktree 격리 + Docker 가 안전망
• ▸위험 명령은 한 번 더 확인

왜 컨벤션 따르나

fix: bug fixed

이런 메시지 100개면 나중에 찾을 수 없음. 표준 컨벤션 따르면:

• ▸git log --grep "^feat(auth)" — auth 영역의 새 기능만
• ▸semantic-release — 자동 버전 + CHANGELOG
• ▸CI 검증 — commitlint 로 잘못된 메시지 PR 차단

형식

<type>(<scope>): <description>

[optional body]

[optional footer]

• ▸type — feat·fix·refactor·docs·test·chore·perf·style
• ▸scope — 영역 (auth·api·ui 등)
• ▸description — 명령형, 50자 이내

실전 예시 5개

1. feat — 새 기능

feat(auth): add JWT refresh token rotation

- Access token TTL 단축 (60min → 15min)
- Refresh token rotation 도입 (재사용 시 전체 무효)
- httpOnly + Secure + SameSite=Lax cookie
- 관련 RFC 8252 권장 사항 반영

Closes #142

2. fix — 버그 수정

fix(api): handle null user in /api/me

비로그인 상태에서 /api/me 호출 시 500 에러 발생.
세션 검증 결과 null 일 때 401 명시적 응답으로 변경.

Before: TypeError: Cannot read 'id' of null → 500
After:  { error: 'NOT_AUTHENTICATED' } → 401

Fixes #198

3. refactor — 리팩토링 (동작 변경 X)

refactor(db): migrate from Prisma to Drizzle

- 빌드 시간 8s → 2s (Prisma generate 제거)
- 번들 크기 250KB → 50KB
- TypeScript inference 정확도 향상

Migration guide: docs/db-migration.md

4. test — 테스트 추가·수정

test(auth): add edge cases for login endpoint

- 빈 비밀번호
- SQL injection 시도 (`' OR '1'='1`)
- 1000자 이상 입력
- 잘못된 이메일 형식 (RFC 5322)

Coverage: 78% → 91%

5. chore — 빌드·의존성·도구

chore(deps): bump next from 14.1 to 14.2

Security: CVE-2024-XXXX 패치 포함
Breaking: middleware matcher 정규식 변경

Migration:
- middleware.ts:12 matcher 패턴 갱신
- /api/auth/* → /api/auth/(.*) 로

팀 컨벤션 예시

추가 type (팀에 따라):

• ▸perf — 성능 개선
• ▸style — 포매팅·세미콜론 (CSS 아님)
• ▸ci — GitHub Actions·workflow
• ▸build — webpack·vite 설정
• ▸revert — 이전 커밋 되돌리기

commitlint 자동 강제

npm install --save-dev @commitlint/cli @commitlint/config-conventional
echo "module.exports = { extends: ['@commitlint/config-conventional'] };" > commitlint.config.js

GitHub Actions:

- uses: wagoid/commitlint-github-action@v6

→ PR 의 모든 commit 메시지 자동 검사. 잘못된 형식이면 머지 차단.

한 번 정리

• ▸type + scope + description 표준
• ▸50자 이내 한 줄 + 상세는 body 에
• ▸semantic-release·CHANGELOG 자동화로 보상
• ▸commitlint 로 팀 전체 강제

이 lesson 의 개념을 알면 AI 에게 구체적으로 지시할 수 있습니다. 막연한 "고쳐줘" 가 아니라 어휘를 가진 요청 — 그게 토큰 절약의 출발점입니다.

• ▸"이 SPEC 기반으로 Plan → Tasks → Implement 흐름 만들어줘"
• ▸"AI 에이전트 모드를 안전하게 쓰기 위한 dry-run + 승인 게이트 패턴 알려줘"

왜 이게 토큰을 줄이나

개념을 모를 땐 AI 답변을 받고도 "그게 뭐예요?" 를 다시 물어야 합니다. 그 "다시 물음" 이 토큰을 잡아먹습니다. 개념 한 번 익혀두면 대화가 한 번에 끝납니다.