Claude Code 계획 모드와 권한 설정은 수정 전에 정한다

코딩 에이전트는 의욕이 넘치는 신입 개발자와 비슷하다. 문제를 하나 보여 주면 “바로 고칠게요”라며 파일을 바꾸기 시작한다. 처음 보는 코드베이스에서 이렇게 시작하면 무엇이 왜 바뀌었는지 따라가기 어렵다. Claude Code로 코드를 고치기 전에 네 가지를 먼저 정한다. 코드 탐색은 Explore 에이전트에 맡겨 메인 대화를 비워 두고, 진단 기준은 스킬로 주고, 요구사항과 수정 방향은 인터뷰나 계획 모드로 합의하고, 무엇을 묻지 않고 실행할지는 권한 모드와 설정 파일로 정한다

1편의 컨텍스트 개념을 안다고 가정한다. 다 읽으면 작업마다 모델과 추론 수준을 고르고, 수정 전에 어느 단계까지 사람이 확인할지 설정으로 정할 수 있다

작업 무게에 맞춰 모델과 effort를 고른다

/model에서 모델을 고르고, 같은 화면에서 좌우 방향키로 effort를 바꾼다. effort는 모델이 문제에 들이는 추론의 깊이를 조절하는 설정이다. 단계는 low, medium, high, xhigh, max이고 모델에 따라 일부가 없다. 기본값은 effort를 지원하는 모델에서 high인데, Opus 5.5는 medium, Opus 4.7은 xhigh가 기본이다(model-config)

강의에서는 effort를 바꾸자 새 세션에도 그 값이 유지됐다. 현재 문서 기준으로 방향키로 고른 뒤 Enter를 누르면 모델별 기본값으로 저장되고, s를 누르면 이번 세션에만 적용된다. max는 환경변수 CLAUDE_CODE_EFFORT_LEVEL로 지정하지 않는 한 세션 한정이다

강사는 일상 작업에는 Sonnet을 쓰고, 가장 강한 모델인 Fable은 하루 몇 번 아키텍처 판단이나 큰 버그, 대규모 리팩터링에만 쓴다고 했다. 강한 모델과 높은 effort는 구독 한도를 빨리 소모하고 응답도 느리다. 파일 몇 개를 옮기거나 CSS를 고치는 일에는 필요 없다. 진단처럼 놓치면 비용이 큰 작업에 강한 설정을 쓴다

advisor는 가벼운 모델이 막힐 때 강한 모델에게 묻게 한다

/advisor는 작업 모델보다 강한 모델을 조언자로 지정한다. 문서의 설명으로는 Claude가 접근 방식을 정하기 전, 같은 오류가 반복될 때, 완료를 선언하기 전 같은 시점에 두 번째 모델에게 묻는다. 조언자 모델은 사람이 고르고, 부를지는 Claude가 판단한다(advisor)

/model sonnet
/advisor opus

주 모델은 Sonnet, 조언자는 Opus로 두는 조합이다. 문서도 이 조합을 흔한 예로 든다. 조언자 호출은 조언자 모델 요율로 계산되어 요금제 사용 한도에 포함된다

강의에서 advisor를 켜고 Workers 코드 리팩터링을 맡겼지만 조언자를 한 번도 부르지 않았다. 켜 둔다고 반드시 호출하는 것은 아니라는 뜻이고, 호출 시점을 Claude가 정한다는 문서 설명과 맞는다. 현재 문서 기준으로 advisor는 실험 기능이며 Anthropic API에서만 동작한다. 조언자는 주 모델과 같거나 더 강해야 하고 Haiku는 조언자가 될 수 없다

코드 탐색은 Explore 에이전트에 맡긴다

처음 보는 코드는 구조부터 파악해야 한다. 강의에서는 예약 기능을 조사하도록 다음과 같이 요청한다

예약 처리 흐름을 정리해 줘. 예약 데이터는 어디서 읽는지, 상태는 어떻게 처리되는지,
어떤 컴포넌트가 예약 UI를 렌더링하는지, 같은 규칙이 여러 곳에 중복되어 있는지 알려 줘.
Explore 에이전트를 사용해 줘.

마지막 줄이 없으면 메인 대화가 직접 파일을 읽는다. 그동안 새 메시지는 대기열에 쌓이고, 읽은 파일과 디렉터리 목록이 전부 메인 컨텍스트에 남는다. Explore를 쓰면 탐색이 별도 컨텍스트에서 돌고 메인 대화에는 보고서만 돌아온다

