02-구조

02. 구조 — 명령 카테고리와 라이프사이클

명령의 다섯 카테고리

Claude Code의 입력은 어떻게 처리되느냐 기준으로 다섯 가지로 나뉜다.

카테고리	입력 형태	처리 주체	예
자연어(Prompt)	일반 텍스트	모델 + 도구 루프	이 함수에 테스트 추가해줘
슬래시(Slash)	/이름 [args]	하네스가 가로채서 스킬/번들 명령 실행	/init, /compact, /agents
Bang(셸)	!cmd	셸 직접 실행, 결과는 컨텍스트로 들어감	!git status
파일 멘션	@경로	하네스가 파일을 읽어 컨텍스트에 prepend	@src/api/handler.ts
키 단축	shift+tab, esc, ctrl+r	UI 상태 토글(Plan/메뉴/히스토리)	Plan 모드 진입

이 표는 단순 외우기가 아니다. 디버깅할 때 “왜 모델이 이 파일을 못 읽었지?”라는 질문은 “내가 자연어로 파일명을 적었나, @로 멘션했나?”의 차이로 갈리는 경우가 많다.

세션 라이프사이클

1. SessionStart — 글로벌 + 프로젝트 + 로컬 settings.json이 머지된다(로컬 우선). CLAUDE.md가 컨텍스트 윈도우에 prepend된다. SessionStart hook이 있으면 발화한다.
2. 사용자 입력 → 모델이 도구 호출(파일 읽기/쓰기/Bash) 결정 → PreToolUse hook → 권한 검사 → 실행 → PostToolUse hook.
3. Stop — 모델이 응답을 마치면 Stop hook이 발화한다. 자동 commit, lint, 알림 등을 건다.
4. SessionEnd — clear, resume, logout 등 종료 사유에 따라 다른 매처가 발화한다.

이 라이프사이클을 알면 “어디에 hook을 거는가”가 결정된다. 이 챕터는 명령에 집중하므로 hook 패턴은 07에서 깊게 다룬다.

비인터랙티브 호출의 형태

# 단발 실행, JSON으로 결과 받기
claude -p "src/ 안의 console.log를 logger.debug로 바꿔줘" \
  --output-format json \
  --max-turns 5

• --output-format json — 스크립트가 파싱하기 쉬운 형태로 출력.
• --max-turns N — 도구 루프 최대 회수. 안전 가드.
• --permission-mode auto|deny|approve — 사람 승인 없이 어떻게 처리할지. CI에서는 auto+엄격한 allowedTools가 일반적.

명령 vs 스킬의 통합

2025년 말부터 Anthropic은 슬래시 명령과 스킬을 한 시스템으로 머지했다. 공식 문서가 명시한다:

“Custom commands have been merged into skills. A file at .claude/commands/deploy.md and a skill at .claude/skills/deploy/SKILL.md both create /deploy and work the same way.”
의역: “커스텀 명령은 스킬로 통합되었다. .claude/commands/deploy.md 와 .claude/skills/deploy/SKILL.md는 둘 다 /deploy를 만들고 동작도 같다.”
— Anthropic 공식 문서, Extend Claude with skills

즉, 04장(슬래시 커맨드)와 05장(Skills)는 사실상 같은 시스템의 두 단계다. CLI를 외울 때부터 이 통합을 머릿속에 넣어두면 나중에 마이그레이션할 일이 없다.