Claude Code, 이 여덟 개만 알면 절반은 쓴 것이다

Claude Code 개념을 20개씩 늘어놓은 카드가 자주 돌아다닌다. 대부분 실제로 있는 기능이고, 몇 개는 이름이 낡았거나 틀렸다.

처음 쓰는 사람에게 20개는 너무 많다. 순서대로 익히면 되는 여덟 개만 골랐다. 전부 공식 문서에서 확인한 것이고, 문서 주소도 같이 붙였다.

1. CLAUDE.md — 매번 읽히는 규칙

저장소 루트에 두는 파일이다. 세션을 시작할 때마다 읽는다. 쓰는 언어, 빌드 명령, 금지 사항처럼 "매번 말하기 귀찮은 것"을 적어 둔다.

주의할 게 하나 있다. 공식 문서가 200줄 이하를 권한다. 길어지면 오히려 지켜지지 않는다. 개인 취향은 CLAUDE.local.md에 따로 적고 .gitignore에 넣는다. 이 파일은 지금도 동작한다. "없어졌다"고 적힌 자료가 있는데 틀렸다.

2. rules/ — CLAUDE.md가 길어질 때

.claude/rules/ 폴더에 주제별로 쪼개 넣는다. 여기가 핵심인데, 각 파일 머리에 paths:로 글롭을 적으면 그 파일이 작업에 들어올 때만 규칙이 로드된다.

프런트엔드 규칙은 프런트엔드 파일을 만질 때만 들어온다. 컨텍스트를 아끼는 공식 방법이고, "CLAUDE.md가 200줄에 가까워지면 rules로 쪼개라"가 공식 권고다. 이걸 커뮤니티 관례라고 적은 카드가 있는데 공식 기능이다.

3. Skills — 반복 작업을 폴더로 만들기

SKILL.md 하나로 워크플로를 정의한다. /이름으로 부르거나, 상황에 맞으면 알아서 불려 온다. 이름과 설명만 먼저 로드되고 본문은 필요할 때 들어온다. 그래서 스킬을 많이 만들어도 컨텍스트가 무거워지지 않는다.

옛 자료는 commands/(슬래시 명령)를 먼저 가르치는데, 공식 문서는 이제 이렇게 말한다. "명령과 스킬은 같은 메커니즘이다. 새로 만들 거면 skills/를 쓰라."

4. Subagents — 컨텍스트를 나눠 쓰기

.claude/agents/에 정의한다. 별도 컨텍스트에서 돌고 결과만 돌려준다. 코드 리뷰나 리서치처럼 "읽을 건 많지만 결론만 필요한" 일에 쓴다. 메인 대화가 파일 내용으로 더럽혀지지 않는다.

참고로 서브에이전트를 띄우는 툴 이름은 Task가 아니라 Agent다. 카드에 자주 틀리게 나온다.

5. Plan mode — 고치기 전에 계획부터

Shift+Tab으로 들어간다. 조사와 계획만 하고 파일을 쓰지 않는다. 남이 만든 코드에 손대야 할 때, 또는 요구사항이 아직 흐릴 때 먼저 켠다. 계획을 보고 승인한 다음에 실행으로 넘어간다.

6. Permissions — 무엇을 물어볼지 정하기

툴과 명령 단위로 허용·질문·거부를 정한다. 모드도 있다. 기본은 매번 묻는 ask, 편집만 자동 승인하는 acceptEdits, 계획만 하는 plan 등이다.

여기서 실무 팁 하나. 매번 승인 누르기가 지겨워서 전부 허용으로 돌리는 사람이 많은데, 그러지 말고 읽기 전용 명령만 허용 목록에 넣는 것부터 하면 체감이 크게 줄어든다.

7. Context window와 compaction — 대화가 길어질 때

