Claude Code 치트시트

/deep-research는 Claude Code에 기본 번들된 동적 워크플로우다(v2.1.154~). 한 질문을 받으면 여러 각도로 웹 검색을 분산해 출처를 모으고, 같은 주장을 서로 다른 출처가 받쳐 주는지 교차 검증한 뒤 살아남은 주장만 모아 인용된 리포트로 돌려준다.
보통 대화로 같은 일을 하면 매 응답이 Claude 컨텍스트로 들어와 답 한 줄을 위해 수백 KB가 쌓이는데, 이쪽은 결과만 컨텍스트에 들어와 세션이 가벼운 상태로 유지된다.

활용

• 한 줄로 시작 → 백그라운드로 돌고 세션은 다른 작업 가능:

  /deep-research What changed in the Node.js permission model between v20 and v22?

  복사
• 진행 상황은 /workflows에서 → 선택 후 Enter로 단계별 에이전트·토큰·경과 펼침 ([[workflows]])
• 권한 모드별 승인 흐름 — default/acceptEdits는 매 런 묻고, auto는 첫 런 한 번만, bypassPermissions·claude -p·SDK는 안 묻고 즉시 시작

주의

• WebSearch 툴이 활성화돼 있어야 한다 — 권한 설정 또는 관리 정책에서 막혀 있으면 실패.
• 한 런은 에이전트 동시 최대 16개 / 총 1,000개 한도 — 폭주 방지선 안에서만 돈다.
• 토큰이 일반 대화보다 훨씬 많이 든다 — 큰 질문 전에 좁은 슬라이스로 비용 가늠.

/workflows는 백그라운드에서 돌고 있거나 끝난 동적 워크플로우 런을 한 화면에서 본다(v2.1.154~). 단계별 에이전트 수·토큰·경과 시간이 줄지어 뜨고, 각 단계를 펼치면 그 에이전트가 무엇을 했는지 그대로 읽힌다.
워크플로우는 "10~수백 개 에이전트가 하나의 작업을 분담하는" 큰 단위라 세션 안에 다 띄우면 막혀 버리는데, 이 명령으로 세션은 그대로 두고 진행 상황만 들여다보거나 위험한 단계만 골라 멈출 수 있다.

활용

• 진행 중인 워크플로우 목록 보기 → /workflows (↑/↓로 선택, Enter로 진행 뷰 진입)
• 단계 안 들어가서 한 에이전트만 멈추기 → 단계 펼친 뒤 해당 행에서 x
• 전체 런 일시 정지·재개 → 런에 포커스 두고 p (재개는 캐시된 결과를 다시 쓰므로 무료)
• 마음에 든 런을 명령으로 저장 → /workflows에서 선택 후 s:

  .claude/workflows/    프로젝트 공유 (clone하면 모두 사용)
  ~/.claude/workflows/  내 홈, 모든 프로젝트

  복사
• 입력 박스 아래 task panel에서 한 줄 진행 요약 보고 ↓ → Enter로 같은 뷰 펼치기

주의

• 워크플로우는 같은 Claude Code 세션 안에서만 resume된다 — 세션 종료 시 다음 시작은 처음부터.
• 런이 토큰을 많이 쓴다 — 큰 작업 전 작은 슬라이스(디렉토리 하나·좁은 질문)에서 비용 확인하고, /workflows 뷰에서 x로 언제든 중단 가능.
• 끄려면 disableWorkflows: true 또는 CLAUDE_CODE_DISABLE_WORKFLOWS=1 → [[disable-workflows]] 참고.

claude plugin init <name>은 ~/.claude/skills/<name>/ 아래에 .claude-plugin/plugin.json 매니페스트와 시작용 SKILL.md를 깔아 놓는 명령이다(v2.1.157~). 다음 세션을 열면 <name>@skills-dir 소스로 자동 로드돼 /plugin과 claude plugin list에 등장한다.
마켓플레이스에 올리거나 --plugin-dir를 매번 넘기는 단계 없이 바로 굴린다 — "커뮤니티에 풀 만큼은 아닌데 여러 프로젝트에서 같이 쓰고 싶은 도구"를 가장 짧게 시작하는 길.

활용

• 최소 스캐폴드 → claude plugin init my-helper
• 스킬·훅 폴더까지 함께 만들기:

  claude plugin init my-helper --with skills hooks

  복사
• 가능한 --with 값: skill · agent · hook · mcp · lsp · output-style · channel
• 기존 스캐폴드 덮어쓰기 → claude plugin init my-helper --force
• 새 세션에서 자동 로드, /plugin과 claude plugin list에 my-helper@skills-dir로 표시

주의

• 같은 이름의 마켓플레이스 플러그인을 이미 깐 상태라면 충돌 — 둘 중 하나를 비활성화 필요.
• 관리 설정에서 strictKnownMarketplaces나 blockedMarketplaces에 {"source": "skills-dir"}가 박혀 있으면 plugin init이 파일 쓰기 전에 실패한다 (조직 정책으로 차단됨).
• 스캐폴드 위치는 ~/.claude/skills/ 고정 — 프로젝트 스코프로 쓰려면 거기서 만든 뒤 별도로 옮기거나 마켓플레이스로 정식 배포.