[메인 대화] ── "예약 흐름 조사, Explore 사용"
    │
    ├─▶ [Explore 에이전트: 별도 컨텍스트]
    │      파일 읽기 × N, 검색 × N, 디렉터리 조회 × N
    │      └─▶ 보고서 1건 반환
    ▼
[메인 대화] 에는 보고서만 남는다

그림의 요점은 메인 대화에 쌓이는 양이다. 탐색 과정이 길수록 차이가 커진다. Explore는 읽기 전용 도구만 쓰며 Write와 Edit가 막혀 있다(sub-agents). 실행 중인 작업은 Ctrl+B로 백그라운드에 보낼 수 있고, 그동안 메인 대화를 계속 쓸 수 있다. 강의에서는 탐색 중에 “안녕”이라고 보내자 바로 답했다

백그라운드라고 무료는 아니다. 서브에이전트의 요청도 메인 대화와 같은 사용 한도에 포함된다. 절약되는 것은 메인 컨텍스트의 공간이다

예전에 쓴 서브에이전트 글에는 Explore가 Haiku로 동작한다고 적었다. 현재 문서에는 v2.1.198부터 Explore가 항상 Haiku로 도는 대신 메인 대화의 모델을 물려받는다고 되어 있다(Claude API에서는 Opus가 상한). 버전에 따라 달라진 동작이므로 두 글의 조건을 구분해 읽어야 한다

스킬은 필요할 때 읽는 지침 모음이다

탐색으로 구조를 파악했다면 코드가 어떤 기준에 못 미치는지 진단할 차례다. 강의에서는 Vercel의 React 모범 사례 스킬을 설치한다

스킬(skill)은 특정 작업에 쓸 지침과 참고 자료를 담은 폴더다. 열어 보면 대부분 마크다운 파일이다. React 모범 사례 스킬의 SKILL.md에는 컴포넌트 작성 규칙이, 옆의 파일들에는 Effect Event를 의존성 배열에 넣지 말 것, 조건부 모듈 로딩 같은 세부 규칙이 들어 있다

설치는 Vercel의 skills CLI로 한다

npx skills add vercel-labs/agent-skills

설치할 에이전트와 범위를 묻는다. 프로젝트 범위는 .claude/skills/, 전역 범위(-g)는 ~/.claude/skills/에 들어간다. 기본 동작은 공용 폴더 .agents/skills/에 원본을 두고 각 에이전트 폴더에 심볼릭 링크를 거는 방식이다. --copy를 주면 독립 복사본을 만든다(vercel-labs/skills). 강의에서 .agents/skills와 .claude/skills가 함께 생긴 이유가 이것이다. 강의는 무엇이 생기는지 보려고 복사 방식을 골랐다

스킬이 CLAUDE.md와 다른 점은 로드 시점이다. 세션을 시작할 때는 스킬의 이름과 설명만 목록으로 들어가고, 본문은 /스킬이름으로 호출하거나 Claude가 관련 작업이라고 판단할 때 읽는다(skills). 한 번 읽은 본문은 이후 대화에 남는다

세션 시작:  "vercel-react-best-practices: React 코드를 작성·검토할 때 사용" (이름+설명)
호출 시:    SKILL.md 본문 + 필요한 규칙 파일

그래서 프런트 매터의 description이 중요하다. Claude는 이 설명을 보고 언제 스킬을 쓸지 정한다. 목록에서 설명은 스킬당 1,536자에서 잘린다. 스킬을 많이 설치하면 목록 자체가 길어지므로 무조건 많이 설치하는 것이 좋지는 않다. /skills로 설치된 스킬을 보고, /context로 스킬 목록이 차지하는 비중을 확인한다

호출은 두 가지 방식이다. 슬래시 메뉴에서 스킬을 직접 고르거나, 자연어로 이름을 부른다

Vercel React 스킬을 사용해서 예약 UI를 진단하고, 발견한 문제를 영향이 큰 순서대로 정리해 줘.

강사는 이 단계에서 수정을 시키지 않았다. 강의용으로 일부러 넣어 둔 문제까지 열 가지가 넘게 나왔지만, 결과를 읽고 계획을 세운 다음에 고친다. 진단과 수정을 분리해 두면 사람이 결과를 거를 기회가 생긴다

다른 스킬은 skills.sh에서 찾는다. 강의는 응답을 짧게 만드는 Caveman 스킬이 토큰을 75% 줄인다고 소개하는데, 이 수치는 스킬 소개문의 주장이고 강의나 이 글에서 잰 값이 아니다

