Claude Code 전문가처럼 쓰기 — 자동완성이 아니라 에이전트를 다루는 법

대부분의 사람은 Claude Code를 — 더 똑똑한 자동완성처럼 씁니다. 질문 하나 던지고, 나온 코드를 복붙하고, 안 되면 또 물어보고. 그렇게 쓰면 — 딱 그 정도 결과가 나옵니다.

전문가는 다릅니다. 그들은 Claude Code를 에이전트로 다룹니다 — 파일을 직접 읽고, 고치고, 명령을 실행하고, 결과를 보고 스스로 고쳐나가는 존재로. 그리고 그 차이는 — 놀랍게도 "프롬프트를 잘 쓰는 법" 같은 게 아닙니다.

좋은 소식은 — 전문가의 사용법은 기술 몇 개로 정리됩니다. 나쁜 소식은 — 그걸 모르면 매번 같은 자리에서 막힙니다. 큰 작업을 시키면 엉뚱한 걸 고치고, 컨텍스트가 꼬이고, 결국 "직접 하는 게 빠르겠다"로 돌아갑니다.

이 글은 Claude Code를 — 장난감이 아니라 도구로 쓰는 법입니다. 멘탈 모델 하나 잡고, 그 위에 실전 기술 열 개를 얹습니다.

멘탈 모델 — 당신이 조종하는 건 세 가지

Claude Code는 결국 — 루프 안에서 도는 에이전트입니다. 받은 목표를 향해 컨텍스트를 읽고 → 행동(파일 수정, 명령 실행)하고 → 결과를 보고 → 다시 판단하고. 이걸 끝날 때까지 반복합니다.

당신이 조종할 수 있는 건 — 딱 세 가지입니다.

[컨텍스트] ──→ [에이전트 루프] ──→ [피드백]
 무엇을 아는가      도구로 행동       결과를 어떻게 보는가
  (Context)         (Tools)           (Feedback)

• 컨텍스트(Context) — Claude가 지금 "아는" 것. 당신의 지시, 열어본 파일, CLAUDE.md, 대화 히스토리. 모델이 똑똑해도 — 모르는 건 못 합니다.
• 도구와 권한(Tools) — Claude가 "할 수 있는" 것. 파일 읽기/쓰기, 셸 명령, 검색, 서브에이전트. 어디까지 허용할지는 당신이 정합니다.
• 피드백 루프(Feedback) — Claude가 자기 일이 맞는지 "확인하는" 법. 테스트, 타입 체크, 빌드, 린트. 이게 없으면 — 그럴듯한 거짓말을 합니다.

전문가가 하는 거의 모든 일은 — 이 셋을 튜닝하는 것입니다. "프롬프트를 어떻게 쓰지?"가 아니라 — "이 작업에 필요한 컨텍스트를 어떻게 넣고, 어떤 권한을 주고, 결과를 어떻게 검증하게 만들까?" 이 그림 하나만 머리에 있으면 — 아래 기술들이 전부 같은 이야기의 변주라는 게 보입니다.

1. CLAUDE.md — 가장 중요한 파일 하나

Claude Code를 켜고 가장 먼저 할 일 — 단 하나만 고른다면 CLAUDE.md입니다.

CLAUDE.md는 — 세션을 시작할 때마다 자동으로 읽히는 프로젝트 메모입니다. 빌드/테스트 명령, 코딩 컨벤션, 디렉토리 구조, 하지 말아야 할 것들을 적어두면 — 매번 설명할 필요가 없어집니다.

/init     # 코드베이스를 훑어서 CLAUDE.md 초안을 만들어줌

좋은 CLAUDE.md에 들어가는 것:

## 명령
- 빌드: `npm run build`
- 테스트: `npm test`, 단일 파일: `npm test -- path/to/file`
- 린트: `npm run lint` (커밋 전 필수)
 