/plugin list는 인터랙티브 세션 안에서 설치된 플러그인을 인라인 한 줄로 보여 주는 명령이다(v2.1.163~). 버전·출처 마켓플레이스·활성 상태가 같은 행에 깔린다.
/plugin 메뉴를 띄우지 않고 빠르게 무엇이 들어 있는지 확인할 때 쓰고, --enabled·--disabled로 상태를 한 번에 좁힐 수 있다.
CLI의 claude plugin list와 같은 데이터셋을 다른 진입점에서 본다.
/plugin 메뉴를 열어 탭을 옮길 필요 없이 한 줄 명령으로 인벤토리가 잡힌다.

활용

• 설치된 플러그인 즉시 확인 → /plugin list (또는 짧게 /plugin ls)
• 지금 켜진 것만 추리기 → /plugin list --enabled
• 꺼진 채 남아 있는 것만 확인 → /plugin list --disabled
• CLI 쪽 동일 출력 → claude plugin list (대화 밖 스크립트 용도). JSON으로 받기:

  claude plugin list --json

  복사

주의

• --enabled·--disabled·ls 단축은 인터랙티브 /plugin list에서만 인식된다 — claude plugin list CLI는 --json·--available만 받는다.
• --available(마켓플레이스 미설치분 포함)은 CLI 쪽에서 --json과 함께만 동작한다.

.mcp.json으로 프로젝트 단위 등록된 MCP 서버 중 아직 승인을 받지 않은 항목은 claude mcp list·claude mcp get <name>에서 ⏸ Pending approval로 표시되고, 거절한 서버는 ✗ Rejected로 남는다.
출력이 파이프로 흘러가는 상황에서도 동일하게 보류 표기만 나가고 연결·기동은 일어나지 않는다 — 스크립트·CI 파이프라인이 무심결에 신규 서버를 자동 승인·실행하던 회피 경로가 막힌다.

승인하려면 인터랙티브 claude 세션에서 신뢰 다이얼로그를 띄워 명시적으로 통과시켜야 한다.
한 번 거절한 서버는 claude mcp reset-project-choices로 선택 초기화해 다시 검토할 수 있다.

활용

• .mcp.json 신규 서버를 확인만 하고 싶을 때 → claude mcp list로 ⏸ Pending approval 줄만 보고 끝내기 — 연결 안 됨
• CI 잡에서 MCP 인벤토리 덤프할 때:

  claude mcp list | grep "Pending approval"   # 새로 추가된 서버만 골라내 알림

  복사
• 한 번 거절했던 서버 다시 검토 → claude mcp reset-project-choices 후 인터랙티브 세션에서 재승인

주의

• 보류·거절 표시 동작은 .mcp.json(project scope) 서버에만 해당. 로컬·유저 스코프 서버는 추가 시점에 본인이 직접 등록한 것이므로 별도 승인 절차 없이 바로 연결된다.

(v2.1.157~) /plugin 슬래시 명령의 인자에 Tab 자동완성이 붙었다.
서브커맨드(install·enable·disable·uninstall 등), 현재 설치된 플러그인 이름, 그리고 알려진 마켓플레이스의 플러그인까지 한 인터페이스에서 후보로 뜬다.
플러그인 이름이나 마켓플레이스 URL을 외워 두지 않아도 Tab 한 번이면 후보가 좁혀진다 — 잘못 친 이름 때문에 "plugin not found"가 뜨는 빈번한 실수가 사라진다.

활용

• 서브커맨드 빠르게 → /plugin <Tab> (install·enable·disable·uninstall 등 후보)
• 설치된 플러그인 이름 → /plugin disable <Tab> (현재 enable 상태인 것만 후보)
• 마켓플레이스에서 검색 → /plugin install <Tab> (알려진 마켓플레이스의 플러그인 이름이 검색 후보로)
• 부정확한 입력 방지 → 이름 일부만 치고 <Tab>으로 정확한 표기 확정

주의

자동완성은 현재 세션이 인지하는 마켓플레이스만 검색한다.
새 마켓플레이스에 막 들어간 플러그인은 마켓플레이스를 먼저 claude plugin marketplace add로 등록한 뒤에야 후보로 뜬다.

/reload-skills는 세션을 종료하지 않고 skill·명령 디렉토리를 다시 훑어 디스크상에서 추가·수정·삭제된 스킬을 현재 세션이 인식하도록 한다(v2.1.152~). 실행 후 사용 가능한 스킬 개수와 새로 추가·제거된 수를 보고한다.
스킬 파일을 편집하거나 팀 스킬 저장소를 git pull로 당겨도 세션을 끊을 필요가 없다 — 다음 프롬프트부터 바로 쓸 수 있다.

활용

• .claude/skills/에 새 스킬을 막 추가했을 때 → /reload-skills로 즉시 인식
• 팀 스킬 저장소를 최신화한 직후 → git pull && /reload-skills 흐름으로 동료가 올린 변경 반영
• 스킬 frontmatter(description·allowed-tools 등)를 수정했을 때 → 재시작 대신 /reload-skills 한 번

