Claude Code 권한 설계 체크리스트 2026 — hooks·subagents·세션 분리 어디서부터 막아야 하나

Posted on by

Claude Code를 오래 쓰다 보면 결국 이 질문으로 돌아온다.

어디까지 자동으로 열어도 되고, 어디서부터는 따로 묶어야 하지?

모델 성능은 멋있다. 근데 실사용에서 더 자주 터지는 건 권한 설계다.

  • hooks가 너무 많이 건드릴 때
  • subagent가 메인 세션보다 더 넓게 볼 때
  • 세션이 길어지면서 원래 금지선이 흐려질 때

이럴 때 필요한 건 더 화려한 프롬프트가 아니라 권한 경계선이다.

Quick Answer

  • Claude Code 권한 설계는 도구 개수보다 행동 등급 분리가 먼저다.
  • 최소한 read, local write, external write, destructive 네 칸은 나눠야 한다.
  • hooks는 자동 반사 신경이라서 더 좁게 묶어야 하고, subagents는 독립 문맥이라서 더 작게 잘라야 한다.
  • 세션은 길어질수록 규칙이 흐려지니, 지속 규칙은 채팅이 아니라 파일 계약서로 빼는 게 낫다.

한 줄로 줄이면 이거다.

Claude Code에서 먼저 설계해야 할 건 “무슨 모델을 쓰나”가 아니라 “누가 어디까지 건드릴 수 있나”다.

이 글이 필요한 사람

  • Claude Code를 개인 프로젝트를 넘어 팀 운영 도구로 쓰려는 사람
  • hooks, subagents, 세션을 다 열어놓고 조금 불안해진 사람
  • CLAUDE.md, skill, hook, permission mode를 어떻게 나눌지 감이 안 오는 사람
  • “왜 어떤 날은 잘 굴러가다 갑자기 위험해 보이지?”를 설명하고 싶은 사람

지금 결론

구성요소 기본 권한 원칙
메인 세션 read + 좁은 local write
hooks 최소 권한, 자동 외부 write 금지
subagents 좁은 문맥 + 좁은 도구
publish/deploy 계열 별도 승인 lane
삭제/이동/외부 API write 강한 확인 유지

즉 설계 순서는 보통 이렇다.

  1. 행동 등급을 나눈다.
  2. 메인 세션 기본권한을 낮게 둔다.
  3. hooks는 더 낮게 둔다.
  4. subagent는 일감별로 더 작게 자른다.
  5. 외부 write는 별도 lane으로 뺀다.

권한 설계를 망치는 출발점

제일 흔한 실수는 이거다.

어차피 내가 쓰는 거니까 다 열어도 되지 않나?

짧은 세션에선 그게 먹힌다. 근데 운영이 길어질수록 아래 문제가 붙는다.

  • 메인 세션이 조사와 수정과 발행을 다 먹는다
  • hooks가 정책 검사보다 자동 실행기처럼 비대해진다
  • subagent가 탐색용인지 수정용인지 경계가 사라진다
  • 세션이 길어질수록 원래 규칙을 잊는다

이때부터는 도구가 문제가 아니라 구조가 문제다.

내가 추천하는 최소 권한 모델

나는 Claude Code 계열을 볼 때 최소한 이 네 칸은 나눈다.

등급 예시 기본값
read 파일 읽기, 검색, 문서 확인 넓게 허용 가능
local write 로컬 파일 수정, 초안 작성 제한적으로 허용
external write 발행, 시트 수정, 외부 API 변경 별도 승인
destructive 삭제, 이동, 대량 수정, 민감 계정 변경 강한 승인

핵심은 파일 수정과 외부 발행을 절대 같은 칸에 두지 않는 거다.

로컬에서 초안 쓰는 건 되돌릴 수 있다. 외부 시스템에 올리는 건 얘기가 달라진다.

hooks는 왜 더 좁게 묶어야 하나

hooks는 편하다. 편해서 더 위험하다.

왜냐면 사람이 일일이 누르지 않아도 이벤트에 반응해서 바로 돈다.

그래서 내 기준의 hooks 원칙은 이렇다.