## 컨벤션
- 기존 객체를 수정하지 말 것 — 항상 새 객체 반환
- 파일은 작게: 200~400줄, 800줄 최대
- console.log 금지 — 로거 사용
 
## 구조
- src/lib — 순수 로직, React 의존성 없음
- src/components — UI만

계층이 있습니다 — 셋 다 합쳐서 읽힙니다:

• ~/.claude/CLAUDE.md — 모든 프로젝트 공통 (내 개인 취향)
• <프로젝트>/CLAUDE.md — 이 프로젝트 (팀 공유, git에 커밋)
• <하위폴더>/CLAUDE.md — 그 폴더에 들어갈 때만

대화 중에 새 규칙이 생기면 — #로 바로 메모에 추가할 수 있습니다.

# 마이그레이션은 항상 supabase/migrations 아래에 둘 것

그러면 Claude가 어디에 저장할지 묻고 — CLAUDE.md에 박아둡니다.

2. 컨텍스트를 의도적으로 비워라 — /clear와 /compact

Claude Code를 잘 못 쓰는 가장 흔한 이유 — 하나의 세션에서 모든 걸 하려는 것입니다.

긴 대화는 컨텍스트 창을 채웁니다. 로그인 만들다가, 버그 잡다가, 리팩토링하다가, CSS 고치다가... 이러면 Claude의 컨텍스트엔 서로 관련 없는 잡동사니가 가득 찹니다. 그러면 — 옛날에 했던 엉뚱한 결정을 끌고 오고, 응답이 느려지고, 비싸집니다.

규칙: 한 작업, 한 세션. 작업이 끝나면 비웁니다.

/clear      # 컨텍스트를 완전히 비움. 새 작업의 시작.
/compact    # 대화를 요약해서 압축 (한 작업이 길어질 때 숨 돌리기)

/clear는 — 새 작업을 시작할 때. 이전 작업의 맥락이 다음 작업에 도움이 안 되면 미련 없이 비웁니다.

/compact는 — 한 작업이 길어져 컨텍스트가 꽉 차가는데 맥락은 유지하고 싶을 때. 대화를 요약본으로 압축합니다.

3. Plan 모드 — 코드를 건드리기 전에 계획부터

작은 수정이면 그냥 시키면 됩니다. 하지만 — 여러 파일을 건드리거나, 구조를 바꾸거나, "어떻게 할지" 자체가 불확실한 작업이라면 — 먼저 계획부터 시켜야 합니다.

Plan 모드는 — Claude가 코드를 한 줄도 건드리지 않고 무엇을 어떻게 할지 계획만 세우게 합니다. 읽기는 하되, 쓰지는 않습니다.

Shift + Tab    # 모드 순환: 보통 → 자동 수락 → Plan 모드

Plan 모드에서 Claude는 코드베이스를 조사하고, 접근 방법을 제안하고, 당신의 승인을 기다립니다. 당신은 그 계획을 읽고 — 방향이 틀렸으면 바로잡습니다. 잘못된 방향으로 200줄을 짠 다음 되돌리는 것보다 — 계획 단계에서 한 문장 고치는 게 100배 쌉니다.

쓰는 흐름:

1. Shift+Tab으로 Plan 모드 진입
2. 작업을 설명 — "결제 모듈을 Stripe에서 Toss로 바꿔줘"
3. Claude가 계획 제시 — 영향받는 파일, 순서, 위험 요소
4. 계획을 검토하고 — 승인하거나 수정 요청
5. 승인하면 그때 코드를 짬

4. 권한을 설계하라 — 자동 수락과 허용 목록

기본적으로 Claude Code는 — 파일을 고치거나 명령을 실행하기 전에 매번 물어봅니다. 안전하지만 — 신뢰가 쌓인 작업에선 느립니다. 두 가지 손잡이가 있습니다.

자동 수락 모드 — 매번 묻지 않고 알아서 진행:

Shift + Tab    # 자동 수락(auto-accept) 토글

