DDAMNOTE 블로그 입니다.

10 minute read

두 편의 유튜브 강의(코드팩토리 “Essential Claude Code Tips”, 코드 벡터 “클로드 코드 꿀팁 60”)를 직접 보고, Claude Code 공식 Best Practices 문서와 대조해 보완한 정리입니다. 중복을 제거하고 실제 워크플로 순서대로 재구성했으며, 신규 프로젝트를 시작할 때 체크리스트처럼 쓰려고 만들었습니다.

들어가며

Claude Code를 쓰다 보면 결국 두 가지로 갈린다. 기능을 몰라서 못 쓰는 경우와 워크플로가 잡히지 않아 효율이 안 나는 경우다. 이 글은 전자를 위한 카탈로그이자 후자를 위한 동선 정리다. 크게 여섯 갈래 — CLI 기본기, 인터랙티브 /command, CLAUDE.md, IDE 연동, 환경 확장(Hooks·Skills·Plugins), 고급 기능 + 공식 베스트 프랙티스 — 로 나눴다.

공식 문서가 거듭 강조하는 대원칙이 둘 있다. 첫째, 컨텍스트 윈도우는 빠르게 차고, 차오를수록 성능이 떨어진다 — 그래서 컨텍스트 관리가 가장 중요한 자원 관리다. 둘째, Claude가 스스로 검증할 수단(테스트·빌드·스크린샷)을 주라 — 그래야 “다 된 것처럼 보임”이 아니라 실제 통과 여부로 작업이 닫힌다. 아래 모든 팁은 결국 이 두 원칙으로 수렴한다.

1. CLI 기본기

터미널에서 Claude Code를 다루는 진입점들이다.

명령 설명
npm install -g @anthropic-ai/claude-code 설치
claude 실행 (폴더 신뢰 후 채팅창 진입)
claude "프롬프트" 실행과 동시에 프롬프트 입력
command \| claude 데이터 파이핑 (헤드리스 모드와 궁합 좋음)
claude -c / --continue 현재 디렉터리의 최근 세션 바로 이어가기
claude -r / --resume 세션 목록에서 골라서 진입
claude update 업데이트
--model <모델> 시작 모델 지정
claude -p "프롬프트" 헤드리스 모드 (인터랙티브 창 없이 응답)
--output-format json 헤드리스 출력을 JSON으로 — 멀티에이전트/프로그래매틱 연동에 핵심
--verbose 디버깅용 상세 로그

헤드리스 모드는 파이핑(|)과 결합하면 다른 도구의 출력을 그대로 주입해 자동화 파이프라인을 짤 수 있다. JSON 출력까지 더하면 후속 처리가 깔끔해진다. 세션이 여러 작업으로 나뉜다면 인터랙티브 모드에서 /rename으로 oauth-migration 같은 이름을 붙여 브랜치처럼 관리하면 --resume으로 찾기 쉽다.

2. 인터랙티브 모드 /command

처음 들어왔다면 /help부터. 아래는 자주 쓰게 되는 핵심들이다.

컨텍스트 관리 (가장 중요)

  • /clear — 대화 이력을 비우고 컨텍스트 윈도우를 확보한다. 새로운 주제로 넘어갈 때마다 습관처럼 실행. 환각 가능성도 낮아진다.
  • /compact — 대화를 요약·압축. 직접 쓰지 않고 컨텍스트를 넘기면 오토 컴팩트가 엉뚱한 시점에 끼어들어 내용이 망가질 수 있다(1장이 아니라 1.5장에서 요약하는 격). 적절한 시점에 직접 호출하자. /compact [유지할 내용]으로 초점을 지정할 수도 있다.

설정·모델·상태

  • /config — 오토 컴팩트, 투두리스트 등 각종 세팅.
  • /model — Opus/Sonnet 선택. Default 모드는 토큰 50%까지 Opus 후 Sonnet 전환($100 플랜은 20%가 한계), Opus Plan 모드는 플래닝만 Opus.
  • /status — 계정·시스템 상태. /doctor — 설치/환경 점검. /cost — (API 모드) 토큰·비용 확인.

