Claude Code를 잘 쓰는 핵심은 "더 똑똑한 프롬프트"보다 컨텍스트(Claude가 한 번에 참고하는 대화와 파일 내용)를 관리하고, 계획을 먼저 세우고, 결과를 검증하는 습관입니다. Stack Overflow 2025 개발자 설문에서 응답자의 84%가 개발에 AI 도구를 쓰고 있거나 쓸 계획이라고 답했지만, AI 결과물의 정확도를 불신한다는 응답(46%)이 신뢰한다는 응답(33%)보다 많았습니다(Stack Overflow Developer Survey 2025, AI, 2026-10-03 확인). 쓰는 사람은 많아도 믿고 맡기기는 어렵다는 뜻입니다. 같은 설문에서 AI 에이전트를 쓰거나 만드는 응답자 가운데 40.8%는 Claude Code를 쓴다고 답했습니다.
이 글은 AI를 쓰면서도 결과를 믿기 어려운 간극을 줄여 주는 Claude Code 팁 11가지를 모았습니다. 모든 팁은 Anthropic 공식 문서(code.claude.com/docs)에서 2026년 10월 3일에 다시 확인했고, 각 팁마다 한국어 공식 문서 링크를 달았습니다.
핵심 요약
- 새 프로젝트에서는
/init으로 CLAUDE.md를 먼저 만들고, 공식 문서 권장대로 200줄 이내로 유지하세요.- 큰 변경은
Shift+Tab플랜 모드로 계획부터 받고, 실수했다면Esc두 번으로 체크포인트를 되돌리세요. 단, Bash로 바뀐 파일은 체크포인트에 잡히지 않습니다.- 같은 문제를 두 번 넘게 고쳐도 안 되면
/clear로 새로 시작하는 편이 낫다고 공식 문서는 권합니다.- 반복 작업은 Skills로 만들어 필요할 때만 불러오고, 반드시 지켜야 할 규칙은 Hooks로 옮기면 CLAUDE.md에 적는 것보다 확실하게 실행됩니다.
#메모 단축키는 현재 빠른 명령 목록에 없고, "think hard"는 이제 일반 텍스트로 전달됩니다. 깊은 추론을 요청하는 키워드는ultrathink하나입니다.
목차
- 1. /init으로 CLAUDE.md 만들기
- 2. 플랜 모드로 계획부터 받기
- 3. Esc로 멈추고 되돌리기
- 4. 컨텍스트 관리
- 5. @파일, 이미지, ! 셸 모드
- 6. 권한 규칙과 auto 모드
- 7. Skills
- 8. Hooks
- 9. 서브에이전트
- 10. MCP
- 11. claude -p와 병렬 세션
- 예시: 팁을 이어서 쓰는 흐름
- 이제는 맞지 않는 옛날 팁
- 자주 묻는 질문
1. /init으로 CLAUDE.md부터 만드세요
CLAUDE.md는 Claude가 세션을 시작할 때마다 읽는 프로젝트 설명서입니다. 프로젝트 루트에서 /init을 실행하면 Claude가 코드베이스를 분석해 빌드·테스트 명령어와 컨벤션을 담은 초안을 만들어 줍니다. 이미 파일이 있으면 덮어쓰지 않고 개선 사항을 제안합니다.
위치에 따라 적용 범위가 달라집니다.
| 파일 위치 | 적용 범위 |
|---|---|
~/.claude/CLAUDE.md |
내 모든 프로젝트 |
./CLAUDE.md 또는 ./.claude/CLAUDE.md |
이 프로젝트 (git으로 팀과 공유) |
./CLAUDE.local.md |
이 프로젝트의 개인 설정 (.gitignore에 추가) |
공식 메모리 문서는 CLAUDE.md 파일 하나당 200줄 이내를 목표로 하라고 권합니다. 파일이 길수록 컨텍스트를 많이 차지하고 지시를 따르는 정도도 떨어지기 때문입니다(Claude가 프로젝트를 기억하는 방법). 규칙을 추가하고 싶다면 대화 중에 "이 내용을 CLAUDE.md에 추가해 줘"라고 요청하거나 /memory로 파일을 열어 직접 고치면 됩니다.
2. 큰 작업은 Shift+Tab 플랜 모드로 계획부터 받으세요
플랜 모드에서 Claude는 파일을 읽고 계획만 제안하며, 사용자가 승인하기 전까지 코드를 수정하지 않습니다. Shift+Tab을 누를 때마다 권한 모드가 바뀌며, 상태 표시줄에 plan mode on이 보일 때까지 누르면 됩니다. 처음부터 플랜 모드로 시작하려면 claude --permission-mode plan을 실행하세요.
공식 모범 사례 문서가 권하는 흐름은 탐색 → 계획 → 구현 → 커밋입니다. 다만 "변경 내용을 한 문장으로 설명할 수 있다면" 계획 단계는 건너뛰어도 된다고 덧붙입니다(Claude Code 모범 사례). 오타 수정에 플랜 모드는 과하고, 여러 파일에 걸친 리팩터링에는 꼭 필요합니다. 계획이 나오면 Ctrl+G로 에디터에서 직접 고칠 수도 있습니다.
3. Esc로 멈추고, Esc 두 번으로 되돌리세요
Esc를 한 번 누르면 Claude가 작업 중간에 멈추고, 그때까지 한 작업은 그대로 남습니다. 방향이 틀렸다고 느끼는 순간 바로 끊는 습관이 토큰과 시간을 아껴 줍니다.
빈 입력창에서 Esc를 두 번 누르거나 /rewind를 입력하면 되돌리기 메뉴가 열립니다. 대화만, 코드만, 또는 둘 다 이전 시점으로 되돌릴 수 있습니다. 작업을 시작하는 프롬프트마다 체크포인트가 자동으로 생기므로, 위험한 리팩터링도 부담 없이 시도해 볼 수 있습니다.
주의할 점이 하나 있습니다. 공식 체크포인트 문서에 따르면 Claude가 Bash 명령으로 수정한 파일은 체크포인트에 기록되지 않습니다(체크포인트). 파일 삭제나 이동, 스크립트 실행 결과까지 되돌리려면 git 커밋이 여전히 필요합니다. 체크포인트는 git을 대체하지 않습니다.
4. /clear, /compact, /context로 컨텍스트를 관리하세요
대화가 길어질수록 Claude가 참고하는 컨텍스트는 오래된 시도와 실패한 수정으로 채워집니다. 상황에 따라 다음 명령을 고르세요(명령어 레퍼런스).
/context: 지금 컨텍스트가 무엇으로 얼마나 차 있는지 색깔 격자로 보여 줍니다./compact Focus on the API changes: 대화를 요약해 공간을 확보합니다. 무엇을 남길지 지시를 함께 줄 수 있습니다./clear: 대화를 비우고 새로 시작합니다./btw: 대화 기록에 남기지 않고 곁가지 질문을 할 때 씁니다.
공식 모범 사례 문서의 기준은 분명합니다. 같은 문제로 Claude를 두 번 넘게 고쳤는데도 해결되지 않으면, /clear로 새로 시작하고 처음 프롬프트를 더 구체적으로 쓰는 편이 낫다고 합니다(Claude Code 모범 사례). 실패한 시도가 쌓인 컨텍스트는 다음 시도를 방해할 때가 많습니다.
5. @파일, 이미지 붙여넣기, ! 셸 모드로 맥락을 바로 넘기세요
말로 설명하는 것보다 파일과 출력을 그대로 보여 주는 편이 정확합니다.
@src/utils/auth.js 의 토큰 갱신 로직을 설명해 줘
!git status
@를 입력하면 파일 경로가 자동 완성되고 해당 파일이 대화에 포함됩니다. 줄 앞에 !를 붙이면 셸 명령이 바로 실행되고 그 출력이 세션에 추가됩니다. 화면 캡처나 디자인 시안은 드래그 앤드 드롭하거나 Ctrl+V로 붙여 넣으면 되는데, macOS의 iTerm2에서는 Cmd+V, Windows와 WSL에서는 Alt+V를 씁니다(인터랙티브 모드).
6. 권한 규칙과 auto 모드를 이해하세요
2026년 들어 크게 바뀐 부분 중 하나입니다. 공식 권한 모드 문서에 따르면 터미널과 VS Code 확장에서 Claude Code v2.1.283 이상은 auto 모드로 시작하는 것이 기본값입니다. auto 모드에서는 분류 모델이 각 작업을 검토해 위험한 작업을 막습니다. 그래서 "Claude Code는 파일을 고치기 전에 항상 물어본다"는 예전 설명은 최신 버전의 기본 동작과 맞지 않습니다. 다만 설정에서 auto 모드를 끄거나 세션이 auto 모드를 지원하지 않으면 Manual 모드로 시작합니다.
auto 모드가 기본이 된 만큼, 자주 쓰는 명령은 /permissions에서 허용 규칙으로 등록해 두면 동작을 예측하기 쉽습니다. 예를 들어 Bash(npm run *) 규칙은 npm run build나 npm run test는 허용하지만 npm install은 허용하지 않습니다(권한 설정). 권한 규칙은 보안 설정의 일부이므로, 팀 단위로 운영한다면 스타트업이 개발보안에 대해 노력할 때에서 정리한 인프라 보안 점검 항목과 함께 보는 것도 좋습니다.
| 설정 파일 | 용도 |
|---|---|
.claude/settings.json |
팀과 공유하는 프로젝트 규칙 |
.claude/settings.local.json |
이 프로젝트의 개인 규칙 |
~/.claude/settings.json |
내 모든 프로젝트 공통 규칙 |
7. 반복하는 프롬프트는 Skills로 만드세요
매번 같은 지시를 붙여 넣고 있다면 Skill로 만들 때입니다. .claude/skills/<이름>/SKILL.md 파일을 만들면 /이름으로 호출할 수 있고, 내용이 관련 있는 상황에서는 Claude가 알아서 적용하기도 합니다(Skills로 Claude 확장하기).
---
name: fix-issue
description: GitHub 이슈를 분석하고 수정한다
disable-model-invocation: true
---
Analyze and fix the GitHub issue: $ARGUMENTS.
위처럼 만들면 /fix-issue 1234로 실행되고 $ARGUMENTS 자리에 1234가 들어갑니다. disable-model-invocation: true를 넣으면 Claude가 자동으로 실행하지 않고 직접 호출할 때만 동작합니다. 예전 방식인 .claude/commands/*.md 파일도 계속 동작하며 같은 /이름 명령을 만듭니다.
8. 반드시 지켜야 할 규칙은 Hooks로 강제하세요
CLAUDE.md에 "편집 후 항상 Prettier를 돌려라"라고 적어도 Claude가 가끔 잊을 수 있습니다. 공식 Hooks 가이드는 CLAUDE.md를 권고, Hooks를 보장으로 구분합니다. Hooks는 파일 편집 후(PostToolUse)나 작업 종료 시(Stop) 같은 정해진 시점에 셸 명령을 항상 실행합니다(Hooks로 작업 자동화하기).
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{ "type": "command", "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write" }
]
}
]
}
}
이 예시는 JSON을 다루는 커맨드라인 도구 jq와 Node.js의 npx가 설치되어 있어야 동작합니다. 설정 파일을 직접 쓰기 부담스럽다면 "파일을 편집할 때마다 prettier를 실행하는 hook을 만들어 줘"라고 Claude에게 요청해도 됩니다. 등록된 hook은 /hooks로 확인합니다.
9. 조사는 서브에이전트에게 맡겨 메인 컨텍스트를 지키세요
서브에이전트는 자기만의 컨텍스트 창에서 일하고 결과 요약만 돌려주는 보조 에이전트입니다. 코드베이스 여기저기를 뒤지는 조사를 메인 대화에서 하면 파일 내용이 컨텍스트를 가득 채우지만, 서브에이전트에게 맡기면 결론만 남습니다(서브에이전트 만들기).
서브에이전트를 써서 우리 인증 시스템이 토큰 갱신을 어떻게 처리하는지 조사해 줘
자주 쓰는 역할은 .claude/agents/ 폴더(개인용은 ~/.claude/agents/)에 마크다운 파일로 정의합니다. 파일 맨 위 --- 사이의 설정 영역(frontmatter)에는 name과 description이 필수이고, tools와 model은 선택입니다. 참고로 현재 버전에서 /agents를 입력하면 대화형 메뉴 대신 안내 문구만 나옵니다. 메뉴는 v2.1.197 이하에서만 동작합니다(명령어 레퍼런스).
10. claude mcp add로 외부 도구를 연결하세요
MCP(Model Context Protocol) 서버를 연결하면 Claude Code가 Notion, Figma, 데이터베이스 같은 외부 도구를 직접 다룰 수 있습니다.
claude mcp add --transport http notion https://mcp.notion.com/mcp
claude mcp list
범위는 --scope 옵션으로 정합니다. 기본값 local은 나만 이 프로젝트에서 쓰고, project는 .mcp.json에 기록되어 팀과 공유되며, user는 내 모든 프로젝트에서 쓰입니다. 세션 안에서는 /mcp로 연결 상태와 인증을 확인합니다. 공식 문서는 연결하기 전에 각 서버를 신뢰할 수 있는지 확인하라고 강조합니다. 외부 콘텐츠를 가져오는 서버는 프롬프트 인젝션 위험에 노출될 수 있기 때문입니다(MCP로 도구 연결하기).
11. claude -p, --continue, --worktree로 터미널 밖까지 확장하세요
Claude Code는 대화형 화면 밖에서도 쓸 수 있습니다.
# 비대화형 실행: 스크립트, CI(자동 빌드·테스트 파이프라인), 커밋 직전 검사(pre-commit hook)에서 사용
git log --oneline -20 | claude -p "최근 커밋을 요약해 줘"
# 이 디렉터리의 마지막 세션 이어가기 / 목록에서 고르기
claude --continue
claude --resume
# 격리된 git worktree에서 병렬 세션 시작 (커밋이 하나 이상 있어야 함)
claude --worktree feature-auth
claude -p에 --output-format json을 붙이면 결과를 JSON으로 받아 다른 스크립트에서 쓸 수 있습니다(일반적인 워크플로).
Anthropic이 2025년 4월에 발표한 분석은 이런 활용이 왜 중요한지 보여 줍니다. 코딩 관련 대화 50만 건을 분석한 결과, Claude Code 대화의 79%가 AI가 작업을 직접 수행하는 "자동화"로 분류되었습니다. Claude.ai에서는 이 비율이 49%였습니다(Anthropic Economic Index: AI's Impact on Software Development, 2025-04-28). Anthropic 자체 분석이라는 점은 감안해야 하지만, Claude Code가 "대화 상대"보다 "작업 실행자"로 쓰이고 있다는 방향은 분명합니다.
예시: 팁을 이어서 쓰는 흐름
아래는 직접 테스트한 기록이 아니라, 앞의 팁들이 실제 작업에서 어떻게 이어지는지 보여 주기 위한 가상의 예시입니다. 로그인 후 가끔 세션이 풀리는 버그를 고친다고 가정해 보겠습니다.
- 처음 여는 저장소라면
/init으로 CLAUDE.md를 만들고 테스트 명령(npm test)이 들어갔는지 확인합니다. (팁 1) Shift+Tab으로 플랜 모드에 들어가 "@src/auth/session.ts를 보고 세션이 풀리는 원인과 수정 계획을 세워 줘"라고 요청합니다. (팁 2, 5)- 계획을 승인한 뒤 수정을 맡깁니다. 엉뚱한 파일을 고치기 시작하면 바로
Esc로 멈추고, 필요하면Esc두 번으로 되돌립니다. (팁 3) - 같은 방향으로 두 번 넘게 고쳐도 테스트가 실패하면, 알게 된 원인을 메모해 두고
/clear후 더 구체적인 프롬프트로 다시 시작합니다. (팁 4) - 수정이 끝나면 테스트를 돌리고 git에 커밋합니다. 이 과정에서 포맷을 매번 지적했다면 Prettier hook을 추가해 다음부터는 자동으로 처리되게 합니다. (팁 8)
핵심은 계획, 검증, 되돌리기를 작은 단위로 반복하는 것입니다. 앞서 본 설문에서 개발자의 46%가 AI 결과물의 정확도를 불신한다고 답한 만큼, 테스트와 커밋으로 확인하는 단계를 빼지 않는 것이 좋습니다.
보너스: 이제는 맞지 않는 옛날 팁 4가지
2025년에 쓰인 한국어 글 중에는 지금 문서와 다른 내용이 꽤 있습니다. 2026년 10월 3일 공식 문서 기준으로 정리했습니다.
| 예전 팁 | 현재 상태 (공식 문서 기준) |
|---|---|
#로 시작하면 메모리에 바로 저장 |
현재 빠른 명령 표에는 /, !, @, :만 있습니다. CLAUDE.md에 추가하려면 Claude에게 요청하거나 /memory를 쓰세요. (인터랙티브 모드) |
| think → think hard → ultrathink 단계별 키워드 | ultrathink만 키워드로 인식합니다. "think", "think hard"는 일반 텍스트로 전달됩니다. (모델 구성) |
/agents로 서브에이전트 메뉴 열기 |
v2.1.197 이하에서만 메뉴가 열리고, 지금은 안내 문구만 나옵니다. (명령어 레퍼런스) |
| "파일 수정 전에 항상 물어본다" | v2.1.283 이상 터미널과 VS Code에서는 auto 모드가 기본입니다. (권한 모드) |
깊은 추론이 필요할 때는 프롬프트 어딘가에 ultrathink를 넣으면 그 한 턴만 더 깊게 추론합니다. 세션 전체의 추론 강도는 /effort로 조절하며, low, medium, high, xhigh, max 단계와 auto를 지원합니다(모델 구성).
이 글의 자료를 고른 방법
이 글은 직접 테스트한 결과가 아니라 공식 문서를 기반으로 한 정리입니다. 다음 기준으로 팁을 골랐습니다.
- 출처: Anthropic 공식 문서(code.claude.com/docs)에 현재 명시된 기능만 넣었습니다. 각 명령어 문법은 2026년 10월 3일에 원문과 대조했습니다.
- 대상: 입문~중급 개발자가 첫 주 안에 바로 써먹을 수 있는지를 기준으로 삼았습니다.
- 최신성: 기존 한국어 글에서 자주 보이지만 현재 문서와 다른 내용은 따로 표시했습니다.
- 통계: Stack Overflow 2025 설문과 Anthropic 공개 연구만 인용했습니다. 2026년 Claude Code 사용 통계는 검증 가능한 1차 자료를 찾지 못해 넣지 않았습니다.
이 글은 Anthropic의 후원을 받지 않았으며 제휴 링크도 없습니다. Claude Code는 업데이트가 잦아서 버전에 따라 동작이 다를 수 있으니, claude --version으로 버전을 확인하고 공식 문서를 함께 보시길 권합니다.
자주 묻는 질문
Claude Code를 처음 쓴다면 무엇부터 해야 하나요?
프로젝트 폴더에서 claude를 실행한 뒤 /init으로 CLAUDE.md를 만드세요. 그다음 작은 작업 하나를 플랜 모드(Shift+Tab)로 맡겨 계획이 어떻게 나오는지 보는 것이 가장 빠른 입문 경로입니다. 막히면 /help로 사용 가능한 명령을 확인하세요.
CLAUDE.md와 Skills, Hooks는 어떻게 구분해서 쓰나요?
CLAUDE.md는 매 세션 항상 알아야 할 프로젝트 정보(빌드 명령, 컨벤션)를 담습니다. Skills는 필요할 때만 불러오는 작업 절차나 지식입니다. Hooks는 Claude의 판단과 상관없이 반드시 실행되어야 하는 명령입니다. "항상 알아야 함"은 CLAUDE.md, "가끔 필요함"은 Skills, "절대 빠지면 안 됨"은 Hooks라고 기억하면 쉽습니다.
체크포인트가 있으면 git 커밋은 안 해도 되나요?
아닙니다. 체크포인트는 Claude의 파일 편집 도구로 바뀐 내용만 기록하고, Bash 명령으로 수정·삭제된 파일은 기록하지 않습니다. 의미 있는 단위로 작업이 끝날 때마다 git에 커밋해 두는 것이 안전합니다.
마무리: 팁 하나만 고른다면
가장 먼저 익힐 습관은 /init으로 CLAUDE.md를 만들고 큰 작업은 플랜 모드로 시작하는 것입니다. 수준에 따라 다음 단계를 고르세요.
- 이번 주에 처음 써 본다면: 팁 1~5만 익혀도 충분합니다. 특히
Esc와/clear를 자주 쓰는 습관을 들이세요. - 이미 매일 쓴다면: 팁 7~11로 넘어가 반복 작업을 Skills로, 강제할 규칙을 Hooks로 옮기고
claude -p로 스크립트에 붙여 보세요.
더 자세한 내용은 한국어로 번역된 Claude Code 모범 사례 공식 문서에서 확인할 수 있습니다.
함께 보면 좋은 영상
- Claude Code best practices | Code w/ Claude (Anthropic, 2025년 5월 발표). 2025년 영상이라 일부 키워드 설명이 현재 문서와 다를 수 있습니다.
- Mastering Claude Code in 30 minutes (Anthropic). Claude Code를 만든 Boris Cherny가 직접 설명합니다.
- How we Claude Code (Claude 공식 채널). Anthropic 엔지니어들이 저장소를 어떻게 설정하는지 보여 줍니다.
글쓴이
주홍철은 네이버 출신 개발자이자 AI 핀테크 스타트업 어비스(AVISS)의 대표입니다. 경제·증시 분석 AI, AI 에이전트, 데이터 파이프라인을 직접 설계하고 개발하며, 『클로드 코드 제대로 시작하기』(길벗)와 『면접을 위한 CS 전공지식 노트』를 썼습니다. 어비스에서는 기업 대상 AX 도입 교육으로 Claude Code 실습 과정을 운영하고 있습니다. 다른 글은 어비스 블로그에서 볼 수 있으며, 글에 대한 정정 요청이나 문의는 [email protected]으로 보내 주세요.