컨텍스트가 차면 앞부분을 요약으로 압축한다. /compact로 직접 시킬 수도 있다. 길어진 세션에서 답이 흔들리기 시작하면 압축하거나 새 세션에서 다시 시작하는 게 빠르다.

/rewind는 다른 기능이다. 파일 스냅샷을 최근 100개까지 들고 있어서 대화나 코드, 또는 둘 다를 되돌린다. 단 bash로 지우거나 옮긴 파일은 추적하지 않는다. 이건 알고 써야 한다.

8. Hooks — 규칙을 말로 하지 않고 강제하기

특정 시점에 내 스크립트를 실행한다. "편집 후 포매터 실행", "커밋 전 린트"처럼 매번 부탁하는 대신 자동으로 돌게 만든다. settings.json의 hooks 키에 정의한다. .claude/hooks/ 폴더에 스크립트를 모으는 건 관례이고, 공식 구조도에는 그 폴더가 없다.

이벤트가 몇 개인지가 재미있다. 카드에는 보통 3~9개가 나오는데 공식 레퍼런스에는 28개가 있다. PermissionRequest, PostToolBatch, PreCompact, TeammateIdle 같은 건 거의 아무도 안 쓴다.

폴더 구조로 정리하면

your-project/
  CLAUDE.md              매번 읽히는 규칙 (200줄 이하)
  CLAUDE.local.md        개인 설정 (gitignore)
  .mcp.json              팀 공용 MCP 서버 — 루트에 둔다, .claude/ 안이 아니다
  .claude/
    settings.json        권한 · 훅 · 모델 · 상태줄
    settings.local.json  개인 오버라이드
    rules/               주제별 규칙 (paths: 로 조건부 로딩)
    skills/<name>/SKILL.md  반복 워크플로
    agents/              서브에이전트
    workflows/           다중 에이전트 오케스트레이션
    output-styles/       응답 방식 교체

카드에 안 나오지만 알아 둘 만한 것

Remote control — 로컬 세션을 폰이나 브라우저에서 이어받는다. 모든 플랜에서 된다
Channels — 텔레그램·디스코드·iMessage 이벤트를 돌고 있는 세션에 밀어넣는다
Agent teams / cross-session messaging — 세션끼리 메시지를 주고받는다
Sandboxing — bash 명령을 OS 수준에서 격리해 파일시스템·네트워크 범위를 제한한다
Worktrees — git worktree로 세션을 병렬로 돌린다. 서로 충돌하지 않는다

"Claude Code는 터미널 코딩 도구"라는 프레임이 이미 낡았다는 게 이 목록에서 보인다.

모델 쪽도 한 번 짚으면

Claude 공식 모델 문서 — Fable, Mythos, Opus, Sonnet, Haiku — 공식 모델 개요 문서. Opus·Sonnet·Haiku 위에 Fable 계열이 있다. 2026-09-18 확인.

"Opus / Sonnet / Haiku 세 가지"로 소개하는 자료는 낡았다. 현재는 Fable 5.1이 라인업 최상단이고, 컨텍스트도 Haiku 4.5만 200K이고 나머지는 1M이다.

그리고 budget_tokens로 extended thinking을 설정하는 예제가 여전히 돌아다니는데, 그 방식은 4.6 세대에서 폐기됐고 이후 모델은 받지 않는다. 지금은 adaptive thinking과 effort 파라미터다.

어디서부터 하면 되나

CLAUDE.md를 20줄쯤 쓴다. 빌드 명령과 금지 사항부터
읽기 전용 명령을 허용 목록에 넣는다
반복하는 일이 세 번 넘으면 스킬로 만든다
규칙이 길어지면 rules로 쪼갠다
자동으로 돌아야 하는 게 생기면 훅으로 옮긴다

이 순서면 카드 20장을 외우지 않아도 된다.

공식 문서: code.claude.com/docs · 폴더 구조: .claude 디렉터리 · 모델: platform.claude.com/docs/en/models/overview · 확인 기준일 2026-09-18