Claude Code 오래 쓸수록 먼저 고쳐야 할 설정 2026 — hooks·permissions·subagents를 한 번에 정리

Posted on by

Claude Code를 처음 쓸 때는 모델이 잘 답하느냐가 더 중요해 보인다.

근데 오래 쓸수록 진짜 차이를 만드는 건 모델보다 설정이다.

2026년 4월 14일 기준으로 Anthropic 공식 문서를 다시 보면 설정 포인트는 엄청 많다.

그런데 실전에서는 다 만질 필요가 없다.

먼저 손대야 하는 건 늘 비슷하다.

permissions

hooks

subagents

이 세 축이다.

이걸 먼저 정리하면 세션이 덜 끊기고, 권한 승인 피로가 줄고, 팀 공용 레포에서 누가 뭘 왜 남겼는지도 설명이 된다.

반대로 이 셋이 흐리면 Claude Code가 똑똑한지 아닌지와 별개로 운영이 금방 지저분해진다.

이번 글은 Claude 사용법 정리 같은 넓은 요약이 아니라, 오래 쓸수록 먼저 고쳐야 할 설정 3층만 실전 기준으로 묶어본 메모다.

Threads 요약 노트에 적힌 74일 연속 사용 4,100회 대화 1,760만 토큰 같은 숫자도 사실 같은 결론으로 모인다.

오래 쓸수록 좋은 프롬프트 하나보다 운영 마찰을 줄이는 기본 설정이 더 큰 차이를 만든다는 거다.

먼저 한 줄 판단

Claude Code 설정은 화려한 자동화부터 붙이기보다 권한 경계 자동 검사 역할 분리 순서로 손보는 편이 덜 꼬인다.

내 기준 한 줄 정리는 이렇다.

  • permissions는 세션 피로를 줄이는 기본 가드레일이다
  • hooks는 자동화보다 사고 방지 장치로 먼저 써야 한다
  • subagents는 일 분배보다 책임 분리에 쓸 때 오래 간다

이 셋만 정리돼도 Claude Code는 훨씬 덜 피곤해진다.

누가 지금 이 글부터 보면 좋은가

이 글은 특히 이런 사람에게 맞다.

  • Claude Code를 개인 장난감이 아니라 작업 도구로 쓰기 시작한 사람
  • 팀 레포에 .claude/가 생겼는데 누가 뭘 공유했는지 헷갈리는 사람
  • 승인 팝업과 권한 질문이 너무 자주 떠서 흐름이 깨지는 사람
  • hooks를 멋있게 붙였는데 오히려 더 시끄러워진 사람
  • subagent를 여러 개 만들었는데 실제론 거의 안 부르는 사람

반대로 아직 하루 이틀 테스트 중이거나, 한 프로젝트에서 딱 한두 번만 쓸 예정이면 이 글의 절반은 과할 수 있다.

그럴 땐 프로젝트 설정 하나와 가벼운 허용 규칙 몇 개만 있어도 충분하다.

왜 설정은 기능보다 마찰 제거 순서로 손봐야 하나

Claude Code 공식 settings 문서는 설정 범위와 우선순위를 꽤 명확하게 설명한다.

2026-04-14 기준 문서에는 scope가 이렇게 나온다.

  • Managed
  • User
  • Project
  • Local

그리고 우선순위도 선명하다.

  • Managed
  • command line arguments
  • Local
  • Project
  • User

즉, 설정은 그냥 많아지는 게임이 아니다.

어디에 둘 것인가

누가 공유하는가

누가 덮어쓰는가

이 세 가지가 먼저다.

이걸 안 정하면 settings는 늘어나는데 실제 운영은 더 혼란스러워진다.

예를 들면 이런 식이다.

  • 내 로컬에서만 편한 설정을 프로젝트에 커밋한다
  • 팀 공용 deny 규칙을 user scope에만 넣어둔다
  • hook를 넣어놓고 누가 왜 넣었는지 설명이 없다
  • subagent를 프로젝트에 박아뒀는데 개인 실험용이라 팀원은 쓸 일이 없다