신뢰할 수 있는, 명확한 작업일 때만 켜세요. 탐색적이거나 위험한 작업에선 — 끄고 하나씩 확인.

영구 허용 목록 — 자주 쓰는 안전한 명령은 settings.json에 등록해두면 매번 안 묻습니다:

// .claude/settings.json (프로젝트) 또는 ~/.claude/settings.json (전역)
{
  "permissions": {
    "allow": [
      "Bash(npm run test:*)",
      "Bash(npm run lint)",
      "Bash(git status)",
      "Edit",
      "Read"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Read(./.env)"
    ]
  }
}

이러면 — 테스트와 린트는 묻지 않고 돌리되, .env는 절대 못 읽고, 위험한 삭제는 막힙니다.

5. 검증 루프를 쥐여줘라 — 테스트가 곧 진실

이 글에서 단 하나만 가져간다면 — 이걸 가져가세요.

Claude는 — 자기가 짠 코드가 맞는지 확인할 방법이 있으면, 스스로 고칩니다. 없으면 — 그럴듯해 보이는 코드를 내놓고 "다 됐습니다"라고 합니다. 차이를 만드는 건 모델이 아니라 — 피드백 루프입니다.

가장 강력한 피드백은 테스트입니다.

"이 함수 고치기 전에 — 실패하는 테스트부터 작성해줘.
 그다음 테스트를 통과시키고, npm test로 초록불 확인해줘."

이렇게 시키면 Claude는 — 테스트를 짜고(RED) → 구현하고 → 테스트를 돌리고 → 실패하면 스스로 고치고 → 통과할 때까지 반복합니다. 당신이 끼어들 필요가 없습니다. 검증 가능한 목표를 주면, 에이전트는 자가 수정합니다.

테스트가 없는 작업이라도 — 피드백은 줄 수 있습니다:

"고친 다음 — npx tsc --noEmit 으로 타입 에러 없는지,
 npm run build 로 빌드되는지 확인하고 끝내줘."

UI 작업이면 — 스크린샷을 붙여넣으세요. "이렇게 보여야 한다"는 이미지 한 장이 — 문단 열 개보다 강력한 피드백입니다.

6. 서브에이전트 — 병렬로, 그리고 컨텍스트를 격리해서

Claude Code는 — 다른 Claude에게 일을 시킬 수 있습니다. 이걸 서브에이전트라고 합니다. 쓰는 이유는 두 가지.

1. 병렬 처리 — 서로 독립적인 일은 동시에:

"3개 영역을 병렬로 점검해줘:
 1) 인증 모듈 보안 리뷰
 2) 캐시 레이어 성능
 3) 유틸 함수 타입 점검"

2. 컨텍스트 격리 — 이게 더 중요합니다. "이 기능이 어디서 구현됐는지 코드베이스 전체를 뒤져줘" 같은 작업은 파일을 수십 개 읽습니다. 그걸 메인 세션에서 하면 — 컨텍스트가 잡동사니로 가득 찹니다. 서브에이전트에게 시키면 — 그 탐색은 서브에이전트의 컨텍스트에서 벌어지고, 메인에는 결론만 돌아옵니다.

자주 쓰는 역할은 — 커스텀 에이전트로 저장해두면 됩니다:

<!-- .claude/agents/code-reviewer.md -->
---
name: code-reviewer
description: 코드 작성/수정 직후 품질·보안 리뷰. 적극적으로 사용.
tools: Read, Grep, Glob, Bash
model: sonnet
---
 
당신은 코드 리뷰 전문가입니다. 변경된 코드를 보안, 가독성,
에러 처리 관점에서 점검하고 — CRITICAL / HIGH / MEDIUM 으로
분류해 보고하세요.

이러면 — "code-reviewer로 방금 코드 리뷰해줘" 한마디로 호출됩니다.

7. 반복 작업은 슬래시 명령으로

같은 지시를 매번 길게 타이핑하고 있다면 — 그건 슬래시 명령으로 만들 신호입니다.