요구사항은 인터뷰로 닫고 수정 방향은 계획 모드에서 합의한다

계획 모드

/plan을 입력하거나 Shift+Tab으로 계획 모드(plan mode)에 들어간다. 이 모드에서 Claude는 필요한 파일을 읽지만 소스를 고치지 않는다. 계획이 나오면 세 가지 선택지가 보인다(permission-modes)

선택지	결과
Yes, and use auto mode	승인 후 auto 모드로 편집 시작 (auto를 쓸 수 없으면 “Yes, auto-accept edits”)
Yes, manually approve edits	승인하되 편집마다 확인
No, keep planning	피드백을 적고 계획을 다시 받는다

Ctrl+G를 누르면 계획을 편집기에서 직접 고칠 수도 있다. 강의는 피드백의 두 가지 쓰임을 구분한다. “파일을 너무 많이 지우지 않는 방향으로 다시 계획해 줘”는 계획을 다시 쓰게 하는 것이고, “계획은 좋아, 다만 파일을 너무 많이 지우지 마”는 조건을 붙여 승인하는 것이다

계획에서 읽을 것은 배경, 제약, 바꿀 파일과 이유다. 강의는 계획 모드 중 Claude가 Explore 에이전트 두 개를 백그라운드로 띄워 조사하는 모습도 보여 준다. 이미 대화로 방향을 충분히 합의했다면 계획 모드를 거치지 않아도 된다

요구사항 인터뷰

새 기능은 요구사항이 추상적인 상태로 시작한다. 강의 후반에 예약 취소와 일정 변경 기능을 만들 때 강사는 다음 문장을 프롬프트 끝에 붙인다

저장소를 읽어도 알아낼 수 없는 결정 사항은 모두 나에게 질문해 줘.
예외 상황은 무엇인지, 여러 선택이 가능한 동작은 어떻게 처리해야 하는지 인터뷰해 줘.

질문하게 하지 않으면 AI가 빈칸을 추측으로 채우고, 추측한 만큼 코드가 늘어나 검토할 양도 늘어난다. 이 요청에 Claude가 던진 질문과 강사의 답은 다음과 같았다

Claude의 질문	결정
인증 기능이 없는데 고객이 자기 예약임을 어떻게 증명하나	예약 참조 번호로 확인
취소하면 DB 행을 어떻게 처리하나	삭제하지 않고 상태를 취소로 변경
일정 변경은 어떻게 하나	기존 예약을 갱신, 담당 미용사 유지
제한과 구현 범위는	UI 포함, 지난 예약은 변경 불가, 별도 마감 시간 없음
새 시간대는 어디서 가져오나	데모이므로 하드코딩

표의 첫 행은 코드만 봐서는 결정할 수 없는 문제다. 인증이 없다는 사실은 Claude가 찾았지만, 무엇으로 본인을 확인할지는 제품 결정이다. 이런 질문이 빠지면 Claude는 임의로 로그인 기능을 만들 수도 있다

강사는 이 경우 계획 모드를 쓰지 않았다. 인터뷰로 사실상 계획을 함께 정했기 때문이다. 계획서를 한 번 더 보고 싶다면 “먼저 질문하고, 그다음 계획을 작성해 줘”라고 이어 붙이면 된다. 더 촘촘한 인터뷰가 필요하면 Addy Osmani의 agent-skills에 있는 interview-me 같은 스킬을 쓸 수 있다고 강의는 소개한다

권한 모드는 무엇을 묻지 않고 실행할지 정한다

계획을 승인하면 파일이 바뀌기 시작한다. 이때 Claude가 어떤 행동을 묻지 않고 실행할지는 권한 모드가 정한다. Shift+Tab으로 바꾼다

모드	묻지 않고 실행하는 것
Manual (`default`)	작업 디렉터리 안의 읽기, 내장 읽기 전용 명령
`acceptEdits`	위 + 파일 편집 + `mkdir`·`touch`·`rm`·`rmdir`·`mv`·`cp`·`sed`
`plan`	읽기만 한다. 편집하지 않는다
`auto`	분류기 모델이 위험도를 판단해 통과시킨 행동

강의는 수동 모드를 “모든 작업을 물어본다”고 단순화하는데, 문서 기준으로 작업 디렉터리 안의 파일 읽기와 Grep은 묻지 않는다(permissions). 편집 승인 모드에 대해서도 강의는 “Bash 명령은 여전히 물어본다”고 설명한다. 현재 문서에는 acceptEdits가 작업 디렉터리 안의 rm, mv, sed 같은 파일 시스템 명령도 자동 승인한다고 되어 있다. 그 밖의 Bash 명령과 작업 디렉터리 밖 경로는 여전히 묻는다(permission-modes). 편집 승인 모드에서 파일 삭제까지 확인 없이 일어날 수 있다는 뜻이다

