2026년 4월 3일 기준. 이 글은 Anthropic 공식 문서인 How Claude Code works, Hooks reference, Create custom subagents를 기준으로 정리했다. 중간중간 넣은 해석은 Claude Code, Codex, Cursor를 같이 굴리면서 느낀 운영 경험을 바탕으로 덧붙였다.
Claude Code를 그냥 “터미널에서 돌아가는 AI 코딩툴” 정도로만 보면 반밖에 못 본 거다. 이 도구는 사실상 모델 + 도구 + 권한 + 세션 + 컨텍스트 관리를 하나로 묶은 작은 런타임에 가깝다. 그래서 표면 기능만 따라 쓰면 “왜 얘는 어떤 날은 똑똑하고 어떤 날은 이상하지?”가 되고, 내부 구조를 이해하면 “왜 live UI가 필요하고 왜 continuous loop가 본체인지”가 보인다.
Quick Answer
Claude Code는 모델이 혼자 마법처럼 다 하는 툴이 아니라, 추론하는 모델과 실행하는 도구를 Claude Code가 감싸서 에이전트 루프로 돌리는 구조다. 여기서 핵심은 네 가지다.
- live terminal UI는 장식이 아니라 루프 상태를 드러내는 계기판이다
- 본체는 한 번 답하고 끝나는 챗이 아니라
continuous agentic loop다 - 성능보다 자주 부딪히는 건
permission mode와context window다 - hooks는 자동화 포인트고, subagents는 컨텍스트 절약 장치다
- 오래 쓸수록 프롬프트보다
CLAUDE.md, skills, 권한 설계가 더 중요해진다
한 줄로 줄이면 이거다.
Claude Code를 잘 쓰는 사람은 좋은 질문만 하는 사람이 아니라, 세션과 권한과 컨텍스트를 설계하는 사람이다.
이 글이 필요한 사람
- Claude Code를 쓰는데 가끔 왜 이렇게 똑똑하고 가끔 왜 이렇게 헤매는지 궁금한 사람
- hooks, subagents, CLAUDE.md를 다 보긴 했는데 어디에 써야 하는지 감이 안 오는 사람
- Cursor, Codex, Claude Code를 같이 쓰면서 역할 분담 기준을 잡고 싶은 사람
- 기능 소개글보다 실제 운영 관점의 설명이 필요한 사람
지금 결론
- Claude Code의 본질은 채팅창이 아니라
반복 실행되는 루프다. - 실제 운영 병목은 모델 지능보다
권한 승인,컨텍스트 비만,작업 분리 실패에서 더 자주 생긴다. - 그래서 초반 세팅 우선순위는
모델 선택보다CLAUDE.md -> permissions -> hooks -> subagents순서가 더 맞다.
Claude Code는 사실 터미널 앱이 아니라 에이전트 하네스에 가깝다
Anthropic 공식 문서는 Claude Code를 language model 위에 얹힌 agentic harness처럼 설명한다. How Claude Code works 문서 기준으로 Claude Code는 모델이 추론하고, 도구가 행동하고, 그 사이를 Claude Code가 연결한다. 모델은 무엇을 할지 판단하고, Claude Code는 파일 읽기, 편집, 셸 실행, 웹 검색, 코드 인텔리전스 같은 실제 액션을 제공한다.
이 차이를 이해하면 UI 집착이 줄어든다. 터미널에서 보이는 스트리밍 출력이 전부인 것 같지만, 진짜 중요한 건 아래 같은 루프가 계속 돈다는 점이다.
- 요청을 읽는다
- 어떤 정보가 필요한지 판단한다
- 적절한 도구를 고른다
- 결과를 다시 읽는다
- 수정 또는 다음 액션을 결정한다
- 검증하고 응답한다
공식 문서 예시도 비슷하다. “fix the failing tests”를 받으면 테스트를 돌리고, 오류를 읽고, 파일을 찾고, 수정하고, 다시 테스트한다. 이게 Claude Code의 진짜 동작 방식이다. 한 번 대답하고 끝나는 챗봇이면 여기서 멈추는데, Claude Code는 이 루프를 계속 돌리기 때문에 “코딩 에이전트” 소리를 듣는 거다.
왜 live UI를 굳이 터미널에 보여주나
여기서 live UI가 나온다. Claude Code는 내부에서 계속 루프를 돌고 있기 때문에, 사용자 입장에선 지금 무슨 일이 벌어지는지 안 보이면 불안하다.
- 지금 파일을 읽는 중인지
- 권한 승인을 기다리는지
- 셸 명령이 돌고 있는지
- subagent가 조사 중인지
- 그냥 멍때리는 건지
이걸 안 보여주면 사용자는 도구를 못 믿는다. 반대로 live UI가 있으면 생각 -> 도구 선택 -> 실행 -> 검증 흐름이 보인다. 즉 live UI는 예쁜 연출이 아니라 에이전트의 현재 상태를 설명하는 안전장치다. 자동차 대시보드 없애고 “엔진은 잘 돌아갑니다”만 믿으라는 셈이면 아무도 오래 못 탄다.
live UI 다음으로 중요한 건 승인 루프다
실사용에서 더 자주 체감되는 건 예쁜 UI가 아니라 permission mode다. 공식 문서 기준으로 Claude Code는 다음 모드를 제공한다.
- Default: 파일 편집과 셸 명령 전에 묻는다
- Auto-accept edits: 파일 수정은 자동, 명령은 계속 묻는다
- Plan mode: 읽기 전용으로 분석만 한다
- Auto mode: 배경 안전장치로 평가하며 더 넓게 자동 실행한다
겉으로 보면 사소해 보여도 여기서 체감 생산성이 크게 갈린다. live UI가 계기판이라면 permission mode는 브레이크와 안전벨트다.
언제 가장 답답하냐
- 작은 수정인데 셸 명령마다 계속 허가를 눌러야 할 때
- 반대로 자동화를 열어놨더니 외부 부작용 있는 명령까지 너무 쉽게 흘러갈 때
- 계획이 필요한 작업인데 바로 편집 모드로 들어가 컨텍스트를 낭비할 때
그래서 운영 팁은 단순하다.
- 구조 파악 단계:
Plan mode - 좁은 로컬 수정:
Auto-accept edits - 검증이 잦은 루틴: allowlist + hooks
- 외부 API, 배포, 데이터 변경: 여전히 보수적으로
도구를 잘 쓰는 사람보다 어떤 작업은 읽기 전용으로 묶고 어떤 작업은 자동화 허용할지를 먼저 나누는 사람이 덜 망한다.
CLAUDE.md가 생각보다 훨씬 중요하다
Anthropic 공식 문서는 Claude Code가 세션 시작 시 현재 디렉토리 파일, git 상태, 최근 커밋, CLAUDE.md, auto memory, skills, MCP 설정 등을 불러온다고 설명한다. 이 말은 곧 “세션 초반 컨텍스트”가 성능에 직결된다는 뜻이다.
많은 사람이 여기서 프롬프트만 신경 쓰는데, 실제로는 CLAUDE.md가 더 오래 간다. 대화 초반에 했던 지시는 컨텍스트 압축 중 사라질 수 있지만 CLAUDE.md는 세션마다 다시 로드된다.
내가 보기엔 Claude Code 운영에서 CLAUDE.md 역할은 이거다.
- 팀 규칙을 세션마다 재주입하는 상수
- 말로 매번 설명하기 귀찮은 프로젝트 계약서
- 컨텍스트 압축 이후에도 남겨야 할 최소 질서
한 번 잘 적어두면 “왜 자꾸 테스트 안 돌리고 끝내냐”, “왜 상대경로로 링크 쓰냐” 같은 잔소리를 세션마다 반복 안 해도 된다. 이건 생산성보다 멘탈 건강에 좋다. AI한테 같은 말 백 번 하는 것도 노동이거든.
hooks는 자동화 스위치고, subagents는 컨텍스트 다이어트다
공식 Hooks reference 문서는 hooks를 Claude Code 라이프사이클 특정 지점에서 자동 실행되는 사용자 정의 셸 명령, HTTP 엔드포인트, LLM 프롬프트로 설명한다. 이벤트도 꽤 많다.
SessionStartPreToolUsePermissionRequestPostToolUseSubagentStartTaskCreatedPreCompactSessionEnd
즉 hooks는 그냥 “테스트 자동 실행” 수준이 아니라, Claude Code 안에서 벌어지는 흐름에 끼어드는 자동화 훅 포인트다.
hooks가 빛나는 자리
- 파일 편집 뒤 자동 테스트
- 세션 시작 때 프로젝트 상태 브리핑
- 특정 도구 실행 전 정책 확인
- 컴팩션 전에 메모 정리
특히 공식 문서 예시처럼 PostToolUse에서 파일 변경 후 백그라운드 테스트를 돌리는 패턴은 바로 실전에 쓸 만하다. 이런 건 단순하지만 팀 전체 생산성엔 꽤 크게 먹힌다.
반대로 subagents는 다른 문제를 푼다. Create custom subagents 문서 기준으로 subagent는 자체 컨텍스트 창, 별도 시스템 프롬프트, 도구 제한, 독립 권한을 가진 특화 작업자다. 핵심 포인트는 독립된 문맥이다.
subagents가 필요한 이유
- 탐색 결과가 메인 세션 문맥을 더럽히지 않음
- 읽기 전용 조사 역할을 따로 분리 가능
- 특정 작업을 더 싼 모델이나 좁은 권한으로 제한 가능
- 병렬 조사나 반복 작업에서 메인 세션 집중력 유지
쉽게 말하면 hooks는 “자동 반사 신경”, subagents는 “일 따로 시키는 알바”에 가깝다.
긴 세션에서 성능이 흔들리는 진짜 이유
Claude Code를 오래 붙들다 보면 “아까는 잘 알아듣더니 왜 갑자기 멍청해졌지?” 싶은 순간이 온다. 공식 문서는 이유를 꽤 솔직하게 말한다. 컨텍스트가 차면 오래된 출력이 지워지고, 필요하면 대화가 요약된다. 핵심 요청과 일부 코드 조각은 남지만, 초기의 세세한 지시가 사라질 수 있다.
여기서 실전 감각이 필요하다.
이런 신호가 오면 컨텍스트 비만이다
- 같은 규칙을 또 어김
- 이미 읽은 파일을 다시 처음처럼 읽음
- 하위 작업이 자꾸 메인 세션을 잡아먹음
- 응답은 길어지는데 밀도는 떨어짐
이럴 때 해법은 모델 교체가 아니라 구조 조정이다.
- 지속 규칙은
CLAUDE.md - 자주 재사용하는 절차는 skills
- 조사성 작업은 subagents
- 중간 정리는
/compact
즉 성능이 떨어졌다고 무조건 “더 비싼 모델”부터 찾으면 안 된다. 헬스장 등록 안 하고 영양제만 추가하는 꼴 날 수 있다.
그럼 실무에선 어떤 순서로 세팅하면 되나
내 추천은 이 순서다.
1. CLAUDE.md부터 세팅
- 프로젝트 목적
- 금지사항
- 자주 쓰는 명령
- 리뷰/테스트 규칙
2. permission mode 기준 정하기
- 읽기만 하는 조사
- 편집 위주 구현
- 외부 영향 있는 명령
이 셋을 같은 모드로 굴리면 체감이 급격히 나빠진다.
3. hooks는 하나만 먼저 붙이기
초반엔 욕심내지 말고 “파일 수정 후 테스트” 같은 것부터 하나 붙이는 게 낫다. hooks는 많아질수록 멋있어 보이지만, 관리 안 되면 자동화가 아니라 자동 귀찮음이 된다.
4. subagents는 고정 역할부터
- 코드 탐색
- 문서 조사
- 리뷰 보조
메인 세션과 쓰임이 분명히 다른 역할부터 나누는 게 좋다.
Claude Code를 잘 쓰는 사람의 사고방식
이제 중요한 얘기. Claude Code를 잘 쓰는 사람은 기능을 많이 외운 사람이 아니다. 다음 질문을 먼저 하는 사람이다.
- 이 작업은 메인 세션이 해야 하나?
- 이건 승인받아야 하나, 자동화해도 되나?
- 이 규칙은 대화에 둘까, CLAUDE.md에 둘까?
- 이 작업 결과를 메인 컨텍스트에 남겨야 하나?
이 질문이 먼저 나오면 Claude Code는 그냥 코딩툴이 아니라 꽤 괜찮은 운영 파트너가 된다.
반대로 기능 목록만 외우고 구조를 안 보면, 결국 “한 번 잘 됐던 프롬프트 복권”만 긁게 된다. 그건 생산성 툴이 아니라 미신이다.
실수 TOP 5
1. hooks를 기능처럼 보고 운영 규칙으로 안 보는 실수
hooks는 예쁜 부가기능이 아니라 정책 자동화 포인트다.
2. subagents를 많이 만들수록 좋은 줄 아는 실수
분리 기준이 없으면 작은 팀장이 열 명 생긴다. 시끄럽기만 하다.
3. 모든 규칙을 채팅으로만 반복하는 실수
지속 규칙은 CLAUDE.md로 빼야 한다.
4. 승인 루프를 성가신 팝업 정도로 보는 실수
permission mode는 안전장치이자 생산성 스위치다.
5. 컨텍스트 압축 이후 성능 저하를 모델 탓만 하는 실수
구조 문제를 지능 문제로 오해하면 계속 비싼 해결책만 찾게 된다.
FAQ
Q. Claude Code는 결국 터미널 챗봇 아닌가요?
아니다. 공식 문서 기준으로는 모델 위에 도구, 권한, 컨텍스트 관리, 세션 저장이 얹힌 에이전트 실행 환경에 더 가깝다.
Q. hooks부터 공부해야 하나요, subagents부터 공부해야 하나요?
반복 자동화가 먼저면 hooks, 문맥 분리가 먼저면 subagents다. 보통은 hooks 1개 붙이고 subagent 1개 만드는 순서가 제일 덜 꼬인다.
Q. 왜 긴 세션에서 점점 성능이 흔들리나요?
컨텍스트가 차면 오래된 출력이 정리되고 일부 지시가 요약되기 때문이다. 지속 규칙은 CLAUDE.md로 빼는 게 낫다.
Q. Codex나 Cursor랑 같이 써도 되나요?
된다. 오히려 역할 분담이 분명하면 더 좋다. Claude Code는 긴 세션 운영과 규칙화에 강점이 있고, 다른 런타임은 구현이나 좁은 수정에 더 편한 구간이 있다.
다음에 읽을 글
- Claude Code 권한 설계 체크리스트 2026 — hooks·subagents·세션 분리 어디서부터 막아야 하나
- Claude Code 비용 줄이는 운영 루틴 2026 — Pro·Max·API를 작업별로 섞어 쓰는 기준표
- Claude Cowork Dispatch 실전기 2026 — 폰에서 시키고 PC에서 끝내는 비동기 에이전트 루프