프로젝트·메모리·권한

  • /init — 프로젝트 초기 분석 후 핵심을 CLAUDE.md에 저장. 프로젝트 시작 직후 필수.
  • # — CLAUDE.md에 빠르게 메모 추가(프로젝트/유저 메모리 선택).
  • /permissions — 도구 권한 관리.

협업·Git

  • /review — 연동된 Git 레포의 PR을 Claude가 리뷰.
  • /pr-comments — PR 코멘트를 전부 긁어와 개선점 분석.
  • /login / /logout — 계정 전환(멀티 계정 운영).

편의 기능

  • terminal-setup — Shift+Enter 줄바꿈 활성화.
  • vim 모드 — 채팅창에서 vim 키바인딩.
  • /agents — 커스텀 서브에이전트 관리(특정 작업에 특화된 에이전트를 미리 만들어 자동 호출).
  • /mcp — 연결된 MCP 상태 한눈에 확인.
  • output-style — 출력 스타일 변경(Explanatory, Learning 등 프리셋).
  • statusline — 하단 한 줄 정보 영역(예: 현재 모델명 고정 표시).

3. CLAUDE.md 마스터클래스

CLAUDE.md는 Claude가 매 대화 시작마다 읽는 특별한 파일이다. 빌드 명령, 코드 스타일, 워크플로 규칙처럼 코드만 봐서는 알 수 없는 영속적 맥락을 넣어둔다. /init으로 초안을 만든 뒤 다듬어 나가면 된다.

핵심 원칙: 짧게 유지하라

직관과 반대로, 공식 문서가 가장 강조하는 건 “많이 적기”가 아니라 “잘라내기“다. CLAUDE.md가 길어지면 실제 지시가 노이즈에 묻혀 Claude가 절반을 무시하게 된다. 각 줄마다 “이걸 지우면 Claude가 실수할까?”를 물어 아니라면 잘라낸다.

✅ 넣을 것 ❌ 뺄 것
Claude가 추측 못 할 Bash 명령 코드를 읽으면 알 수 있는 것
기본값과 다른 코드 스타일 규칙 이미 아는 표준 언어 관습
테스트 방법·선호 러너 상세 API 문서(링크로 대체)
레포 에티켓(브랜치·PR 규칙) 자주 바뀌는 정보
프로젝트 고유 아키텍처 결정 자명한 원칙(“깔끔하게 짜라”)
개발 환경 특이사항(필수 env var) 파일별 코드베이스 설명

규칙을 넣었는데도 Claude가 계속 어긴다면 파일이 너무 길어 규칙이 묻힌 것이다. 강조가 필요하면 IMPORTANT, YOU MUST 같은 표현으로 준수도를 높일 수 있다. git에 체크인해 팀과 공유하면 시간이 갈수록 가치가 누적된다.

파일 위치 (우선순위 순)

  • ~/.claude/CLAUDE.md — 모든 세션에 적용(내 전역 룰)
  • ./CLAUDE.md — 프로젝트 루트, git 체크인해 팀 공유
  • ./CLAUDE.local.md — 나만 쓰는 프로젝트 메모(.gitignore에 추가)
  • 상위 디렉터리 — 모노레포에서 root/CLAUDE.md와 root/foo/CLAUDE.md가 함께 로드됨
  • 하위 디렉터리 — 그 폴더의 파일을 읽을 때만 온디맨드로 로드 → 루트 비대화 방지의 핵심

(엔터프라이즈 레벨의 회사 전반 룰을 두는 위치도 별도로 존재한다.)

활용 팁

  • 파일 임포트 — @path/to/import 문법으로 다른 파일을 끌어올 수 있다. 예: Git workflow: @docs/git-instructions.md
  • 파일 태그 — 프롬프트에서 @로 정확한 파일 지정(절대·상대 경로 모두 가능).
  • 온디맨드 분리 — 가끔만 필요한 도메인 지식·워크플로는 CLAUDE.md에 넣지 말고 Skill로 빼라(아래 5장). 매 세션 로드되지 않아 컨텍스트를 아낀다.