auto 모드는 별도의 분류기 모델이 실행 전에 행동을 검토하고, 요청 범위를 넘어서는 행동을 막는다. 현재 문서 기준으로 v2.1.283 이상에서는 대화형 터미널과 VS Code 세션이 auto 모드로 시작한다. 강의 시점과 달리 새로 설치한 사용자는 따로 고르지 않아도 auto로 일하게 된다. Shift+Tab을 누르면 auto에서 Manual로 넘어가고, 이후 Manual → acceptEdits → plan 순으로 돈다

강사는 auto를 거의 쓰지 않고 편집 승인 모드를 주로 쓴다고 했다. 파일 편집은 되감기와 Git으로 되돌릴 수 있지만, 명령 하나는 코드를 대량으로 지우거나 git push --force를 실행할 수 있기 때문이다. 어떤 모드를 쓰든 되돌릴 수 없는 명령을 사람이 볼 수 있는지가 선택 기준이다

반복되는 승인은 settings.json 규칙으로 옮긴다

편집 승인 모드에서도 타입 검사처럼 매번 묻는 명령이 있다. 기능을 고칠 때마다 “네”를 누르는 대신 규칙으로 허용한다. 반대로 운영 배포처럼 Claude가 절대 실행하면 안 되는 명령은 거부 규칙으로 막는다

/permissions로 규칙을 관리하는 화면을 열 수 있고, 규칙은 .claude/settings.json에 저장된다. 다음은 타입 검사를 허용하고 배포와 푸시를 막는 설정이다

{
  "permissions": {
    "allow": [
      "Bash(npm run typecheck)",
      "Bash(npx drizzle-kit generate)"
    ],
    "deny": [
      "Bash(npm run deploy *)",
      "Bash(git push *)"
    ]
  }
}

규칙은 도구이름(입력 패턴) 형태다. 평가 순서는 deny, ask, allow이고 이 순서로 처음 맞는 규칙이 결과를 정한다(permissions). 넓은 deny는 좁은 allow보다 이긴다. Bash(aws *)를 거부하면 Bash(aws s3 ls)를 허용해도 막힌다

* 앞의 공백은 의미가 있다. Bash(ls *)는 ls 다음에 공백을 요구하므로 lsof에 맞지 않고, Bash(ls*)는 lsof에도 맞는다. Bash(npm run deploy *)는 인수 없는 npm run deploy에도 맞는다. 예전 문법 Bash(npm run deploy:*)는 같은 뜻으로 인식되지만, 이름이 deploy:prod인 스크립트를 가리키지는 않는다. /permissions 화면은 공백 형식으로 저장한다. 강의에서는 이 규칙을 넣은 뒤 새 세션에서 타입 검사는 바로 실행되고 npm run deploy는 거부되는 것을 확인했다

실행 중에 “Yes, and don’t ask again”을 고른 Bash 명령은 저장소 루트의 .claude/settings.local.json에 저장된다. 팀과 공유하지 않는 개인 허용 목록이 이렇게 쌓인다. 파일 편집 승인은 디스크에 저장되지 않고 세션이 끝날 때까지만 유지된다

비밀 파일은 경로 규칙으로 막는다. Read(./.env)를 deny에 넣으면 Claude의 파일 도구뿐 아니라 Bash의 cat, head, sed 같은 인식 가능한 파일 명령과 리다이렉션 대상에도 적용된다. 다만 Python이나 Node 스크립트가 파일을 직접 여는 경우는 막지 못한다. 문서는 모든 프로세스를 막으려면 샌드박스를 켜라고 안내한다(permissions). 이 한계는 5편의 훅 예제에서 다시 나온다

설정 파일을 처음부터 완성할 필요는 없다. “마이그레이션 생성은 허용하되 데이터베이스에 직접 푸시하는 명령은 막아 줘”처럼 조건을 말하고 Claude에게 규칙 초안을 쓰게 한 다음 검토해도 된다. 전부 허용과 전부 거부 사이에서 자기 작업에 맞는 지점을 조금씩 찾는 것이 목표다

탐색은 따로 보내고, 진단 기준은 스킬로 주고, 결정은 질문으로 받아 내고, 되돌릴 수 없는 명령은 규칙으로 막은 다음에 수정을 허락한다

출처

nomadcoders