.claude/commands/ 아래에 마크다운 파일을 두면 — 그게 곧 /명령이 됩니다.

<!-- .claude/commands/fix-issue.md -->
GitHub 이슈 #$ARGUMENTS 를 처리해줘:
1. `gh issue view $ARGUMENTS` 로 내용 파악
2. 관련 코드 찾기
3. 실패 테스트 작성 → 수정 → 테스트 통과
4. 커밋 메시지 초안 작성

이제 — /fix-issue 42 한 줄이면 위 절차가 통째로 실행됩니다. $ARGUMENTS 자리에 42가 들어갑니다.

내장 명령도 알아두면 좋습니다:

/clear      컨텍스트 비우기
/compact    대화 압축
/init       CLAUDE.md 생성
/review     코드 리뷰
/model      모델 변경
/agents     서브에이전트 관리

8. 훅(Hooks) — 부르지 않아도 도는 가드레일

슬래시 명령이 "내가 부를 때 도는 것"이라면 — 훅은 **"부르지 않아도 자동으로 도는 것"**입니다.

훅은 특정 시점에 셸 명령을 자동 실행합니다. 가장 흔한 용도는 — 파일을 고칠 때마다 자동 포맷:

// .claude/settings.json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write \"$CLAUDE_FILE_PATHS\""
          }
        ]
      }
    ]
  }
}

이제 — Claude가 파일을 고칠 때마다 prettier가 자동으로 돕니다. "포맷 맞춰줘"라고 부탁할 필요가 없습니다.

훅이 강력한 이유 — 결정론적이기 때문입니다. "린트해줘"라고 부탁하면 Claude가 까먹을 수 있지만, 훅은 코드가 무조건 실행됩니다. 부탁이 아니라 규칙.

주요 시점:

• PreToolUse — 도구 실행 전 (위험한 명령 차단)
• PostToolUse — 도구 실행 후 (포맷, 린트, 타입 체크)
• Stop — 세션 끝날 때 (최종 점검)

9. MCP — 바깥 세계를 연결한다

지금까지는 — Claude가 파일과 셸 안에서 노는 이야기였습니다. MCP(Model Context Protocol)는 그 바깥 세계를 연결합니다.

MCP 서버를 붙이면 — Claude가 데이터베이스를 직접 쿼리하고, 이슈 트래커를 읽고, 디자인 파일을 보고, 브라우저를 조종할 수 있습니다.

claude mcp add --transport http context7 https://...   # 라이브러리 최신 문서
claude mcp list                                         # 붙은 서버 목록

자주 쓰는 조합:

• 문서 MCP (Context7 등) — 라이브러리 최신 API를 환각 없이
• DB MCP — 스키마 보고, 쿼리 돌리고
• 브라우저 MCP (Playwright 등) — 실제로 페이지를 열어 UI 확인
• 이슈/지라/노션 MCP — 작업 컨텍스트를 직접 읽기

핵심은 — 검증과 컨텍스트의 확장입니다. 브라우저 MCP가 있으면 — Claude가 자기가 만든 화면을 직접 열어보고 고칠 수 있습니다. 또 하나의 피드백 루프죠.

10. 모델과 사고 시간 — 비싼 머리를 언제 쓸까

마지막 손잡이 — 머리의 크기와 생각의 깊이.

/model    # Opus / Sonnet / Haiku 전환

• Opus — 가장 깊은 추론. 복잡한 아키텍처 결정, 까다로운 디버깅, 큰 리팩토링 설계.
• Sonnet — 대부분의 코딩 작업. 기본값으로 두기 좋음.
• Haiku — 빠르고 쌈. 단순 수정, 반복 작업, 자주 호출되는 서브에이전트.

비싼 머리를 항상 쓸 필요는 없습니다 — 작업 난이도에 맞춰 고르는 게 프로의 비용 감각입니다.