겉으로는 기능이 많아지는데, 실제로는 마찰도 같이 커진다.

그래서 설정은 새 기능 추가 순서보다 마찰 제거 순서로 보는 편이 낫다.

1층은 permissions와 scope부터 고쳐야 한다

첫 번째 층은 permissions다.

이건 멋이 아니라 기본 체력이다.

공식 settings 문서는 project scope가 팀 공유용 permissions, hooks, MCP servers에 적합하다고 적고 있다.

반대로 local scope는 개인 오버라이드와 실험용에 가깝다.

이 차이를 안 나누면 팀 레포가 금방 이상해진다.

scope를 이렇게 나누면 덜 피곤하다

scope 내 기준 역할 여기 두면 좋은 것 여기 두면 안 좋은 것
user 전역 취향 개인 선호, 공통 alias, 자주 쓰는 허용 규칙 특정 프로젝트 전용 실험
project 팀 공용 규칙 공용 permissions, 팀 hooks, 공용 subagent 개인 취향, 개인 비밀키 경로
local 내 실험 구역 프로젝트별 개인 오버라이드, 테스트 팀원이 알아야 하는 핵심 규칙
managed 조직 정책 보안/준수 강제 개인 편의 옵션

이 표가 별거 아닌 것 같아도 실무에서는 제일 중요하다.

왜냐면 Claude Code는 잘못 허용했을 때보다 어디에 허용했는지 헷갈릴 때 더 오래 고생하기 때문이다.

승인 피로가 쌓인다면 허용 규칙을 다시 봐야 한다

세션이 자주 끊기는 사람은 대개 모델 문제가 아니라 권한 설계가 엉성한 경우가 많다.

아래 징후가 보이면 permissions부터 다시 보는 편이 낫다.

  • 매번 같은 npm test나 pnpm lint를 다시 승인한다
  • 읽어도 되는 경로와 안 되는 경로 경계가 불명확하다
  • project 규칙보다 user 규칙이 더 공격적이다
  • .env나 secrets류 deny가 없는 상태로 오래 쓴다
  • 팀원이 만든 rule 때문에 내 세션만 이상하게 막힌다

공식 문서 예시도 allow와 deny를 같이 둔다.

핵심은 간단하다.

매번 허용할 명령은 좁고 선명하게,

절대 읽히면 안 되는 비밀 경로는 명시적으로 막는 쪽이 낫다.

/config를 한 번도 안 눌렀다면 이미 늦었다

공식 settings 문서는 active settings를 /config에서 확인하라고 안내한다.

이건 은근 중요하다.

왜냐면 많은 팀이 파일은 있는데 실제로 어느 scope가 먹는지 안 보고 추측으로 운영하기 때문이다.

설정이 꼬였을 때 제일 먼저 할 일은 새 rule 추가가 아니다.

지금 무엇이 실제로 활성인지 확인하는 일이다.

내 기준 첫 점검 순서는 이렇다.

  1. /config에서 현재 적용 상태를 본다
  2. user/project/local 중 어디가 이기고 있는지 확인한다
  3. 중복되는 allow/deny를 줄인다
  4. 팀 공용 rule과 개인 실험 rule을 분리한다

대부분의 이상한 승인 피로는 이 단계에서 이미 많이 줄어든다.

permissions는 넓게 여는 것보다 반복을 줄이는 쪽이 맞다

여기서 흔한 실수가 있다.

불편하니까 그냥 다 열자

이건 초반엔 편한데 나중엔 더 귀찮다.

권한이 너무 넓으면 나중에 문제 생겼을 때 무엇이 원인인지 추적이 안 된다.

차라리 반복적으로 꼭 필요한 도구만 좁게 허용하는 쪽이 낫다.

