Claude Code를 반년 넘게 사용하면서, 코드를 작성한 줄 수보다 더 많은 함정을 밟아봤습니다.
처음에는 Claude Code가 그저 "더 발전된 Copilot"이라고 생각했습니다. 터미널에 입력하면 코드를 작성해주고 끝나는 도구라고요. 하지만 나중에 깨달았습니다. 이 도구의 한계는 제가 상상했던 것보다 훨씬 높지만, 사용법을 알아야만 가능합니다.
이 글은 공식 문서와 실제 경험을 결합하여 제가 생각하기에 가장 중요한 사용 팁을 정리한 것입니다. 어떤 것들은 힘들게 얻은 교훈이고, 다른 것들은 문서를 읽어야만 알 수 있었던 숨겨진 기능들입니다.
1. CLAUDE.MD: 가장 과소평가된 기능
이 글에서 단 하나만 기억해야 한다면 이것을 기억하세요: CLAUDE.md를 잘 작성하세요.
CLAUDE.md는 Claude Code가 모든 대화 시작 시 자동으로 읽는 명령 파일입니다. 새 동료를 위해 작성하는 온보딩 문서와 같아서, 그들이 알기를 원하는 모든 것을 거기에 적어두면 됩니다.
많은 사람들이 CLAUDE.md를 작성하지 않거나 몇 줄만 적습니다. 그 결과 매 대화마다 프로젝트 구조, 코딩 표준, 기술 스택 선택 이유를 처음부터 설명해야 합니다. 마치 매일 아침 회사를 동료에게 다시 소개하는 것과 같습니다.
좋은 CLAUDE.md가 포함해야 할 내용:
1# 프로젝트 이름23## 빌드 및 테스트 명령어4- 의존성 설치: npm install5- 테스트 실행: npm test6- 단일 테스트: npm test -- --grep "테스트 이름"7- 포맷팅: npm run format89## 코딩 표준10- Python: 포맷팅에 ruff 사용, 줄 너비 8811- 테스팅: pytest 사용, 서비스당 하나의 테스트 파일12- API 라우트: 복수형 파일명 사용: users.py, orders.py13- 커밋 메시지: 영어, 형식: type(scope): description1415## 아키텍처 결정 사항16- CSS Modules 대신 Tailwind 선택 (팀이 표준화했기 때문)17- 사용자 권한 확인은 미들웨어에서 처리; 모든 라우트에서 반복하지 않음18- Redis 캐시 키 접두사: app:v1:1920## 일반적인 함정21- DB 연결 풀 제한은 20개; 루프에서 새 연결을 열지 마세요22- 데이터베이스를 모킹하지 마세요; 지난번에 모킹은 통과했지만 프로덕션 마이그레이션은 실패했습니다
핵심 원칙:
첫째, Claude가 코드에서 추론할 수 없는 것을 작성하세요. 프로젝트의 "무엇"보다 "왜"가 더 중요합니다. React 사용법을 설명할 필요는 없지만 "팀이 표준화했기 때문에 Tailwind를 선택했다"는 것은 알려줘야 합니다.
둘째, 200줄 미만으로 유지하세요. 공식 문서는 CLAUDE.md가 너무 길면 Claude가 규칙을 무시할 수 있다고 명시적으로 언급합니다. 마크다운 헤더와 목록을 사용하여 스캔하기 쉽게 만드세요.
셋째, 자주 변경되는 내용을 넣지 마세요. 상세한 API 문서나 파일별 설명은 CLAUDE.md에 적합하지 않습니다. 링크만 제공하세요.
CLAUDE.md의 4가지 수준
Claude Code는 우선순위가 높은 순서대로 4가지 수준의 CLAUDE.md를 지원합니다:
제 글로벌 CLAUDE.md에는 보통 다음과 같이 작성합니다:
1- 저는 풀스택 엔지니어입니다; 기본 개념을 지나치게 설명할 필요 없음2- 답변은 간결하게 유지; 불필요한 인사말 생략3- 코드 변경 후做了什么 요약하지 마세요; diff를 확인하겠습니다4- 간단한 해결책 우선; 과도한 엔지니어링 피하기
이 네 줄만으로 수백 번의 반복적인 수정을 줄일 수 있습니다.
고급: .claude/rules/로 규칙 구성하기
프로젝트가 성장함에 따라 하나의 CLAUDE.md 파일로는 모든 것을 담을 수 없습니다. 공식 솔루션은 더 우아합니다: 규칙을 .claude/rules/ 디렉토리로 분할하세요.
1.claude/rules/2├── testing.md # 테스팅 표준3├── api-style.md # API 작성 스타일4└── frontend.md # 프론트엔드 규칙
더 강력한 기능으로, YAML 프론트매터를 사용하여 규칙을 특정 파일로 제한할 수 있습니다:
1---2paths: ["src/api/**/*.ts", "src/routes/**/*.ts"]3---45API 라우트는 입력 검증과 오류 처리를 포함해야 합니다.6모든 새 엔드포인트는 tests/api/에 통합 테스트가 필요합니다.
이렇게 하면 Claude가 일치하는 파일에 액세스할 때만 규칙이 로드되어 컨텍스트 공간을 절약합니다.
2. 프롬프트 품질이 출력 품질을 결정합니다
진부한 말처럼 들리지만, 너무 많은 사람들이 Claude Code를 이렇게 사용하는 것을 봤습니다:
"로그인 기능을 작성해줘"
그런 다음 생성된 방대한 코드 덩어리에 대해 고민합니다. 원하는 게 아니거든요.
좋은 명령어는 세 가지 요소를 포함해야 합니다: 목표, 제약 조건, 맥락.
나쁜 명령어 vs 좋은 명령어
나쁨: "사용자 목록에 검색 기능을 추가해줘"
좋음: "@src/pages/UserList.tsx의 테이블 위에 검색 상자를 추가해줘. 검색은 백엔드 API /api/users?search=xxx를 사용하고, 프론트엔드 필터링은 하지 마. 300ms 디바운스를 사용하고, 스타일은 기존 Filter 컴포넌트와 일관되게 유지해."
차이점은? 좋은 명령어는 모호함을 줄입니다. Claude Code는 프론트엔드 검색인지 백엔드 검색인지, 디바운스 시간, 스타일링 표준을 추측할 필요가 없습니다.
공식 권장 프롬프트 팁
1. @를 사용하여 특정 파일 참조
Claude Code는 @filepath를 사용하여 파일 내용을 직접 컨텍스트로 가져오는 것을 지원합니다. "그 인증 관련 코드"라고 말하는 대신 @src/auth/login.ts라고 작성하는 것이 훨씬 정확합니다. 줄 범위도 지정할 수 있습니다: @src/auth/login.ts#5-30.
2. 스크린샷과 이미지 붙여넣기
Ctrl+V를 사용하여 이미지를 직접 붙여넣으세요. UI 문제를 디버깅할 때 "지금 모습"과 "원하는 모습"의 스크린샷은 텍스트 설명보다 10배 더 효과적입니다.
3. 검증 기준 제공
"이 버그를 고쳐줘"라고만 말하지 말고, 이렇게 말하세요:
"로그인 시간 초과 후 재인증이 실패하는 문제를 수정해줘. 수정 후 토큰 만료 시 어떤 버튼을 클릭해도 자동으로 로그인 페이지로 리디렉션되어야 해. 테스트 케이스는 @tests/auth.test.ts에 있어; 수정 후 통과하는지 실행해봐."
Claude에게 자체 검증 가능한 기준을 제공하세요 — 테스트 케이스, 스크린샷, 예상 출력 — 그래야 스스로 작업 품질을 확인하고 왕복을 줄일 수 있습니다.
4. 하지 말아야 할 것을 명확히 하세요
Claude Code는 때때로 지나치게 열성적일 수 있습니다. 버그를 고치라고 했는데 주변 코드도 리팩토링합니다. "이 함수만 변경하고 다른 코드는 건드리지 마"라고 명시적으로 말하면 많은 문제를 예방할 수 있습니다.
모호한 명령어가 유용할 때
모든 상황이 정밀함을 요구하는 것은 아닙니다. 모호한 명령어는 탐색적 작업에 더 좋습니다:
- "이 파일에서 개선할 점은 무엇인가요?"
- "이 모듈의 아키텍처를 이해할 수 있게 도와주세요"
- "이 코드에 잠재적인 문제가 있나요?"
하지만 구현 단계에 도달하면 정밀 모드로 다시 전환하세요.
3. PLAN MODE: 행동하기 전에 명확하게 생각하기
Claude Code에는 Plan Mode가 있으며, 이것이 가장 과소평가된 워크플로우라고 생각합니다.
Plan Mode 진입 방법
세 가지 방법:
1# 플랜 모드로 직접 시작2claude --permission-mode plan34# 대화 중 전환 (Shift+Tab 두 번 누르기)5Shift+Tab Shift+Tab67# 프롬프트에 말하기8"아직 코드를 변경하지 말고, 계획을 세우는 것을 도와줘"
Plan Mode에서 Claude Code는 파일을 읽고 코드를 검색만 할 수 있습니다. 어떤 수정도 할 수 없습니다. 코드베이스를 탐색하고 요구 사항을 분석하며 상세한 구현 계획을 제공합니다.
Plan Mode의 올바른 사용법
핵심 작업: Ctrl+G를 눌러 에디터에서 계획을 열고 편집하세요.
즉, 다음을 할 수 있습니다:
- Claude가 초기 계획을 생성하도록 함
- Ctrl+G로 계획을 열고 동의하지 않는 부분을 삭제하고 자신의 아이디어 추가
- 일반 모드로 전환(Shift+Tab)하고 수정된 계획에 따라 Claude가 실행하도록 함
계획을 변경하는 데는 한 문장이면 충분하지만, 이미 작성된 코드를 변경하는 데는 10배 더 오래 걸립니다.
복잡한 작업을 위한 권장 워크플로우
공식 표준 프로세스는 4단계입니다: 탐색 → 계획 → 구현 → 검증.
11. Plan Mode 진입22. Claude가 관련 코드를 읽도록 함: "src/auth/의 코드를 읽어 세션 로직을 이해해줘"33. 계획 요청: "OAuth2 마이그레이션 계획을 세워줘"44. Ctrl+G로 계획 검토 및 편집55. 일반 모드로 전환66. "계획에 따라 구현하고, 작성 후 테스트를 실행해줘"77. Claude가 요구 사항에 대해 자체 점검하도록 함
Plan Mode가 필요하지 않은 경우
- 변수 이름 변경
- 명백한 오타 수정
- 단일 로그 줄 추가
기준은 간단합니다: 작업을 구현하는 방법이 하나뿐이라면 바로 하세요. 선택지가 여러 개라면 먼저 계획을 세우세요.
4. SUB-AGENTS: Claude Code의 멀티태스킹 능력
Sub-agents는 강력한 메커니즘입니다. Claude Code는 독립적인 AI 프로세스를 실행하여 작업을 병렬로 처리할 수 있습니다. 각 sub-agent는 자체 컨텍스트 창을 가지며 메인 대화를 복잡하게 만들지 않습니다.
내장 Sub-agent 유형
Sub-agents의 가장 큰 가치: 컨텍스트 격리
Claude에게 테스트 실행, 로그 분석, 또는 많은 파일 검색을 요청하면 이러한 작업은 엄청난 출력을 생성하여 컨텍스트 창을 채웁니다. 이러한 작업에는 sub-agents를 사용하세요. 출력은 sub-agent의 컨텍스트에 남고 요약만 반환됩니다.
예를 들어:
"Sub-agent를 사용하여 모든 테스트를 실행하고 실패한 케이스를 나열해줘"
"Sub-agent를 사용하여 더 이상 사용되지 않는 API를 사용하는 모든 파일을 검색해줘"
백그라운드에서 실행: Ctrl+B
Ctrl+B를 누르면 sub-agent가 백그라운드로 전환됩니다. Claude와 다른 이야기를 계속할 수 있으며, 백그라운드 작업이 완료되면 알림을 받습니다.
적합한 경우:
- 테스트 스위트 실행 (보통 몇 분 소요)
- 대규모 코드 검색
- 긴급하지 않은 코드 리뷰
커스텀 Sub-agents
.claude/agents/ 디렉토리에 커스텀 에이전트를 생성할 수 있습니다:
1---2name: code-reviewer3description: 코드 리뷰 전문가. 코드 변경 후 자동으로 트리거됩니다.4tools: Read, Grep, Glob, Bash5model: sonnet6---78당신은 시니어 코드 리뷰어입니다. 다음 차원을 확인하세요:9- 코드 명확성 및 가독성10- 오류 처리의 완전성11- 민감한 정보 노출12- 입력 검증13- 성능 함정
그런 다음 대화에서 @"code-reviewer (agent)"를 사용하여 호출하세요.
5. 컨텍스트 관리: 가장 간과되는 핵심
Claude Code의 컨텍스트 창은 크지만(최대 1M 토큰), 무한하지 않으며 컨텍스트 관리는 출력 품질을 직접적으로 결정합니다.
컨텍스트에 포함된 것
- 대화 기록
- Claude가 읽은 모든 파일 내용
- 명령어 실행 출력
- CLAUDE.md 파일 (매번 로드됨)
- 메모리 파일 (처음 200줄)
- 로드된 Skill 및 MCP 도구 정의
5가지 실용적인 전략
1. /clear: 작업 완료 시 지우기
버그 수정, 기능 추가, 리팩토링을 모두 같은 대화에서 하지 마세요. /clear는 컨텍스트를 비우지만 CLAUDE.md는 유지하여 무료 재시작처럼 작동합니다.
2. /compact: 수동으로 컨텍스트 압축
대화가 길어지면 /compact를 사용하여 Claude가 이전 대화를 자동으로 요약하고 압축하도록 하세요. 더 나은 방법은 압축에 초점을 추가하는 것입니다:
/compact focus on API changes and test results
이렇게 하면 Claude가 압축 중에 관심 있는 내용을 우선적으로 유지합니다.
3. /context: 컨텍스트를 차지하는 항목 확인
/context를 입력하면 현재 사용량을 볼 수 있습니다. 어떤 파일이 얼마나 많은 토큰을 차지하는지, MCP 도구 정의가 얼마나 많은 공간을 차지하는지 알 수 있습니다. 쓸모없는 MCP 서버가 엄청난 공간을 차지하는 경우를 자주 발견합니다.
4. Sub-agents를 사용하여 노이즈 격리
테스트 실행 및 로그 분석은 많은 출력을 생성합니다. Sub-agents가 처리하도록 하여 메인 대화 컨텍스트를 깨끗하게 유지하세요.
5. CLAUDE.md에 압축 보존 지침 작성
Claude에게 압축 중에 반드시 유지해야 할 내용을 알릴 수 있습니다:
1# 압축 지침2컨텍스트 압축 시 항상 유지할 내용:3- 수정된 파일의 전체 목록4- 테스트 명령어 및 결과5- 주요 아키텍처 결정 사항
메모리 vs CLAUDE.md
메모리의 용도: 사용자 선호사항("이 사람은 간결한 답변을 좋아함"), 프로젝트 규칙("배포에 특별한 단계가 있음"), 과거 결정 사항("지난번에 X 때문에 옵션 A를 선택함").
메모리가 아닌 것: 코드 세부 사항, Git 기록, 임시 상태 — 이러한 것은 코드와 Git에서 더 정확하게 검색됩니다.
/memory 명령어를 사용하여 로드된 모든 메모리를 보고 관리하세요.
6. 권한 관리: 보안과 효율성의 균형
Claude Code는 5가지 권한 모드를 제공하며, 대화 중 Shift+Tab으로 전환할 수 있습니다:
권한 규칙 구성
.claude/settings.json에서 각 도구에 대한 권한을 세밀하게 제어할 수 있습니다:
1{2 "permissions": {3 "allow": [4 "Bash(npm run *)",5 "Bash(git commit *)",6 "Edit(src/**/*.ts)",7 "Read(*.md)"8 ],9 "deny": [10 "Bash(rm -rf *)",11 "Edit(.env)"12 ]13 }14}
규칙 우선순위: deny → ask → allow (deny가 가장 높은 우선순위).
즉, 일반적인 명령어는 대담하게 허용하면서 deny를 사용하여 민감한 파일을 보호할 수 있습니다. 예를 들어, .env 파일은 절대 편집되어서는 안 됩니다.
설정 파일의 계층 구조
CLAUDE.md와 유사하게 설정에도 여러 수준이 있습니다:
1조직 정책 (최우선 순위)2 ↓3CLI 인수4 ↓5.claude/settings.local.json (로컬, Git에 커밋되지 않음)6 ↓7.claude/settings.json (프로젝트 수준, 팀과 공유)8 ↓9~/.claude/settings.json (글로벌, 개인)10 ↓11기본값 (최하위 우선순위)
제 조언: 팀 공유 규칙은 .claude/settings.json에, 개인 선호사항은 ~/.claude/settings.json에, 민감한 설정은 .claude/settings.local.json에 넣고 (.gitignore에 추가하는 것을 잊지 마세요).
7. HOOKS: 규칙을 철칙으로 만들기
CLAUDE.md의 지침은 "제안"입니다. Claude는 대부분 따르지만 가끔 잊어버립니다. Hooks는 "철칙"입니다. 무슨 일이 있어도 실행됩니다.
Hooks는 특정 라이프사이클 이벤트에 의해 자동으로 트리거되는 셸 명령어로, settings.json에 구성됩니다.
주요 이벤트 유형
실용적인 예제
자동 포맷팅 — 모든 편집 후 Prettier 실행:
1{2 "hooks": {3 "PostToolUse": [{4 "matcher": "Edit|Write",5 "hooks": [{6 "type": "command",7 "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"8 }]9 }]10 }11}
중요 파일 보호 — 프로덕션 설정 수정 방지:
1{2 "hooks": {3 "PreToolUse": [{4 "matcher": "Edit|Write",5 "hooks": [{6 "type": "command",7 "command": ".claude/hooks/protect-files.sh"8 }]9 }]10 }11}
종료 코드 0을 반환하는 Hook 명령어는 허용을 의미하고, 종료 코드 2는 차단을 의미합니다. 즉, 모든 복잡한 로직을 작성할 수 있습니다.
컨텍스트 압축 후 중요 정보 재주입:
1{2 "hooks": {3 "SessionStart": [{4 "matcher": "compact",5 "hooks": [{6 "type": "command",7 "command": "echo 'Bun을 사용하고 npm을 사용하지 마세요. 커밋하기 전에 bun test를 실행하세요.'"8 }]9 }]10 }11}
이것은 일반적인 문제를 해결합니다: 긴 대화가 압축되면 이전에 언급된 중요한 지침이 손실될 수 있습니다. Hooks는 매 압축 후 자동으로 재주입할 수 있습니다.
4가지 유형의 Hooks
8. GIT WORKFLOW: WORKTREE를 잘 활용하기
Claude Code는 Git 명령어를 실행할 수 있으며, 이는 양날의 검입니다. 하지만 공식 도구는 훌륭한 안전망을 제공합니다: Worktree.
Git Worktree: 격리된 작업 공간
1# 격리된 worktree에서 Claude 시작2claude --worktree feature-auth3claude --worktree bugfix-12345# 자동으로 이름 생성6claude --worktree
Worktree는 .claude/worktrees/ 아래에 독립적인 Git 브랜치 복사본을 생성합니다. Claude가 내부에서 무엇을 하든 메인 브랜치에 영향을 미치지 않습니다. 종료 시:
- 변경 사항이 없으면 → 자동 정리
- 변경 사항이 있으면 → 유지 또는 삭제 여부를 묻는 메시지 표시
이것은 특히 탐색적 작업에 유용합니다. 리팩토링 계획이 효과가 있을지 확신이 없나요? Worktree에서 시도해보고 실패하면 위험 없이 폐기하세요.
몇 가지 Git 철칙
1. Claude Code가 자동으로 푸시하지 못하게 하세요
커밋은 할 수 있지만, 푸시 작업은 사용자가 확인해야 합니다. 원격에 푸시되면 롤백 비용이 크게 증가합니다.
2. 자주 커밋하세요
작은 기능을 완료한 후 커밋하세요. /rewind를 사용하여 커밋 기록이 있는 경우 모든 체크포인트로 돌아갈 수 있습니다.
3. 파괴적인 작업에 주의하세요
Claude Code가 git reset --hard, git push --force, 또는 rm -rf를 실행하려고 하면 승인하기 전에 결과를 신중히 생각하세요. 이러한 작업은 취소할 수 없습니다. 권한 규칙에서 이러한 명령어를 거부할 수도 있습니다.
4. PR에서 컨텍스트 복원
이것은 PR 변경 사항과 토론을 컨텍스트로 자동 로드하여 코드 리뷰나 다른 사람의 작업을 계속하는 데 완벽합니다.
1claude --from-pr 123
9. 단축키 및 명령어 참조
매일 사용하는 단축키입니다. 꼭 기억하세요:
가장 일반적인 단축키
가장 일반적인 슬래시 명령어
1/compact [focus] # 컨텍스트 압축, 초점 지정 가능2/clear # 대화 지우기, 다시 시작3/context # 컨텍스트 사용량 보기4/memory # 메모리 보기 및 관리5/rewind # 체크포인트로 롤백6/resume [name] # 이전 대화 재개7/model # 모델 전환8/effort [level] # 추론 깊이 설정: low/medium/high/max9/init # CLAUDE.md 자동 생성10/mcp # MCP 서버 관리11/permissions # 권한 규칙 보기12/cost # 토큰 소비량 보기
/init은 새 프로젝트에 특히 유용합니다. 코드베이스를 자동으로 분석하고 CLAUDE.md 초안 작성을 도와줍니다. 보통 수동 조정이 필요하지만, 처음부터 시작하는 것보다 훨씬 빠릅니다.
10. EXTENDED THINKING: Claude가 더 깊이 생각하게 하기
복잡한 문제의 경우 Extended Thinking 모드를 활성화하여 Claude가 답변하기 전에 더 많은 시간을 추론에 사용할 수 있습니다.
사용 방법
1# 단축키 전환2Option+T (Mac) / Alt+T (Windows/Linux)34# 또는 명령어로5/effort high # 더 깊은 추론6/effort max # 최대 추론 깊이7/effort low # 간단한 작업, 토큰 절약
사용 시기
- 복잡한 아키텍처 결정
- 까다로운 디버깅 (여러 가능한 원인을 제거해야 함)
- 다단계 리팩토링 설계
- 여러 솔루션의 장단점 비교
필요하지 않은 경우
- 간단한 코드 변경
- 포맷팅, 이름 변경
- 이미 명확한 버그 수정
프로 팁: 프롬프트에 "ultrathink"를 작성하면 effort 설정을 수동으로 조정하지 않고도 가장 높은 추론 깊이를 강제할 수 있습니다.
11. MCP SERVER: Claude를 외부 세계에 연결하기
MCP (Model Context Protocol)를 사용하면 Claude Code가 GitHub, 데이터베이스, Slack, Notion 등 외부 도구와 통신할 수 있습니다.
빠른 추가
1claude mcp add github -- npx @anthropic-ai/mcp-server-github2claude mcp add postgres -- npx @anthropic-ai/mcp-server-postgres postgresql://localhost:5432/mydb
구성 파일
MCP는 .mcp.json에 구성됩니다:
1{2 "mcpServers": {3 "github": {4 "type": "stdio",5 "command": "npx",6 "args": ["@modelcontextprotocol/server-github"],7 "env": {8 "GITHUB_TOKEN": "$GITHUB_TOKEN"9 }10 }11 }12}
컨텍스트 오버헤드 참고
각 MCP 서버는 도구 정의에 추가로 100-500+ 토큰을 소비합니다. /mcp 명령어를 사용하여 각 서버의 오버헤드를 확인하고 사용하지 않는 서버는 비활성화하세요.
제 경험: 욕심내지 마세요. 2-3개의 일반적으로 사용되는 MCP 서버면 충분합니다. 너무 많이 설치하면 도구 정의가 컨텍스트 공간을 차지하여 코드 분석 품질이 저하될 수 있습니다.
12. IDE 통합: 터미널 그 이상
VS Code
Claude Code 확장 프로그램을 설치한 후 VS Code에서 직접 Claude를 사용할 수 있으며 터미널로 전환할 필요가 없습니다.
유용한 기능:
- 나란히 diff 보기: Claude의 변경 사항이 diff로 표시되어 한눈에 파악 가능
- Option+K / Alt+K: 현재 파일에 @참조를 빠르게 삽입
- 멀티탭 대화: 다른 탭에서 여러 독립적인 대화 열기
- Cmd+Shift+Esc: 새 대화 탭 빠르게 열기
JetBrains
IntelliJ, PyCharm, WebStorm 등 JetBrains IDE에도 Claude Code 플러그인이 있습니다. Plugins 마켓플레이스에서 "Claude Code"를 검색하여 설치하세요.
13. 코드 리뷰: 신뢰하되 검증하세요
Claude Code의 코드 품질은 일반적으로 좋지만, 맹목적으로 신뢰해서는 안 됩니다.
일반적인 문제
1. 과도한 엔지니어링
간단한 유틸리티 함수를 요청했는데 제네릭, 인터페이스, 팩토리 패턴이 포함된 완전한 추상화 계층을 제공합니다. 호두까기 인형에 망치를 사용하는 격입니다.
해결책: CLAUDE.md에 "간단한 해결책 우선"이라고 작성하거나 명령어에 "추상화 불필요"라고 명시적으로 말하세요.
2. 환각 API
때때로 존재하지 않는 API나 오래된 구문을 사용합니다. 특히 새로운 버전의 niche 라이브러리에서 그렇습니다.
해결책: 테스트를 실행하세요. 이것이 명령어에 검증 표준을 포함해야 하는 이유입니다.
3. 범위 확장
하나의 함수를 변경하라고 했는데 전체 파일을 리팩토링합니다.
해결책: "X만 변경하고 다른 코드는 건드리지 마"라고 명시적으로 말하세요. 또는 /freeze 명령어를 사용하여 편집 범위를 특정 디렉토리로 제한하세요.
Writer/Reviewer 모드
공식적으로 권장되는 고급 모드: 두 개의 독립적인 세션을 사용하여 "Writer"와 "Reviewer" 역할을 수행하세요.
두 세션은 독립적인 컨텍스트를 가지므로 Reviewer는 Writer의 논리에 영향을 받지 않고 사각지대를 찾을 수 있습니다.
1세션 A (Writer): "API 속도 제한 미들웨어 구현"2세션 B (Reviewer): "@src/middleware/rateLimiter.ts의 속도 제한 구현 검토,3 엣지 케이스, 경쟁 조건, 일관성에 초점"4세션 A: "리뷰 피드백 수정: [B의 출력 붙여넣기]"
14. Claude Code로 하지 말아야 할 것
"해야 할 것"에 대해 많이 말했으니, 이제 "하지 말아야 할 것"에 대해 이야기해 봅시다.
1. 전혀 이해하지 못하는 일을 시키지 마세요
Kubernetes에 대해 전혀 모른다면 Claude Code가 배포 설정을 작성하여 직접 사용하도록 하지 마세요. 이해하지 못하는 것은 검토할 수 없습니다.
2. 버전 관리가 없는 환경에서 사용하지 마세요
Git이 없으면 롤백 기능이 없습니다. Claude Code의 변경 사항이 파일을 덮어쓸 수 있으며, 버전 관리 없이 사용하는 것은 그물 없이 줄타기를 하는 것과 같습니다.
3. 한 번에 거대한 작업을 던지지 마세요
"전체 프로젝트를 JavaScript에서 TypeScript로 마이그레이션해줘"
이 명령어는 Claude Code에게 자유 재량권을 주어 결과를 통제 불가능하게 만듭니다. 작은 단계로 나누고 각 단계를 확인한 후 다음 단계로 진행하세요.
4. 첫 시도에 완벽을 기대하지 마세요
반복은 정상입니다. /rewind를 사용하여 돌아가고 정확한 피드백으로 "무엇이 잘못되었는지" 설명하세요.
요약
Claude Code 사용의 핵심 철학은 간단합니다:
그것은 매우 유능한 협력자이지만, 자동 조종 장치가 아닙니다. 핸들은 항상 당신의 손에 있습니다.
중요도 순으로 정리한 제 조언은:
- CLAUDE.md 를 잘 작성하라 — 한 번 투자하면 모든 대화에서 이점을 얻는다
- 정확한 지침을 제공하라 — 목표 + 제약 조건 + 검증 기준
- Plan Mode 를 사용하라 — 복잡한 작업은 먼저 계획하고, 나중에 실행하라
- 컨텍스트를 관리하라 — /clear, /compact, Sub-agents
- 권한을 통제하라 — 위험한 작업은 거부하고, 일반적인 명령은 허용하라
- 자주 커밋하라 — 롤백할 수 있는 능력을 유지하라
이것들을 실천하면, Claude Code 는 여러분의 효율성을 몇 배로 높여줄 수 있습니다. 그렇지 않으면, 더 빠르게 혼란만 가중시킬 뿐입니다.
도구의 가치는 항상 그것을 사용하는 사람에 달려 있습니다.
위 내용은 Claude Code 공식 문서와 실무 경험을 결합한 것입니다. 더 나은 방법이 있다면 자유롭게 공유해 주세요.