4. IDE 연동

  • 플러그인/확장 설치 → 터미널과 자동 연동.
  • Ctrl/Cmd + Esc — 빠른 실행.
  • 코드를 하이라이트하면 그 영역이 자동으로 문맥에 주입.
  • VS Code·IntelliJ 등에서 diff 뷰 연동으로 변경사항 확인.
  • 파일 참조 단축키: Mac Cmd+Option+K, Windows Alt+Ctrl+K.
  • /ide — 현재 터미널이 아닌 다른 IDE와 연동.

5. 환경 확장 — Hooks · Skills · Plugins · Subagents

영상에는 거의 안 나오지만 공식 문서가 비중 있게 다루는, “한 번 세팅하면 계속 효과 보는” 확장 요소들이다. 신규 프로젝트 셋업 시 가장 투자 가치가 높은 영역.

Hooks (훅)

CLAUDE.md 규칙은 권고사항이라 안 지켜질 수 있다. 반면 훅은 워크플로의 특정 시점에 스크립트를 자동 실행하는 결정론적 장치라 동작이 반드시 일어난다. 예를 들어 “파일 편집 후 eslint 자동 실행”, “migrations 폴더 쓰기 차단”, “검증이 통과할 때까지 턴 종료를 막는 Stop 훅” 같은 것. .claude/settings.json에 정의하거나 /hooks로 확인하며, Claude에게 “파일 편집마다 eslint 돌리는 훅 작성해줘”라고 시키면 만들어준다. 무조건 매번 일어나야 하는 동작에 쓴다.

Skills (스킬)

.claude/skills/에 SKILL.md를 만들면 프로젝트·팀·도메인 특화 지식을 줄 수 있다. Claude가 관련 상황에 자동 적용하거나 /skill-name으로 직접 호출한다. 핵심은 CLAUDE.md는 매 세션 로드되므로 항상 적용되는 것만, 가끔만 필요한 건 스킬로 빼서 필요할 때만 로드시키는 분리다. 부수효과가 있어 수동 실행만 원하면 front matter에 disable-model-invocation: true.

---
name: fix-issue
description: Fix a GitHub issue
disable-model-invocation: true
---
GitHub 이슈를 분석·수정: $ARGUMENTS
1. gh issue view로 상세 확인 → 2. 관련 파일 탐색 → 3. 수정 → 4. 테스트 → 5. PR 생성

/fix-issue 1234처럼 인자와 함께 호출한다. (영상의 “스킬 크리에이터”는 이 SKILL.md를 대화로 만들어주는 도우미다.)

Subagents (서브에이전트)

.claude/agents/에 정의하는, 독립된 컨텍스트에서 도는 전문 보조 에이전트. 컨텍스트가 가장 중요한 자원이라는 점에서 강력한 도구다. 코드베이스 조사처럼 파일을 많이 읽는 작업을 서브에이전트에 맡기면, 그쪽 컨텍스트에서 탐색하고 요약만 보고해 메인 대화가 깨끗하게 유지된다. 조사뿐 아니라 검증에도 쓴다 — “이 코드 엣지케이스를 서브에이전트로 리뷰해줘”.

Plugins (플러그인)

/plugin으로 마켓플레이스를 둘러본다. 플러그인은 스킬·훅·서브에이전트·MCP 서버를 하나의 설치 단위로 묶어 설정 없이 추가해준다. 타입 언어를 쓴다면 code intelligence 플러그인으로 심볼 내비게이션·편집 후 자동 에러 감지를 붙일 수 있다.

무엇을 쓸지 헷갈릴 때: 매번 반드시 일어나야 하면 훅, 도메인 지식·재사용 워크플로면 스킬, 컨텍스트를 분리해 조사·검증하려면 서브에이전트, 외부 서비스 연동이면 MCP, 이걸 묶어 배포하면 플러그인.

