Claude Code 전문 활용 가이드 — 내장 기능부터 Context Engineering까지

설치된 스킬(oh-my-claudecode, superpowers, octo) 바깥에도 Claude Code 자체의 내장 기능, 외부 AI 도구, 전문 개발 방법론이 있다. 이 문서는 그 세 축을 실무 관점에서 정리한다.

Claude Code 내장 기능 완전 활용

슬래시 커맨드 전체 목록

Claude Code에는 40개 이상의 내장 커맨드가 있다. 자율 개발에 핵심적인 것들을 용도별로 나눈다.

컨텍스트 & 계획

커맨드	설명	활용 시나리오
`/init`	CLAUDE.md 초기화 (가이드 기반)	프로젝트 시작 시 AI 지침서 생성
`/compact [focus]`	컨텍스트 수동 압축 (포커스 지정 가능)	긴 세션에서 핵심만 유지
`/context`	실시간 컨텍스트 사용량 확인	토큰 예산 관리
`/plan`	Plan Mode 전환 (읽기 전용 분석)	코드 작성 전 안전한 탐색

모델 & 실행 제어

커맨드	설명	활용 시나리오
`/model <name>`	모델 전환 (opus, sonnet, haiku)	작업 복잡도에 따른 비용 최적화
`/model config`	사용 가능한 모델 및 비용 확인	비용 계획
`/continue [session-id]`	이전 세션 이어서 작업	장기 프로젝트 연속성
`/resume`	세션 선택 UI (대화형)	여러 세션 중 선택
`/fork-session`	현재 세션 분기 (히스토리 유지)	실험적 작업 분기

권한 & 보안

커맨드	설명	활용 시나리오
`/permissions`	시각적 권한 관리자 열기	권한 규칙 확인/수정
`/add-dir <path>`	추가 디렉토리 접근 권한 부여	다중 프로젝트 작업
`/auto-mode defaults`	자동 모드 기본 규칙 확인	안전 규칙 이해
`/auto-mode critique`	AI가 커스텀 규칙 피드백	규칙 품질 검증

워크플로우 & 분석

커맨드	설명	활용 시나리오
`/review`	자동화된 코드 리뷰	PR 전 품질 점검
`/doctor`	환경/설치 진단	문제 해결
`/cost`	토큰 사용량 및 비용 조회	비용 관리
`/status`	세션 상태 및 리소스 확인	모니터링
`/loop [interval] [cmd]`	반복 실행 (예: `/loop 5m /review`)	지속적 모니터링
`/hooks`	설정된 훅 시각적 브라우저	훅 관리
`/mcp`	MCP 서버 상태 및 비용 확인	MCP 관리

세션 관리

커맨드	설명	활용 시나리오
`/help`	전체 커맨드 목록 표시	기능 발견
`/login` / `/logout`	인증 관리	계정 전환
`/bug`	버그 리포트	문제 신고
`/listen`	파일 감시 모드	변경 감지 자동 반응
`/vim`	Vim 키바인딩 토글	에디터 습관 유지

Hooks 시스템 — 자동화의 핵심

Hooks는 세션의 특정 시점에 자동으로 실행되는 스크립트다. 검증, 알림, 워크플로우 자동화를 여기에 건다.

타입	설명	제어
command	셸 스크립트 실행, JSON 수신	exit 0=성공, exit 2=차단
http	외부 웹훅 POST 호출	HTTP 응답 기반
prompt	Claude 단일 턴 프롬프트 분석	분석 결과 반환
agent	서브에이전트 생성 (검증용)	에이전트 결과 반환

라이프사이클은 세션 시작부터 종료까지 순서대로 이어진다.

SessionStart
  ↓
UserPromptSubmit ─→ PreToolUse ─→ [도구 실행] ─→ PostToolUse
                         ↑                           ↓
                         └──── 각 도구 호출마다 반복 ────┘
  ↓
Stop (Claude 응답 완료)
  ↓
SessionEnd

이벤트는 실행을 막을 수 있는 것과 결과만 관찰하는 것으로 나뉜다. 차단 가능한 이벤트는 다음과 같다.

이벤트	시점	활용
`PreToolUse`	도구 실행 직전	위험한 명령 차단
`PermissionRequest`	권한 요청 시	자동 승인/거부
`UserPromptSubmit`	프롬프트 제출 시	입력 검증
`Stop`	Claude 응답 완료 시	완료 조건 강제 (Ralph 루프)
`PreCompact`	컨텍스트 압축 전	보존할 내용 지정

관찰 전용 이벤트는 실행 후 반응만 한다.

이벤트	시점	활용
`PostToolUse`	도구 성공 후	결과 로깅, 알림
`PostToolUseFailure`	도구 실패 후	오류 추적
`FileChanged`	파일 변경 감지	자동 린트/테스트
`CwdChanged`	작업 디렉토리 변경	컨텍스트 자동 전환

실제 설정은 settings.json에 이벤트별로 훅을 등록하는 방식이다.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "if": "Bash(rm *)",
            "command": ".claude/hooks/block-destructive.sh",
            "timeout": 600,
            "statusMessage": "안전 검사 중..."
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/auto-lint.sh",
            "async": true
          }
        ]
      }
    ],
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/session-summary.sh",
            "async": true
          }
        ]
      }
    ]
  }
}