주의

세션 시작 훅이 설치한 스킬을 같은 세션에 자동 노출하려면 [[session-start-reload-skills]] 쪽 reloadSkills: true를 쓰면 된다 — 사용자가 /reload-skills를 따로 입력할 필요 없이 첫 프롬프트부터 잡힌다.

/config → Editor mode에서 vim 모드를 켰을 때, NORMAL 모드에서 /를 누르면 표준 모드의 Ctrl+R과 똑같이 history search가 열린다(v2.1.152~). bash·zsh의 vi-mode와 동작이 맞는다.
vim 모드를 쓰면서 이전 프롬프트를 다시 부르려고 INSERT로 돌아가 Ctrl+R을 누르거나 NORMAL 모드를 벗어나야 했던 흐름이 끊기지 않는다.

활용

• NORMAL 모드에서 직전 명령 다시 부르기 → /로 history 검색 열기 → 검색어 입력 → Enter로 실행
• NORMAL ?는 그대로 vim 동작인 help 메뉴 — /만 history search로 매핑됨
• 검색 도중 다음 매치로 이동 → Ctrl+R (HistorySearch 컨텍스트의 historySearch:next)

주의

vim 모드를 끄면 NORMAL 모드가 없으므로 이 동작도 사라진다.
표준 모드에서 동일한 검색은 Ctrl+R. 키바인딩을 커스터마이즈해서 Ctrl+R을 바꾼 경우, NORMAL /는 여전히 history search 액션을 호출한다 — 액션이 동일하므로 함께 변경된 매핑을 따른다.

스킬 프론트매터의 disallowed-tools는 스킬이 활성화된 동안 Claude에게 노출되는 툴 풀에서 나열된 것을 빼버린다(v2.1.152~). [[allowed-tools]]가 화이트리스트라면 이쪽은 블랙리스트 — 모델이 애초에 해당 툴을 호출할 수 없게 만든다.
사용자가 다음 메시지를 보내면 제한이 풀린다.
백그라운드 루프나 자율 스킬이 절대 건드리면 안 되는 툴(예: AskUserQuestion)을 처음부터 보이지 않게 할 때 적합하다.

값은 공백·콤마 구분 문자열 또는 YAML 리스트.

활용

• 자율 루프 스킬에서 사용자에게 묻지 못하게 막기:

  ---
  name: nightly-triage
  description: Triage overnight failures and write a report
  disallowed-tools: AskUserQuestion
  ---

  복사
• 읽기 전용 검토 스킬에서 쓰기 도구 차단 → disallowed-tools: Edit, Write, NotebookEdit
• 짧은 비대화 스킬이 끝없는 추가 작업으로 번지는 것 방지 → 해당 스킬 동안만 Bash 빼두기

주의

• 제한은 스킬 활성 턴 동안만 — 사용자가 다음 메시지를 보내면 풀린다. 영구 차단은 권한 설정의 deny 규칙으로.
• allowed-tools와 같이 적으면 우선순위 충돌은 docs에 명시 없음 — 같은 툴을 양쪽에 두지 말 것.

if: "Bash(...)"로 좁힌 훅은 단일 호출뿐 아니라 &&·; 복합 명령, $()·백틱으로 감싼 서브쉘 안쪽까지 검사한다.
npm test && git push나 echo $(rm -rf /)처럼 위험한 서브커맨드를 숨겨도 패턴이 적중하면 훅이 발화한다.
명령 이름까지만 좁힌 패턴은 정확히 매칭하고, 인자까지 제한한 패턴은 $()·백틱·$VAR 안에선 fail-open — 변수 치환 결과를 정적으로 알 수 없을 때 안전 쪽으로 항상 발화한다.

활용

• 매칭 사례 (docs 표 그대로):

  if 패턴	Bash 명령	발화?	이유
  Bash(git *)	FOO=bar git push	✅	앞 변수 할당이 벗겨지고 git push 매칭
  Bash(git *)	npm test && git push	✅	각 서브커맨드 별도 검사
  Bash(rm *)	echo $(rm -rf /)	✅	$()·백틱 안쪽도 검사
  Bash(rm *)	echo $(date)	❌	안쪽 명령이 rm *에 안 맞음
  Bash(git push *)	echo $(date)	✅	인자까지 제한한 패턴은 $()에서 fail-open

• 위험한 호출을 차단하려면 명령 이름 단위로 좁힌다 → Bash(rm:*) deny + if: "Bash(rm *)" 훅을 같이 걸어 서브쉘 우회까지 차단

• 인자 패턴(Bash(git push *))이 들어가면 무관한 명령에서도 훅이 떠 비용이 늘 수 있음 — 정말 필요한 곳에만 사용

주의

이 매칭 규칙은 if 필드에만 적용된다(PreToolUse·PostToolUse·PermissionRequest·PermissionDenied 같은 툴 이벤트에서). matcher 필드는 툴 이름만 본다.
(v2.1.163~ 인자 패턴의 fail-open이 명시적으로 문서화됐다.)