이 선택을 한눈에 정리하면 다음과 같다.

Claude Code 확장 요소 선택 트리 — Hook, Skill, Subagent, MCP, Plugin

6. 고급 기능

기본기를 넘어선, 알아두면 차이가 나는 기능들이다.

리서치·대규모 작업

  • 딥 리서치 — 단순 검색이 아니라 소스 수집 → 크로스체크 → 검증 → 결과 생성을 단계별로 설계해 진행. /workflows로 현재 스텝 확인 가능. 검증 단계에서 잘못된 정보를 걸러주는 게 강점.
  • 울트라 코드 — effort 최상위 옵션. X-high + 워크플로 결합으로 다수 에이전트를 동시 생성해 분석·수정·검증·테스트까지 한 번에. 페이즈로 분할되어 진행된다.
  • 배치(/batch) — 5~30개 워커를 병렬 생성. 동일 패턴의 반복 작업에 최적.

배치 vs 다이나믹 워크플로

  • 배치: 같은 패턴의 여러 작업을 병렬로 나눠 실행 → 반복적·대량 작업에 유리
  • 다이나믹 워크플로: 복잡한 목표를 조사·실행·검증·결과합치까지 처리하며 그 과정조차 병렬화 → 논리적 판단이 중요한 작업에 유리

세션 운영

  • 백그라운드(bg) — 작업을 백그라운드로 보내고 터미널 해방. claude agent로 복귀, 에이전트 패널에서 세션 리뷰.
  • BTW(/btw) — 세션을 더럽히지 않고 질문. 공식 문서 기준으로는 답이 대화 이력에 들어가지 않는 별도 오버레이로 떠 컨텍스트를 키우지 않는다(영상에서는 F로 포크해 기존 컨텍스트를 공유하는 흐름으로 소개됐는데, 버전에 따라 동작이 다를 수 있다).
  • 리와인드(/rewind 또는 Esc Esc) — 특정 프롬프트로 되돌리기. 대화만/코드만/둘 다 복원, 또는 summarize from here(선택 지점부터 아래로 압축)·summarize up to here(처음부터 선택 지점까지 압축) 선택. 매 프롬프트가 체크포인트가 되고 세션을 넘어 유지된다. 단, 체크포인트는 Claude가 만든 변경만 추적하므로 git을 대체하지 않는다.
  • /copy — 직전 프롬프트를 그대로 복사. 드래그 선택 불필요(의외로 모르는 사람 많음).

웹 위임 / 추가 비용

  • 울트라 플랜(/ultraplan) — 세션이 아닌 웹으로 작업을 위임. 터미널이 해방되고, 웹 실행이 플래닝에 더 최적화돼 완성도 높은 플랜 생성(토큰 소모는 큼). 슬래시 없이 입력해도 동작.
  • 울트라 리뷰 — Extra Usage 활성화가 필요한 유료 기능(1회 약 $5, 무료 5회 제공). 가치는 프로젝트 중요도에 따라 판단.

프롬프트·스킬

  • 골(goal) — 변경 내용과 성공 조건을 명확히 정의해야 장시간 고완성도 작업이 가능. 메타프롬프팅 추천: “이 프로젝트를 ~로 바꾸는 골 프롬프트를 작성해줘”라고 하면 목표·배경·매핑 규칙·제약·성공 기준이 포함된 구조화 프롬프트를 만들어준다.
  • 스킬 크리에이터 — 스킬 생성 시 벤치마킹, 리소스 절감량, 그리고 해당 스킬이 모델 기본 능력으로 흡수돼 곧 deprecate될지까지 알려준다. 작업하던 같은 세션에서 만들면 정확도가 높다.
  • 퓨어 퍼미션스 프롬프트 — skip-permissions 모드를 꺼리는 사람용. 지금까지 안전하게 승인한 작업을 분석해 allow-list를 생성, 반복 권한 질문을 줄여준다.
  • 코드 리뷰 — 리뷰 에이전트·목표 지정 가능. 리뷰에 최적화돼 더 좋은 리포트. 머지 전 추천.