위험 명령을 잡아내는 훅은 이렇게 생겼다.

#!/bin/bash
# .claude/hooks/block-destructive.sh
COMMAND=$(echo "$CLAUDE_TOOL_INPUT" | jq -r '.command')

if echo "$COMMAND" | grep -qE 'rm -rf|drop table|truncate'; then
  echo "BLOCKED: 파괴적 명령이 감지되었습니다: $COMMAND" >&2
  exit 2  # 차단
fi
exit 0  # 허용

편집 직후 자동 린트를 거는 훅도 비슷한 구조다.

#!/bin/bash
# .claude/hooks/auto-lint.sh
FILE=$(echo "$CLAUDE_TOOL_INPUT" | jq -r '.file_path')
EXTENSION="${FILE##*.}"

case "$EXTENSION" in
  py) ruff check "$FILE" --fix 2>/dev/null ;;
  ts|tsx) npx eslint "$FILE" --fix 2>/dev/null ;;
  go) gofmt -w "$FILE" 2>/dev/null ;;
esac
exit 0

Permission 시스템 — 자율 실행의 전제조건

자율 코딩을 하려면 권한 설정이 먼저다. Shift+Tab으로 전환할 수 있는 모드는 자율성 수위가 다르다.

모드	동작	자율성	적합한 상황
default	첫 사용 시 확인	낮음	일반 개발
acceptEdits	파일 편집 자동 승인	중간	신뢰할 수 있는 저장소
plan	읽기 전용 (편집 불가)	없음	안전한 탐색
auto	배경 안전 검사 후 자동 결정	높음	자율 실행 (연구 프리뷰)
dontAsk	사전 승인된 것만 허용	제한적	잠금 환경
bypassPermissions	전부 자동 승인	최대	컨테이너/VM 전용

자율 실행을 위한 권장 설정은 allow/deny 패턴을 명시적으로 나눈다.

{
  "defaultMode": "acceptEdits",
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(npx *)",
      "Bash(python *)",
      "Bash(pytest *)",
      "Bash(git add *)",
      "Bash(git commit *)",
      "Bash(git status)",
      "Bash(git diff *)",
      "Bash(git log *)",
      "Bash(mkdir *)",
      "Bash(ls *)",
      "Bash(cat *)",
      "Bash(uv *)",
      "Edit(/src/**)",
      "Edit(/tests/**)",
      "Write(/src/**)",
      "Write(/tests/**)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(git push --force *)",
      "Bash(git reset --hard *)",
      "Edit(/.env*)",
      "Edit(/secrets/**)"
    ]
  }
}

패턴 문법은 다음과 같이 매칭된다.