예를 들면 이런 패턴은 이해 가능하다.

  • Bash(npm run test *)
  • Bash(pnpm lint)
  • Read(./docs/**)

반대로 이런 건 나중에 후회할 가능성이 높다.

  • Bash(*)
  • Read(./**)
  • 특정 프로젝트에서만 써야 할 예외를 user scope에 넣기

Claude Code는 권한 승인을 줄이는 도구이지, 권한 경계 자체를 지우는 도구는 아니다.

2층은 hooks다

두 번째 층은 hooks다.

여기서 사람 마음이 흔들린다.

hooks를 보면 갑자기 다 자동화하고 싶어진다.

근데 공식 hooks 문서를 다시 보면 실전에서 먼저 붙일 자리는 생산성 쇼가 아니라 사고 방지다.

2026-04-14 기준 hooks 문서에는 이벤트가 꽤 다양하게 나온다.

  • PreToolUse
  • PostToolUse
  • PostToolUseFailure
  • Notification
  • SubagentStart
  • SubagentStop
  • Stop
  • PreCompact

즉, hooks는 단순 알림만이 아니라 작업 전, 작업 후, 실패 시점, 정지 시점까지 걸 수 있는 구조다.

제일 먼저 붙일 만한 hook는 세 가지다

내 기준으로는 아래 세 개가 제일 ROI가 높다.

1. 위험 명령 전 차단

PreToolUse는 실행 전에 걸린다.

그래서 정말 먼저 붙일 만한 건 화려한 post-processing보다 위험 명령 차단이다.

예를 들면 이런 쪽이다.

  • 파괴적 git 명령 경고
  • 프로덕션 경로 접근 차단
  • 특정 배포 스크립트 실행 전 재확인

이건 자동화를 늘리는 게 아니라 실수를 줄이는 장치다.

2. 수정 후 가벼운 검사

PostToolUse는 도구가 성공한 직후 실행된다.

공식 문서 예시도 Write 뒤에 lint check를 붙이는 구조를 보여준다.

이건 꽤 실전적이다.

파일이 바뀌었을 때 아주 가벼운 검사만 붙여도 후반 디버깅 시간을 줄여준다.

다만 여기서 포인트는 가벼운 검사다.

거대한 test suite를 모든 Edit 뒤에 걸어버리면 workflow가 바로 질식한다.

3. 멈추기 전 체크

Stop과 SubagentStop은 작업이 끝났다고 판단하는 시점에 관여할 수 있다.

이건 꽤 강력하다.

예를 들면

  • TODO가 남아 있으면 멈추지 않기
  • 핵심 테스트가 안 돌았으면 멈추지 않기
  • publish 전에 preflight가 안 끝났으면 멈추지 않기

이런 가드레일을 만들 수 있다.

길게 보면 이게 automation보다 더 쓸모 있다.

실수한 뒤 수습 보다 멈추기 전에 한 번 더 보기 가 훨씬 싸기 때문이다.

Notification hook는 알림보다 문맥 보강에 써야 한다

Notification은 permission prompt, idle prompt, auth success, elicitation dialog 같은 타입에 반응한다.

문서상으로 Notification hook는 알림 자체를 막지는 못하고, 추가 문맥을 넣는 정도다.

그래서 이건 메인 자동화 엔진보다 놓치지 않기 쪽에 가깝다.

예를 들면

  • permission prompt가 뜰 때 사내 규칙 링크 붙이기
  • idle prompt가 뜰 때 다음 체크리스트 남기기
  • auth 관련 성공 이벤트를 로그로 남기기

이 정도가 현실적이다.

hook가 실패하는 이유는 대개 너무 많은 걸 기대해서다

hooks는 잘 쓰면 좋다.

근데 과해지면 오히려 제일 먼저 시끄러워진다.

대표적인 실패 패턴은 이렇다.

  • 모든 이벤트에 다 건다
  • 한 hook가 너무 많은 책임을 가진다
  • 가벼운 검사 대신 무거운 파이프라인을 붙인다
  • 실패했을 때 fallback이 없다
  • 누가 유지보수하는지 owner가 없다

내 기준으로 hook는 한 줄 정책 + 짧은 확인 정도로 시작하는 게 제일 낫다.

3층은 subagents다

세 번째 층은 subagents다.

많은 팀이 여기서 제일 신난다.

역할 이름 붙이는 재미가 크고, 분업 체계가 갑자기 있어 보이기 때문이다.

근데 공식 sub-agents 문서가 말하는 핵심은 조금 다르다.

2026-04-14 기준 문서에는 subagent가 Markdown files with YAML frontmatter 라고 적혀 있다.

그리고 저장 위치도 선명하다.

  • project subagents: .claude/agents/
  • user subagents: ~/.claude/agents/

즉, subagent는 예쁜 이름표가 아니라 실제 파일로 관리되는 설정 객체다.

그래서 더더욱 무한 증식시키면 안 된다.

subagent는 작업 종류보다 책임 경계로 나누는 편이 낫다

별로 안 좋은 분리 방식은 이런 거다.

  • frontend-agent
  • backend-agent
  • bug-agent
  • fix-agent
  • review-agent
  • quick-agent
  • slower-agent

이렇게 쪼개면 듣기엔 그럴듯한데 실제로는 경계가 겹친다.

반대로 오래 가는 건 책임 경계가 선명한 유형이다.

  • code-review 전용
  • release-check 전용
  • data-extraction 전용
  • docs-sync 전용

즉, 무엇을 맡으면 끝나는가 가 보여야 한다.

project와 user subagent를 섞을 때 원칙이 필요하다

공식 문서는 project subagent가 레포 특화 역할에 적합하다고 설명한다.

이건 아주 실전적이다.

내 기준으로는 이렇게 나누면 편하다.

  • project: 이 레포 맥락을 꼭 알아야 하는 역할
  • user: 어떤 프로젝트에도 들고 다닐 수 있는 개인 전문가

예를 들면

  • release note 포맷이 특이한 레포면 project subagent
  • 내가 어디서든 쓰는 code-reviewer면 user subagent

이걸 안 나누면 개인 실험용 에이전트가 팀 레포에 눌러앉는다.

그리고 그 순간부터 아무도 자신 있게 못 고친다.

subagent를 많이 만드는 것보다 설명을 잘 쓰는 게 더 중요하다

문서에 따르면 subagent는 YAML frontmatter 뒤에 system prompt를 Markdown으로 둔다.

여기서 중요한 건 모델 이름보다 설명과 경계다.

설명이 흐리면 호출하는 쪽도 흐려진다.

그래서 나는 subagent 설명에 꼭 아래를 넣는 편이다.

  • 언제 부를지
  • 무엇을 하지 말아야 하는지
  • 어떤 출력이면 완료인지

실제로 오래 가는 subagent는 프롬프트가 멋진 놈보다 완료 기준이 선명한 놈이다.

제일 덜 꼬이는 추천 배치

지금 막 정리한다면 나는 대체로 이렇게 간다.

층 첫 설정 목적
1층 project permissions + local override 최소화 승인 피로와 비밀 경로 리스크 줄이기
2층 PreToolUse 1개, PostToolUse 1개, Stop 1개 사고 방지와 가벼운 자동 검사
3층 project subagent 1~2개, user subagent 1개 역할 분리와 재사용성 확보

좀 더 풀어 쓰면 이렇다.

  • 팀 공용 레포에는 project 규칙만 최대한 선명하게 둔다
  • 개인 실험은 local에 둔다
  • hook는 처음부터 세 개 넘기지 않는다
  • subagent는 팀 공용 2개를 넘기지 않고 시작한다

이 정도면 대부분의 팀이 감당 가능하다.

30분 리셋 루틴

이미 복잡해졌다면 처음부터 다시 만들 필요는 없다.

30분만 써서 아래 순서로 리셋해도 된다.

1. settings 파일 위치부터 적는다

  • ~/.claude/settings.json
  • .claude/settings.json
  • .claude/settings.local.json
  • .claude/agents/
  • ~/.claude/agents/

이 다섯 줄만 적어도 어디가 개인용이고 어디가 공용인지 정리되기 시작한다.

2. 승인 많이 뜨는 명령 세 개만 뽑는다

가장 자주 반복되는 승인 세 개만 뽑아라.

그걸 보고 좁은 allow 규칙으로 옮길지 결정한다.

처음부터 완벽하게 하지 않아도 된다.

반복이 큰 것부터 줄이면 된다.

3. hook를 전수조사하지 말고 owner부터 본다

hook 내용보다 먼저 누가 관리하느냐를 본다.

owner 없는 hook는 대체로 오래 못 간다.

없앨 후보 1순위다.

4. subagent는 실제 호출된 것만 남긴다

이름만 멋지고 아무도 안 부르는 subagent는 정리해도 된다.

역할 분리는 컬렉션 게임이 아니다.

실제 반복되는 책임만 남는 편이 낫다.

실수 TOP 5

1. user scope에 팀 규칙을 우겨 넣는다

내 컴퓨터에선 되는데 팀 운영은 더 혼란스러워진다.

2. hook를 자동화 자랑 용도로만 쓴다

가장 먼저 필요한 건 멋진 자동화보다 사고 방지다.

3. subagent를 너무 많이 만든다

많다고 분업이 되는 게 아니다.

경계가 겹치면 오히려 호출자가 더 헷갈린다.

4. /config로 실제 적용 상태를 안 본다

이건 거의 확정적으로 시간을 낭비한다.

5. local 실험을 project에 그대로 커밋한다

개인 편의와 팀 공용이 섞이는 순간 레포가 지저분해진다.

언제 이 셋업이 맞고 언제 아닌가

잘 맞는 경우

  • Claude Code를 매일 혹은 매주 반복 사용한다
  • 팀 레포에서 공용 규칙이 필요하다
  • 승인 피로와 실수 방지가 실제 비용으로 느껴진다
  • 작업 역할이 어느 정도 반복된다

아직 과한 경우

  • 일회성 실험만 한다
  • 혼자 잠깐 써보고 끝낼 프로젝트다
  • hook와 subagent를 관리할 사람 자체가 없다
  • 팀 공용 규칙보다 속도가 훨씬 중요하다

그 경우엔 project permissions 최소 셋만 먼저 두고, 나머지는 나중에 붙여도 된다.

FAQ

settings는 user에 몰아두면 더 편하지 않나

혼자만 쓸 때는 편할 수 있다.

하지만 팀 레포에서 반복되는 규칙은 project에 두는 편이 낫다.

그래야 같이 보는 사람들이 왜 그런 규칙이 있는지 이해할 수 있다.

local과 project가 겹치면 뭐가 이기나

2026-04-14 기준 공식 settings 문서에 따르면 local이 project보다 우선한다.

그래서 local은 개인 실험용으로만 좁게 쓰는 편이 안전하다.

hook는 몇 개부터 많은 편일까

정답은 없지만 처음부터 다섯 개 넘게 깔면 대개 유지보수 피로가 먼저 온다.

내 기준 시작점은 세 개 이하다.

subagent는 project에 두는 게 무조건 맞나

아니다.

프로젝트 특화 역할이면 project, 어디서든 들고 다닐 개인 전문가면 user가 낫다.

permissions를 넓게 열어두면 작업 속도는 빨라지지 않나

당장은 그럴 수 있다.

하지만 나중에 원인 추적과 팀 공유가 더 어려워진다.

반복되는 허용만 좁게 여는 쪽이 오래 보면 더 빠르다.

hook를 testing 자동화에만 써도 되나

된다.

다만 가장 먼저 붙일 건 대개 무거운 테스트보다 위험 명령 차단이나 멈춤 전 체크다.

subagent 설명에서 제일 중요한 건 뭔가

언제 부를지와 무엇이면 완료인지다.

설명보다 역할 경계가 흐리면 아무도 안정적으로 못 쓴다.

공식 출처

관련 글