기타

  • /powerup — 애니메이션과 함께 기능 사용법을 알려주는 튜토리얼.
  • /radio — 24시간 바이브 코딩용 라디오 재생.
  • /team-onboarding — 트랜스크립트를 전부 읽고 새 팀원에게 가르칠 내용을 정리(체크리스트 생성). 세션 작업 기록 용도로도 변형 가능.

7. 앤트로픽 공식 베스트 프랙티스

가장 실전 가치가 높은 부분. 공식 권장 워크플로의 핵심은 분석·계획을 구현과 분리하고, 검증이 통과할 때까지 스스로 반복시키는 것이다.

Explore → Plan → Code → Commit 워크플로와 검증 루프

  • gh CLI(Git CLI) 설치 — 커밋·롤백·PR 등 복잡한 Git 워크플로를 Claude가 알아서 처리.
  • MCP 적극 활용 — Supabase, Playwright 등 Claude가 직접 못 하는 영역을 확장. 사용자 레벨에 정의하면 전 프로젝트 공통 사용.
  • 커스텀 슬래시 커맨드 — 자주 쓰는 명령을 저장해 반복 사용. $ARGUMENTS로 인자 받기. 사용자/프로젝트 스코프 구분.
  • Explore → Plan → Code → Commit 순서 준수 — 대화 전체가 한 번에 컨텍스트에 들어가므로, 충분히 분석·계획한 뒤 실행·커밋. plan mode에서 탐색·계획만 하다가(Ctrl+G로 계획을 에디터에서 직접 편집 가능) 모드를 빠져나와 구현하면 “엉뚱한 문제를 푸는” 실수를 막는다. 단 타이포 수정처럼 한 문장으로 diff를 설명할 수 있는 작업이면 계획 단계는 생략하고 바로 시키는 게 낫다.
  • 검증 수단을 먼저 줘라(가장 중요) — Claude는 “다 된 것처럼 보이면” 멈춘다. 테스트·빌드 종료코드·린터·스크린샷 비교처럼 통과/실패 신호를 주면 스스로 통과할 때까지 반복한다. 한 프롬프트 안에서 “구현 후 테스트 돌려라”로 시키거나, 세션 단위면 /goal의 성공 조건으로 걸면 별도 평가자가 매 턴 재확인한다. 성공을 주장하지 말고 증거(테스트 출력·실행 결과)를 보이게 하라.
  • 씽킹 토큰(레거시 참고) — 예전 가이드의 think < think hard < think harder < ultrathink 매직워드로 사고 토큰을 늘리는 방식이 있었다. 여전히 동작할 수 있으나, 현재 공식 best-practices는 이 매직워드 대신 plan mode를 전면에 둔다. 복잡한 작업은 plan mode + 명확한 계획으로 접근하는 걸 권장.
  • TDD — 예상 입출력 기반 테스트를 먼저 작성 → 실패 확인 → 구현 → 통과까지 이터레이트.
  • 스크린샷 활용 — Playwright/Puppeteer로 페이지 캡처 후 주입하며 반복하면 결과물 품질이 크게 오른다.
  • 권한 인터럽트 줄이기 — 매번 승인 클릭은 결국 검토가 아니라 그냥 클릭이 된다. 공식 권장은 세 가지: auto mode(별도 분류 모델이 위험한 것만 차단), permission allowlist(npm run lint 등 안전한 명령만 허용), /sandbox(파일시스템·네트워크를 제한하는 OS 레벨 격리). claude --permission-mode auto -p "fix all lint errors"처럼 비대화 실행에도 쓴다. (구버전의 --dangerously-skip-permissions는 이름 그대로 위험하니 동작을 완전히 이해한 뒤에만, 가급적 sandbox/auto mode로 대체.)
  • Claude를 선생님으로 — 새 코드베이스는 전반 → 세부 순으로 top-down 질문.
  • 프롬프트는 항상 상세하게 — “테스트 작성해줘”보다 “sample 파일의 테스트 코드 작성, 로그인 상태 헤더 포함, 모킹 금지”처럼.
  • 이미지 전달 — 드래그앤드롭 또는 Ctrl+V (Mac에서도 붙여넣기는 Cmd+V가 아니라 Ctrl+V).
  • @ 파일 태그 + Tab 내비게이트.
  • ESC를 두려워 말기 — 엉뚱한 방향이면 즉시 취소해 컨텍스트 오염을 막는다.
  • 롤백 명령 — 커밋/변경사항 롤백은 설명만 하면 Claude가 잘 처리.
  • 체크리스트·스크래치 패드 — 멀티스텝 작업은 마크다운 체크리스트로 시키면 롱러닝 태스크 수행력이 올라간다.
  • 작업과 검증 분리 + 어드버서리얼 리뷰 — 코딩 후 /clear 하거나 별도 서브에이전트로 검증하면 다른 관점을 얻는다. 코드를 짠 세션은 자기 코드에 편향되므로, fresh 컨텍스트의 리뷰어가 diff만 보고 평가하게 하라. 내장 /code-review 스킬은 현재 diff의 버그를 새 서브에이전트로 검토해 보고한다. (리뷰어는 시키면 항상 뭔가를 찾아내니, “정확성·요구사항에 영향 주는 gap만 보고하라”고 제한해 과도한 엔지니어링을 막는다.)
  • 큰 기능은 Claude가 나를 인터뷰하게 하기 — 최소 프롬프트로 시작해 AskUserQuestion 도구로 기술 구현·UI/UX·엣지케이스·트레이드오프를 인터뷰하게 한 뒤 SPEC.md로 스펙을 뽑고, 새 세션에서 깨끗한 컨텍스트로 실행한다. 좋은 스펙은 관련 파일·인터페이스를 명시하고, 범위 밖을 못박고, end-to-end 검증 단계로 끝난다.
  • 워크트리 — 브랜치별 독립 작업 + PR 머지로 동시 작업 플로우 구성. Writer/Reviewer 패턴(한 세션은 구현, 다른 세션은 리뷰)이나 테스트 작성/통과를 나누는 데 유용.