생각의 깊이도 조절됩니다. 어려운 문제 앞에서 — 키워드 하나로 사고 시간을 늘립니다:

think          조금 더 생각
think hard     더
ultrathink     최대한 깊이

"이 동시성 버그를 ultrathink로 분석해줘 —
 경쟁 조건이 어디서 나는지 추적하고 고쳐줘."

복잡한 추론이 필요한 순간에만 쓰세요. 단순 작업에 ultrathink는 — 돈과 시간 낭비입니다.

하루 워크플로우 — 한 페이지로

전문가의 하루는 — 결국 이 흐름의 반복입니다:

# 프로젝트 셋업 (한 번만)
/init                          # CLAUDE.md 생성 → 손으로 다듬기
# .claude/settings.json 에 권한 + 포맷 훅 설정
 
# 새 작업 시작
/clear                         # 깨끗한 컨텍스트
Shift+Tab → Plan 모드           # 큰 작업이면 계획부터
# "결제 모듈 리팩토링 계획 세워줘 — 먼저 보여주고 승인받아"
 
# 계획 승인 후 — 검증 루프와 함께 실행
# "실패 테스트부터 → 구현 → npm test 초록불까지 스스로 반복해줘"
 
# 탐색이 필요하면 서브에이전트로 격리
# "이 패턴이 어디 쓰이는지 서브에이전트로 찾아서 결론만 줘"
 
# 마무리
/review                        # 또는 code-reviewer 에이전트
git diff                       # 내 눈으로 최종 확인
# 커밋 (PostToolUse 훅이 이미 포맷/린트는 해둠)
 
# 다음 작업 → 다시 /clear

흔한 함정 5가지

1. 모든 걸 한 세션에서 컨텍스트가 잡동사니로 차서 판단이 흐려집니다. → 작업마다 /clear.

2. CLAUDE.md 없이 매번 설명 같은 컨벤션을 매 세션 반복 타이핑. → /init 하고 다듬어서 한 번에.

3. 검증 없이 "다 됐다"를 믿기 테스트도 빌드도 안 돌리고 코드를 받아들임. → 항상 채점기(테스트/타입/빌드)를 쥐여주기.

4. 무지성 자동 수락 auto-accept 켜놓고 안 보다가 엉뚱한 파일이 다 바뀜. → 신뢰 구간에서만, 허용 목록은 정교하게.

5. 큰 작업을 계획 없이 바로 방향이 틀린 채 200줄이 나옴. → Plan 모드, "먼저 계획부터".

마무리 — 진짜 비밀

이 글의 기술 열 개는 — 전부 한 문장으로 요약됩니다.

Claude Code를 잘 쓴다는 건 — 더 좋은 프롬프트를 쓰는 게 아니라, 에이전트가 일할 환경을 설계하는 것이다.

좋은 컨텍스트(CLAUDE.md, 깨끗한 세션)를 주고, 적절한 권한(허용 목록, 자동 수락)을 주고, 촘촘한 피드백 루프(테스트, 타입, 훅)를 깔아주면 — 모델은 알아서 좋은 결과를 냅니다. 막힐 때 던질 질문은 항상 똑같습니다 — "Claude가 지금 이걸 할 만큼 충분히 아는가? 할 권한이 있는가? 맞는지 확인할 방법이 있는가?"

git이 그랬듯 — Claude Code의 진짜 비밀도 두려워하지 않는 것입니다. 자동 수락이 무서운 건 되돌릴 수 없을까봐인데 — 자주 커밋하고, 브랜치를 나누고, 검증 루프를 깔아두면 — 최악의 경우에도 git reset 한 번이면 됩니다. (git이 아직 무섭다면 — 먼저 git부터.)

다음 글에서는 — 한 단계 더 들어가서, 나만의 하네스를 만드는 법을 다루겠습니다. 커스텀 에이전트, 훅, 슬래시 명령을 엮어서 — 반복되는 내 작업 흐름을 통째로 자동화하는 패턴.