hooks에 잘 맞는 것

  • 포맷 검사
  • 로컬 테스트
  • 상태 메모 남기기
  • 경고 메시지 출력

hooks에 안 맞는 것

  • 외부 발행
  • 계정 변경
  • 비밀정보를 다루는 업로드
  • destructive command 자동 실행

쉽게 말하면 hooks는 자동 브레이크엔 맞지만 자동 액셀엔 잘 안 맞는다.

subagents는 왜 좁은 문맥으로 잘라야 하나

subagent의 장점은 독립 문맥이다. 문제는 그 장점이 가끔 독립 사고처럼 변한다는 거다.

그래서 subagent는 보통 역할 기준으로 자르는 게 낫다.

역할 권장 범위
explorer 읽기 전용 조사
review helper 읽기 + 코멘트 수준
worker 지정 파일 쓰기
publisher 별도 승인 이후만

여기서 중요한 건 도구 수보다 책임 범위다.

조사원한테 쓰기 권한을 넓게 주면 어색하고, 발행 담당한테 전체 볼트 읽기 권한을 넓게 주는 것도 과할 수 있다.

세션 분리는 왜 생각보다 중요하나

세션은 길어질수록 규칙이 흐려진다.

초반엔 분명히 이랬다.

  • 오늘은 초안만 쓴다
  • 외부 발행은 안 한다
  • 이 세션은 조사만 한다

근데 오래 굴리다 보면 세션이 이런 식으로 변한다.

  • 초안도 쓰고
  • 링크도 고치고
  • 시트도 만지고
  • 발행도 해버리고

이러면 권한 설계가 무너진다.

그래서 세션은 기능이 아니라 단계로 나누는 게 좋다.

  1. 조사 세션
  2. 수정 세션
  3. 검토 세션
  4. 발행 세션

같은 도구라도 세션 성격이 다르면 허용 범위도 달라져야 한다.

체크리스트: 어디서부터 막을까

1. 외부 write가 섞이면 lane을 분리해라

WordPress, Google Sheets, 배포, 원격 API는 같은 칸이 아니다.

2. hooks는 경고/검사 중심으로 두고, 실행은 최소화해라

자동으로 돌아간다고 자동으로 맡겨도 되는 건 아니다.

3. subagent는 역할 단위로 좁혀라

탐색용, 수정용, 리뷰용, 발행용을 한 몸에 넣지 마라.

4. 지속 규칙은 채팅이 아니라 파일에 둬라

세션이 길어지면 기억보다 계약서가 이긴다.

5. 비밀정보를 보는 세션과 글을 쓰는 세션을 섞지 마라

문맥 오염은 생각보다 쉽게 난다.

실수 TOP 5

1. 권한 설계를 모델 선택보다 뒤로 미루는 실수

운영 병목은 대개 거기서 먼저 난다.

2. hooks를 “자동 편의”로만 보는 실수

hooks는 정책 포인트다.

3. subagent를 많이 만들면 안전해진다고 믿는 실수

경계 없는 분화는 안전이 아니라 소음이다.

4. 세션을 길게 끌면서도 lane 분리를 안 하는 실수

그럼 결국 뭐든 다 하게 된다.

5. 외부 write를 local write랑 같은 급으로 취급하는 실수

이건 진짜 빨리 고쳐야 한다.

FAQ

Q. hooks부터 잠가야 하나, subagents부터 잠가야 하나

보통은 hooks부터다. 자동 반응은 생각보다 사고 반경이 크다.

Q. 메인 세션이 다 하면 안 되나

짧게는 되는데, 운영이 커지면 언젠가 규칙이 흐려진다.

Q. 권한 분리의 최소 단위는 뭔가

read / local write / external write / destructive 네 칸부터면 시작하기 좋다.

Q. Claude Code에서 제일 먼저 문서화할 건 뭔가

세션 목적, 금지선, 외부 write 승인 규칙이다.

다음에 읽을 글

출처와 전제

  • Claude Code 공식 동작 구조와 permission/hook/subagent 감각은 Anthropic 공개 문서와 로컬 운영 경험을 함께 반영했다.
  • 이 글은 보안 제품 문서가 아니라 운영 설계 체크리스트다.