Bash(npm run *)      → npm run test, npm run build 등 매치
Bash(git * main)     → git merge main, git push origin main 매치
Edit(/src/**)        → src/ 하위 모든 파일 편집 허용
Read(~/.config/*)    → 홈 디렉토리 설정 파일 읽기
Read(//etc/hosts)    → 절대 경로 (// 접두사)

우선순위는 Deny > Ask > Allow — 첫 번째 매칭 규칙이 적용된다.

Custom Slash Commands — 나만의 명령어

.claude/commands/ 디렉토리에 Markdown 파일을 추가하면 그대로 커스텀 슬래시 커맨드가 된다.

.claude/commands/           # 프로젝트 커맨드
  ├── deploy-staging.md     # /deploy-staging
  ├── run-tests.md          # /run-tests
  └── setup-db.md           # /setup-db

~/.claude/commands/         # 글로벌 커맨드
  ├── daily-standup.md      # /daily-standup
  └── review-pr.md          # /review-pr

/deploy-staging 예시는 배포 절차를 순서대로 적어두는 식이다.

# Deploy to Staging

1. Run all tests: `pytest --tb=short`
2. If tests pass, build Docker image: `docker build -t app:staging .`
3. Push to registry: `docker push registry.example.com/app:staging`
4. Deploy: `kubectl apply -f k8s/staging/`
5. Wait 30 seconds and verify health: `curl -s https://staging.example.com/health`
6. Report deployment status

$ARGUMENTS를 쓰면 인자를 받는 커맨드도 만들 수 있다.

# Review PR $ARGUMENTS

1. Fetch PR details: `gh pr view $ARGUMENTS --json title,body,files`
2. Read each changed file
3. Check for:
   - Security vulnerabilities (OWASP Top 10)
   - Missing tests
   - Code style violations
   - Performance issues
4. Write review summary

사용은 /review-pr 123처럼 인자를 붙이면 된다.

CLAUDE.md / AGENTS.md — 컨텍스트 엔지니어링

CLAUDE.md는 계층 구조로 로드된다.

~/.claude/CLAUDE.md              # 글로벌 (모든 프로젝트)
./CLAUDE.md                      # 프로젝트 루트 (팀 공유, git 체크인)
./src/CLAUDE.md                  # 디렉토리별 (해당 파일 작업 시 로드)
./src/auth/CLAUDE.md             # 하위 디렉토리별

작업 중인 파일의 경로를 따라 상위 → 하위 순으로 모두 로드된다는 게 로딩 규칙이다.

효과적인 CLAUDE.md는 프로젝트 개요, 셋업, 아키텍처, 컨벤션, 테스트, 압축 지침까지 담는다.

# Project: My API Server

## Overview

FastAPI 기반 REST API 서버. PostgreSQL, Redis 사용.

## Development Setup

source .venv/bin/activate && uv pip install -e ".[dev]"

## Architecture

- src/api/ → FastAPI 라우터 (엔드포인트 정의)
- src/models/ → SQLAlchemy 모델
- src/schemas/ → Pydantic 스키마 (요청/응답)
- src/services/→ 비즈니스 로직
- tests/ → pytest 테스트

## Conventions

- 함수명: snake_case
- 클래스명: PascalCase
- 비동기 함수 필수 (async def)
- 모든 엔드포인트에 Pydantic 스키마 사용
- 에러 응답: {"detail": "message"} 형식

## Testing

pytest --tb=short -q

# 새 기능 추가 시 반드시 테스트 작성

## Compact Instructions

컨텍스트 압축 시 보존할 내용:

- API 엔드포인트 구조
- 인증 플로우 (JWT + Refresh Token)
- DB 마이그레이션 규칙

AGENTS.md는 디렉토리 단위로 서브에이전트에게 줄 지침을 담는다.

# Directory: src/auth/

## Purpose

JWT 기반 인증/인가 모듈

## Key Files

- router.py → /auth/\* 엔드포인트
- service.py → 토큰 생성/검증 로직
- models.py → User, RefreshToken 모델
- schemas.py → LoginRequest, TokenResponse

## AI Agent Instructions

- 비밀번호는 반드시 bcrypt 해시 사용
- 토큰 만료 시간: Access 15분, Refresh 7일
- 모든 엔드포인트에 rate limiting 적용
- 민감한 정보 로깅 금지

## Testing

pytest tests/test_auth.py -v

Memory 시스템 — 세션 간 지식 유지

Memory는 네 가지 타입으로 나뉜다.

타입	용도	예시
user	사용자 역할, 선호도, 지식 수준	"시니어 백엔드 개발자, Go 전문"
feedback	작업 방식 피드백 (무엇을 하고/하지 말 것)	"테스트에서 DB 모킹 금지"
project	프로젝트 진행 상황, 결정, 맥락	"인증 모듈 리팩토링 중, 법적 요구사항"
reference	외부 리소스 위치	"버그 트래킹은 Linear INGEST 프로젝트"

Memory 파일은 front-matter가 붙은 짧은 Markdown이다.

---
name: db-testing-policy
description: 통합 테스트에서 실제 DB 사용 필수
type: feedback
---

테스트에서 데이터베이스를 모킹하지 말 것.

**Why:** 지난 분기에 모킹된 테스트가 통과했지만 프로덕션 마이그레이션이 실패한 사건
**How to apply:** pytest에서 실제 SQLite/PostgreSQL 연결 사용

CLAUDE.md와는 성격이 다르다.

구분	Memory	CLAUDE.md
범위	개인적 학습	팀 공유 지침
지속성	세션 간 유지	영구 (git 체크인)
생성	대화에서 자동 학습	수동 작성
용도	선호도, 피드백, 맥락	아키텍처, 컨벤션, 셋업

Plan Mode — 안전한 분석 모드

# CLI에서 Plan Mode로 시작
claude --mode plan

# 세션 중 전환
/plan

일반 모드와 Plan Mode의 차이는 실행 전 분석 단계를 강제하느냐에 있다.

일반 모드:
  "이 함수 리팩토링해줘" → [바로 코드 수정 시작]

Plan Mode:
  "이 함수 리팩토링해줘" → [분석만 수행]
  → "이 함수는 3가지 책임을 가지고 있습니다..."
  → "리팩토링 계획: 1) 검증 로직 분리 2) DB 접근 분리 3) ..."
  → [사용자 승인 후 실행 모드로 전환]

복잡한 리팩토링 전 영향도 분석, 레거시 코드 이해, 아키텍처 의사결정, 비용이 높은 실수를 방지하고 싶을 때 적합하다.

Git Worktree — 병렬 작업 격리

Git Worktree는 하나의 저장소에서 여러 브랜치를 동시에 체크아웃할 수 있게 한다.

# 기능 A 작업용 워크트리
git worktree add -b feature/auth ../project-auth main
cd ../project-auth
claude  # 독립 세션

# 기능 B 작업용 워크트리 (동시에)
git worktree add -b feature/api ../project-api main
cd ../project-api
claude  # 독립 세션 (A와 충돌 없음)

자율 코딩에서는 세션마다 독립된 파일 시스템을 갖게 하는 데 쓰인다.

┌─ Worktree 1 (feature/auth) ──────┐
│ Claude Session A                  │
│ → 인증 모듈 구현 중                │
│ → 독립된 파일 시스템               │
└───────────────────────────────────┘

┌─ Worktree 2 (feature/api) ───────┐
│ Claude Session B                  │
│ → API 라우터 구현 중               │
│ → Session A와 충돌 없음            │
└───────────────────────────────────┘

┌─ Main Worktree (main) ───────────┐
│ Claude Session C                  │
│ → 코드 리뷰/통합 담당              │
└───────────────────────────────────┘

정리는 git worktree remove로 한다.

git worktree remove ../project-auth
git worktree remove ../project-api

MCP 서버 생태계 — 무한 확장

MCP(Model Context Protocol)는 Claude Code의 능력을 외부 도구와 데이터 소스로 확장한다.

MCP 서버	용도	활용
filesystem	파일 시스템 조작	디렉토리 트리, 파일 검색
github	GitHub API 연동	Issue 생성, PR 관리, 코드 검색
openchrome	브라우저 자동화	웹 앱 테스트, 스크린샷, DOM 조작
exa	의미 기반 웹 검색	문서 검색, 코드 예제 수집
context7	라이브러리 문서 조회	최신 API 문서 실시간 참조
postgres/mysql	데이터베이스 직접 접근	스키마 조회, 쿼리 실행
docker	Docker 컨테이너 관리	빌드, 실행, 로그 확인
kubernetes	K8s 클러스터 관리	파드 상태, 배포 관리
slack	Slack 메시지 전송	배포 알림, 상태 보고
linear	Linear 이슈 관리	이슈 생성/업데이트
sentry	에러 모니터링	프로덕션 에러 조회
playwright	E2E 테스트	브라우저 기반 테스트 자동화

설정은 settings.json의 mcpServers에 등록한다.

// .claude/settings.json
{
  "mcpServers": {
    "github": {
      "type": "node",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "postgres": {
      "type": "node",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "postgresql://user:pass@localhost:5432/mydb"
      }
    },
    "custom-api": {
      "type": "http",
      "url": "http://localhost:3000/mcp"
    }
  }
}

MCP 도구도 일반 권한 규칙처럼 allow/deny로 세밀하게 통제할 수 있다.

{
  "permissions": {
    "allow": [
      "mcp__github__list_issues",
      "mcp__github__create_issue",
      "mcp__context7__*"
    ],
    "deny": ["mcp__github__delete_repo", "mcp__postgres__drop_*"]
  }
}

Claude Code SDK — 커스텀 에이전트 빌드

Claude Code SDK를 쓰면 Claude Code를 프로그래밍 방식으로 제어할 수 있다.

import { ClaudeCode } from "@anthropic-ai/claude-code";

const claude = new ClaudeCode({
  model: "claude-sonnet-4-5",
  mode: "auto",
  cwd: "/path/to/project",
});

// 단순 실행
const result = await claude.run(
  "이 프로젝트의 테스트를 실행하고 결과를 알려줘",
);

// 스트리밍
for await (const event of claude.stream("API 엔드포인트 추가해줘")) {
  if (event.type === "text") console.log(event.text);
  if (event.type === "tool_use") console.log(`Tool: ${event.name}`);
}

CI/CD 파이프라인에 물리면 PR마다 자동 리뷰를 돌릴 수 있다.

# .github/workflows/ai-review.yml
name: AI Code Review
on: [pull_request]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: AI Review
        run: |
          npx claude-code --mode plan \
            --prompt "이 PR의 변경사항을 리뷰하고 보안/성능 이슈를 찾아줘" \
            --output review.md
      - name: Post Review
        uses: actions/github-script@v7
        with:
          script: |
            const review = fs.readFileSync('review.md', 'utf8');
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              body: review
            });

외부 AI 코딩 도구 생태계

Claude Code 바깥에도 전문 개발에 쓸 수 있는 AI 코딩 도구가 많다. 터미널 기반부터 자율 에이전트까지 결이 다르다.

터미널 기반 도구

도구	특징	강점	제한
Claude Code	Anthropic 공식 CLI	에이전트 오케스트레이션, MCP, Hooks	Anthropic 모델만
OpenAI Codex CLI	OpenAI 공식 CLI	GPT 모델, 빠른 응답	플러그인 생태계 작음
Google Gemini CLI	Google 공식 CLI	긴 컨텍스트(1M+), 무료 티어	에이전트 기능 제한
Aider	오픈소스 페어 프로그래밍	다중 모델 지원, Git 통합	자율 실행 기능 약함
Amazon Q Developer	AWS 통합 CLI	AWS 서비스 전문, 보안 스캔	AWS 생태계 편향

IDE 기반 도구

도구	IDE	특징	자율 실행
GitHub Copilot	VS Code, JetBrains, Vim	Agent mode, Workspace	중간 (Agent mode)
Cursor	전용 IDE (VS Code 포크)	Composer, .cursorrules	높음 (Composer)
Windsurf	전용 IDE	Cascade, Flows	높음 (Cascade)
Cline	VS Code 확장	다중 모델, 자율 모드	높음
Continue.dev	VS Code, JetBrains	오픈소스, 커스터마이징	중간

웹 기반 도구

도구	특징	적합한 상황
Bolt.new	브라우저에서 풀스택 앱 생성	빠른 프로토타이핑
v0 (Vercel)	UI 컴포넌트 생성	React/Next.js 프론트엔드
Lovable	대화형 앱 빌더	비개발자의 MVP 제작
Replit Agent	클라우드 IDE + AI 에이전트	배포까지 원스톱

자율 에이전트 도구

도구	특징	수준
Devin (Cognition AI)	완전 자율 소프트웨어 엔지니어	가장 높은 자율성
SWE-Agent	오픈소스 자율 버그 수정	연구/벤치마크
OpenHands	오픈소스 AI 개발자	오픈소스 대안
Factory AI	엔터프라이즈 AI 코딩	기업용

여러 도구를 동시에 굴릴 때는 역할을 나누는 편이 낫다.

┌─────────────────────────────────────────────────────────────┐
│                  Multi-Model 워크플로우                       │
│                                                             │
│  Claude Code (Opus)  ──→ 아키텍처 설계, 복잡한 로직            │
│  Codex CLI           ──→ 빠른 구현, 단순 CRUD                 │
│  Gemini CLI          ──→ 긴 컨텍스트 분석, 코드베이스 이해       │
│  Aider (GPT-4o)      ──→ 빠른 반복, 페어 프로그래밍             │
│                                                             │
│  Claude Code가 오케스트레이터 역할:                             │
│  /ccg 로 3개 모델의 응답을 합성하여 최적 결과 도출               │
└─────────────────────────────────────────────────────────────┘

전문 AI 개발 방법론

Vibe Coding (바이브 코딩)

Andrej Karpathy가 2025년 초 제안한 개념으로, AI에게 대략적인 의도("vibe")만 전달하고 구현 세부사항은 AI에게 맡기는 프로그래밍 스타일이다.

핵심 원칙은 네 가지다. 1) 자연어 우선 — 코드 대신 의도를 설명한다. 2) 결과 기반 평가 — 과정이 아닌 결과물로 판단한다. 3) 반복적 정제 — 한 번에 완벽하지 않아도 반복으로 개선한다. 4) AI 주도 — 구현 결정은 AI에게 위임한다.

어디에 쓸지는 상황을 가린다.

적합	부적합
프로토타입, MVP	미션 크리티컬 시스템
개인 프로젝트	금융/의료 소프트웨어
빠른 실험	성능이 중요한 시스템
학습/탐색	보안이 중요한 시스템
내부 도구	대규모 팀 협업

흔히 빠지는 안티패턴은 네 가지다. Blind Trust(AI 출력을 검증 없이 사용), Prompt Dumping(거대한 프롬프트를 한 번에 전달), No Versioning(Git 없이 AI와 작업), Context Neglect(CLAUDE.md 없이 매번 처음부터 설명).

Spec-Driven AI Development (명세 기반 AI 개발)

AI가 가장 잘 작동하는 방식은 명확한 명세서를 기반으로 구현하는 것이다. 좋은 AI 명세서는 목표, API 엔드포인트, 비즈니스 규칙, 에러 처리, 수락 기준을 모두 담는다.

## 기능: 사용자 인증

### 목표

JWT 기반 사용자 인증 시스템 구현

### API 엔드포인트

| Method | Path           | 요청                    | 응답                          | 상태 코드 |
| ------ | -------------- | ----------------------- | ----------------------------- | --------- |
| POST   | /auth/register | {email, password, name} | {id, email, name}             | 201       |
| POST   | /auth/login    | {email, password}       | {access_token, refresh_token} | 200       |
| POST   | /auth/refresh  | {refresh_token}         | {access_token}                | 200       |
| GET    | /auth/me       | Header: Bearer token    | {id, email, name}             | 200       |

### 비즈니스 규칙

1. 비밀번호: 최소 8자, 대소문자+숫자+특수문자
2. Access Token: 15분 만료
3. Refresh Token: 7일 만료, 1회 사용 후 재발급
4. 동일 이메일 중복 가입 불가

### 에러 처리

| 상황            | 상태 코드 | 응답                                   |
| --------------- | --------- | --------------------------------------- |
| 중복 이메일     | 409       | {"detail": "Email already registered"} |
| 잘못된 비밀번호 | 401       | {"detail": "Invalid credentials"}      |
| 만료된 토큰     | 401       | {"detail": "Token expired"}            |

### 수락 기준 (Acceptance Criteria)

- [ ] POST /auth/register로 새 사용자 생성 가능
- [ ] 중복 이메일 시 409 반환
- [ ] POST /auth/login으로 JWT 토큰 발급
- [ ] 잘못된 비밀번호 시 401 반환
- [ ] Access Token으로 GET /auth/me 접근 가능
- [ ] 만료된 토큰 시 401 반환
- [ ] Refresh Token으로 새 Access Token 발급 가능
- [ ] 모든 비밀번호 bcrypt 해시로 저장
- [ ] pytest 테스트 100% 통과

이 명세서를 그대로 AI에 전달하면 된다.

/autopilot 위 명세서대로 FastAPI로 구현해줘
# 또는
/ralph 위 명세서의 수락 기준을 모두 통과시켜줘

Plan-Execute-Verify (PEV) 루프

AI 자율 개발의 가장 기본적이고 효과적인 패턴이다.

┌──────────────────────────────────────────────────────┐
│                   PEV 루프                            │
│                                                      │
│  ┌─────────┐    ┌─────────┐    ┌─────────┐          │
│  │  Plan   │───→│ Execute │───→│ Verify  │          │
│  │ (계획)   │    │ (실행)   │    │ (검증)   │          │
│  └─────────┘    └─────────┘    └────┬────┘          │
│       ↑                             │               │
│       │          실패 시              │               │
│       └─────────────────────────────┘               │
│                                                      │
│  Plan:   무엇을 할지 분석하고 계획                      │
│  Execute: 계획대로 코드 작성                           │
│  Verify:  테스트 실행, 빌드 확인, 수동 검증              │
└──────────────────────────────────────────────────────┘

Claude Code에서는 Plan Mode → 코드 작성 → /verify(또는 직접 테스트 실행) 순서로 구현된다.

# Plan
/plan  # Plan Mode에서 분석
# → 계획 확인 후 실행 모드로 전환

# Execute
# Claude가 코드 작성

# Verify
/verify  # 또는 직접 pytest, npm test 등 실행

Writer-Reviewer 분리 원칙

AI 자율 개발에서 가장 중요한 원칙 하나를 꼽으라면 작성자와 검증자를 분리하는 것이다.

┌────────────┐                    ┌────────────┐
│   Writer   │  ←── 다른 에이전트 ──→│  Reviewer  │
│  (작성자)   │                    │  (검증자)   │
│            │                    │            │
│ • 코드 작성 │                    │ • 코드 리뷰  │
│ • 테스트 작성│                    │ • 보안 감사  │
│ • 구현 결정 │                    │ • 성능 분석  │
└────────────┘                    └────────────┘
       │                                │
       └────────── 절대 같은 ──────────────┘
                  에이전트 아님

같은 AI가 작성하고 리뷰하면 자기 확인 편향이 생긴다. 다른 에이전트나 모델이 리뷰해야 놓친 문제를 발견할 가능성이 생긴다. Claude Code에서는 Autopilot Phase 4의 3명 독립 검증자(Architect + Security + Code-reviewer), Ralph의 별도 리뷰어 에이전트, /ccg의 3개 모델 교차 검증이 이 원칙을 구현한다.

Incremental vs Batch Development

방식	설명	적합한 상황
Incremental	작은 단위로 구현 → 검증 → 다음 단위	복잡한 로직, 의존성 높은 코드
Batch	전체를 한 번에 구현 → 한 번에 검증	독립적 모듈, 보일러플레이트

# Incremental (Ralph 방식)
/ralph 인증 → 사용자 → 게시글 → 댓글 순서로 하나씩 구현하고 검증

# Batch (Ultrawork 방식)
/ultrawork 인증, 사용자, 게시글, 댓글 모듈을 동시에 구현

Context Engineering — AI 시대의 핵심 역량

Context Engineering은 AI에게 적절한 맥락을 적절한 시점에 제공하는 기술이다.

컨텍스트는 네 계층으로 나뉜다.

Level 1: 시스템 컨텍스트 (변경 불가)
  └─ 모델 학습 데이터, 시스템 프롬프트

Level 2: 영구 컨텍스트 (세션 시작 시 로드)
  ├─ CLAUDE.md (프로젝트 지침)
  ├─ AGENTS.md (디렉토리별 지침)
  └─ Memory (학습된 선호도)

Level 3: 세션 컨텍스트 (대화 중 축적)
  ├─ 대화 히스토리
  ├─ 읽은 파일 내용
  └─ 도구 실행 결과

Level 4: 즉시 컨텍스트 (현재 프롬프트)
  └─ 사용자 메시지 + 첨부 파일

예산 관리는 사용량 확인과 수동 압축을 오가며 한다.

# 현재 사용량 확인
/context

# 수동 압축 (포커스 지정)
/compact 인증 모듈 구현에 집중. API 엔드포인트 구조와 에러 처리 보존.

# Compact Instructions (CLAUDE.md에 추가)
## Compact Instructions
압축 시 보존: 인증 플로우, API 구조, DB 스키마
압축 시 제거: 디버깅 히스토리, 이전 시도 실패 내역

최적화 전략은 다섯 가지로 정리된다.

전략	방법	효과
사전 로딩	CLAUDE.md에 핵심 정보	매 세션 자동 로드
지연 로딩	필요할 때만 파일 읽기	토큰 절약
위임	서브에이전트로 격리	메인 컨텍스트 보호
압축	/compact로 핵심만 유지	긴 세션 지속 가능
분할	기능별 세션 분리	집중도 향상

플랫폼마다 컨텍스트 파일 이름과 형식이 다르므로, 여러 도구를 섞어 쓴다면 핵심 내용을 공통으로 유지하고 플랫폼별로 변환하는 게 낫다.

플랫폼	파일명	형식
Claude Code	`CLAUDE.md`	Markdown
Cursor	`.cursorrules`	텍스트
GitHub Copilot	`.github/copilot-instructions.md`	Markdown
Windsurf	`.windsurfrules`	텍스트
Cline	`.clinerules`	텍스트
Aider	`.aider.conf.yml`	YAML

프롬프트 엔지니어링 for Code

효과적인 코드 생성 프롬프트 패턴

제약 명시는 언어·프레임워크·DB·테스트 도구까지 조건을 나열하는 방식이다.

구현해줘: 사용자 서비스
- 언어: Python 3.12+
- 프레임워크: FastAPI
- DB: SQLAlchemy + PostgreSQL
- 검증: Pydantic v2
- 테스트: pytest + httpx
- 제약: async 필수, 타입 힌트 필수, docstring 불필요

예시 기반은 기존 코드 패턴을 보여주고 같은 스타일로 확장을 요청하는 방식이다.

아래 패턴과 동일한 스타일로 Order 서비스를 구현해줘:

# 기존 User 서비스 패턴 (참고용):
class UserService:
    def __init__(self, db: AsyncSession):
        self.db = db

    async def create(self, data: UserCreate) -> User:
        user = User(**data.model_dump())
        self.db.add(user)
        await self.db.commit()
        return user

하지 말 것 명시는 흔히 나오는 나쁜 습관을 미리 차단하는 방식이다.

REST API 구현해줘.
하지 말 것:
- ORM 없이 raw SQL 사용하지 말 것
- print() 디버깅 하지 말 것
- 하드코딩된 설정값 사용하지 말 것
- 주석으로 코드 설명하지 말 것 (코드가 자체 문서화되어야 함)
- try/except로 모든 예외를 삼키지 말 것

반복 정제는 뼈대부터 시작해 단계적으로 살을 붙이는 방식이다.

# 1차: 뼈대
/autopilot 기본 CRUD API 뼈대만 만들어줘

# 2차: 살 붙이기
인증 미들웨어를 추가하고, 권한 검사를 각 엔드포인트에 적용해줘

# 3차: 테스트
현재 코드에 대한 통합 테스트를 작성해줘

# 4차: 정제
/ai-slop-cleaner

디버깅 프롬프트 패턴

증상, 기대 동작, 실제 동작을 나눠 적으면 AI가 원인을 찾기 쉬워진다.

문제: POST /api/orders 호출 시 500 에러

기대 동작: 201 Created와 주문 ID 반환
실제 동작: 500 Internal Server Error, 로그에 "IntegrityError: NOT NULL constraint"

관련 코드: src/api/orders.py, src/models/order.py
최근 변경: Order 모델에 shipping_address 필드 추가 (NOT NULL)

오류 메시지 자체를 붙이고 발생 맥락을 함께 설명하는 것도 효과적이다.

이 에러를 해결해줘:

TypeError: argument of type 'NoneType' is not iterable
File "src/auth/service.py", line 42, in verify_token
if "admin" in user.roles:

user.roles가 None일 수 있는 경우: 마이그레이션 전 생성된 사용자

Multi-Agent 오케스트레이션 패턴

기본 패턴은 세 가지로 나뉜다.

**Specialist Routing(전문가 라우팅)**은 요청을 분석해 적합한 에이전트로 보낸다.

사용자 요청
    ↓
┌─────────────────────────────────┐
│         Router Agent            │
│   (요청 분석 + 에이전트 선택)      │
└────────┬────────────────────────┘
         │
    ┌────┼────┬────────┐
    ↓    ↓    ↓        ↓
 코드  테스트  보안    문서
 작성  작성   검토    작성

**Pipeline(파이프라인)**은 분석부터 배포까지 순서대로 넘긴다.

분석 → 설계 → 구현 → 테스트 → 리뷰 → 배포
  │      │      │      │      │      │
analyst  architect  executor  tester  reviewer  deployer

**Fan-Out / Fan-In(병렬 수렴)**은 독립 모듈을 분배했다가 결과를 다시 합친다.

                ┌→ Agent A (모듈 1) ─┐
요청 ──→ 분배 ──┤→ Agent B (모듈 2) ──┤──→ 합성 ──→ 결과
                └→ Agent C (모듈 3) ─┘

Claude Code에서는 이 세 패턴이 각각 다른 명령으로 매핑된다.

# Specialist Routing
/team 1:executor,1:test-engineer,1:code-reviewer "인증 모듈 구현"

# Pipeline (자동)
/autopilot  # 내부적으로 Phase 0→5 파이프라인

# Fan-Out / Fan-In
/ultrawork "독립 모듈 3개 동시 구현"

AI-Native 테스팅 전략

AI TDD (Test-Driven Development with AI)

전통적 TDD와 AI TDD는 누가 구현을 맡느냐만 다르다.

전통적 TDD:
  개발자가 테스트 작성 → 개발자가 구현 → 테스트 통과

AI TDD:
  개발자가 테스트 작성 → AI가 구현 → 테스트 통과
  또는
  AI가 테스트 작성 → AI가 구현 → 자동 검증 루프

실전에서는 세 가지 방법 중 하나를 고른다.

# 방법 1: 사람이 테스트, AI가 구현
# tests/test_auth.py를 직접 작성한 후:
/ralph tests/test_auth.py의 모든 테스트가 통과하도록 구현해줘

# 방법 2: AI가 전부 (TDD 모드)
/autopilot TDD로 인증 모듈 구현. 테스트 먼저 작성 후 구현.

# 방법 3: superpowers TDD 스킬
# (자동 트리거: 기능 구현 시)

테스트 전략 매트릭스

테스트 유형	AI 역할	도구
단위 테스트	작성 + 실행	pytest, jest
통합 테스트	작성 + 실행	pytest + httpx
E2E 테스트	작성 + 실행	Playwright MCP
속성 기반 테스트	작성	Hypothesis, fast-check
뮤테이션 테스트	분석	mutmut, Stryker
부하 테스트	스크립트 생성	k6, Locust

AI 코드의 테스트 우선순위

해피 패스는 AI가 가장 잘하는 영역이라 오히려 우선순위가 낮다. AI가 잘못 이해하거나 놓치기 쉬운 영역부터 순서를 매긴다.

1순위: 비즈니스 로직 (AI가 잘못 이해했을 가능성 높음)
2순위: 경계값 / 에러 케이스 (AI가 놓치기 쉬움)
3순위: 인증/권한 (보안 취약점)
4순위: 데이터 무결성 (DB 제약조건)
5순위: 해피 패스 (AI가 가장 잘하는 영역)

안전장치와 가드레일

방어 계층은 다섯 겹으로 쌓는다.

Layer 1: Permission System
  └─ 위험한 명령 사전 차단

Layer 2: Hooks
  └─ 실행 전/후 자동 검증

Layer 3: Git
  └─ 모든 변경 추적, 롤백 가능

Layer 4: Worktree
  └─ 실험적 작업 격리

Layer 5: Review
  └─ AI 작성 → 별도 AI/인간 리뷰

롤백은 Claude Code 내장 Undo부터 Git 명령, Worktree 제거까지 여러 단계로 준비해둔다.

# Claude Code 내장 Undo
Esc Esc  # 이전 체크포인트로 되돌리기

# Git 기반 롤백
git stash          # 변경사항 임시 저장
git checkout .     # 변경 취소
git revert HEAD    # 마지막 커밋 되돌리기

# Worktree 기반 격리
git worktree remove ../experiment  # 실험 워크트리 제거

AI 코드 보안 체크리스트는 배포 전에 항목별로 확인한다.

□ SQL 인젝션: ORM 사용, raw SQL에 파라미터 바인딩
□ XSS: 사용자 입력 이스케이프
□ CSRF: 토큰 검증
□ 인증 우회: 모든 엔드포인트에 인증 미들웨어
□ 민감 정보 노출: .env 파일, 로그에 비밀번호/토큰 없음
□ 의존성 취약점: npm audit / pip-audit
□ 하드코딩된 시크릿: 환경변수 사용
□ 과도한 권한: 최소 권한 원칙

실전 통합 워크플로우

혼자 개발할 때는 최대 자율성을 노린다.

# 환경 설정
/init                          # CLAUDE.md 생성
# Permission: acceptEdits 모드로 설정

# 개발 루프
/deep-interview <아이디어>      # 요구사항 정제
/ralplan <명세>                 # 계획 수립 → 승인
# → autopilot 자동 실행          # 구현 + 테스트 + 검증
/ai-slop-cleaner               # 코드 정제
# → 커밋

팀 개발은 표준화된 프로세스로 간다.

# 팀 설정 (한 번)
CLAUDE.md에 팀 컨벤션 기록 (git 체크인)
AGENTS.md에 디렉토리별 규칙 기록
.claude/commands/에 팀 커스텀 커맨드 추가
.claude/hooks/에 자동 검증 훅 설정

# 개발 플로우
git worktree add -b feature/xxx ../feature-xxx
cd ../feature-xxx
claude
/autopilot <기능 요구사항>
# → 자동 구현 + 테스트
/review                        # AI 코드 리뷰
# → PR 생성

외부 도구를 연동하는 하이브리드 워크플로우도 가능하다.

# Claude Code + 외부 도구 조합
# 1. Gemini CLI로 대규모 코드베이스 분석 (긴 컨텍스트)
gemini "이 프로젝트의 전체 아키텍처를 분석해줘"

# 2. Claude Code로 구현
/autopilot Gemini 분석 결과 기반으로 리팩토링 구현

# 3. Aider로 빠른 수정
aider --model gpt-4o "이 함수의 성능 최적화"

# 4. Claude Code로 최종 검증
/verify
/review

CI/CD에 물리면 품질 관리 자체를 자동화할 수 있다.

# .github/workflows/ai-quality.yml
name: AI Quality Gate
on: [pull_request]

jobs:
  ai-review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: AI Code Review
        run: claude --mode plan --print "이 PR의 변경사항을 리뷰해줘"
      - name: AI Security Scan
        run: claude --mode plan --print "보안 취약점을 스캔해줘"
      - name: AI Test Coverage
        run: claude --mode plan --print "테스트 커버리지 분석해줘"

빠른 참조 카드

키보드 단축키

단축키	동작
`Shift+Tab`	Permission 모드 순환
`Esc Esc`	이전 체크포인트로 되돌리기
`Ctrl+C`	Claude 중단
`Ctrl+L`	화면 지우기
`Tab`	명령어 자동 완성
`/`	커맨드 메뉴 열기

모델 선택 가이드

작업	추천 모델	이유
파일 탐색, 간단한 질문	Haiku	빠르고 저렴
일반 구현, 테스트 작성	Sonnet	균형 잡힌 성능
아키텍처 설계, 보안 감사	Opus	최고 정확도

비용 최적화는 작업 성격에 맞춰 모델을 바꿔가며 쓰는 것으로 시작한다.

# 탐색은 Haiku
/model haiku
"이 프로젝트 구조를 설명해줘"

# 구현은 Sonnet
/model sonnet
"API 엔드포인트 구현해줘"

# 검증은 Opus
/model opus
"이 인증 플로우에 보안 취약점이 있는지 분석해줘"