신규 프로젝트 시작 체크리스트

위 내용을 새 프로젝트 시작 동선으로 압축하면 이렇다.

  1. claude 실행 → /init으로 CLAUDE.md 초안 생성, 짧게 유지하며 다듬기
  2. CLAUDE.md를 폴더 단위로 온디맨드 분리(루트는 가볍게), 가끔 쓰는 지식은 Skill로
  3. gh CLI 설치, 필요한 MCP 사용자 레벨 등록
  4. 반드시 매번 일어나야 하는 동작은 Hook으로, 자주 쓰는 작업은 커스텀 슬래시 커맨드/스킬로
  5. 권한은 auto mode / /sandbox로 인터럽트 줄이기
  6. 작업은 Explore → Plan(plan mode) → Code → Commit, 복잡한 건 plan mode + 명확한 계획/골/워크플로
  7. 검증 수단(테스트·스크린샷)을 먼저 주고, 새 주제마다 /clear, 검증은 fresh 서브에이전트로 분리

마치며

기능은 많지만 결국 한 곳으로 수렴한다. 컨텍스트를 깨끗하게 관리하고(/clear·/compact·CLAUDE.md), Claude가 스스로 검증하게 하며(테스트·스크린샷), 작업 동선을 분리·구조화하는 것 말이다. CLI 명령이나 슬래시 커맨드는 이 큰 그림을 거드는 도구일 뿐이고, 정작 차이를 만드는 건 Hooks·Skills·Plugins처럼 “환경에 미리 투자해두는” 요소들이다.

기능을 전부 외울 필요는 없다. 새 프로젝트를 셋업할 때 위 체크리스트를 한 번씩만 따라가도 체감 효율은 충분히 달라진다. 나머지 기능들은 그때그때 필요할 때 이 글과 공식 문서를 다시 펼쳐 찾아 쓰면 그만이다.

Comments

You May Also Enjoy