저자가 취미와 업무 현장에서 Claude Code를 어떻게 운영·설정·확장하는지—from CLAUDE.md, 컨텍스트·슬래시 명령어, 서브에이전트, 훅, 계획 모드, Skills와 MCP, SDK와 GitHub Action, settings.json까지—실전 팁과 철학을 정리한다.
나는 Claude Code를 정말 많이 쓴다.
취미로는 VM에서 일주일에 몇 번씩 사이드 프로젝트를 하며, 종종 --dangerously-skip-permissions로 마음에 떠오른 아이디어를 바이브 코딩(vibe code)한다. 일적으로는 우리 팀 일부가 엔지니어링 팀을 위한 AI-IDE 규칙과 툴링을 구축하는데, 코드 생성만으로도 매달 수십억 토큰을 소비한다.
CLI 에이전트 영역은 점점 붐비고 있고, Claude Code, Gemini CLI, Cursor, Codex CLI 사이에서 실제 레이스는 Anthropic과 OpenAI 간의 경쟁처럼 느껴진다. 하지만 솔직히, 다른 개발자들과 얘기해 보면 선택은 종종 피상적인 요인—“운 좋게” 잘 구현된 기능 하나나 그냥 취향에 맞는 시스템 프롬프트의 바이브—로 갈리는 경우가 많다. 현시점에서 이 도구들은 대부분 꽤 좋다. 또 사람들은 출력 스타일이나 UI에 과하게 집착하는 경향이 있다고 느낀다. 예컨대 나에게 “당신 말이 100% 맞아요!” 식의 아첨은 결함이라기보다는, 당신이 에이전트 루프에 너무 깊이 끼어 있다는 신호다. 내 목표는 대개 “쏘고 잊기(shoot and forget)”—위임하고, 컨텍스트를 잡아주고, 나머지는 알아서 일하게 두는 것—이다. 과정이 아니라 최종 PR로 도구를 판단한다.
지난 몇 달 동안 Claude Code에 꾸준히 머물러 보며, 이 글은 Claude Code 전체 생태계에 대한 내 성찰을 정리한 것이다. 내가 쓰는 거의 모든 기능(그리고 중요하게는 쓰지 않는 것들) — 기본이 되는 CLAUDE.md 파일과 커스텀 슬래시 명령어부터 강력한 Subagents, Hooks, GitHub Actions까지 — 을 다룬다. 이 글은 꽤 길어졌고, 처음부터 끝까지 읽기보다는 참고서처럼 필요한 부분을 찾아보길 권한다.
코드베이스에서 Claude Code를 효과적으로 쓰는 데 가장 중요한 단일 파일은 루트의 CLAUDE.md다. 이 파일은 에이전트의 “헌법”이며, 해당 레포지토리가 어떻게 작동하는지에 대한 주된 진실의 원천이다.
이 파일을 어떻게 다룰지는 상황에 따라 다르다. 취미 프로젝트에선 Claude가 원하면 무엇이든 거기에 덤프하게 둔다.
업무에선, 우리 모노레포의 CLAUDE.md는 엄격하게 관리되며 현재 13KB 수준이다(25KB까지 커져도 이상하진 않다).
CLAUDE.md에 들어갈 준비가 안 된 것이다.시간이 지나며 우리는 효과적인 CLAUDE.md를 작성하기 위한 강한(의견이 분명한) 철학을 갖게 됐다.
@로 끌어오지 말라. 방대한 문서가 어딘가에 따로 있다면, CLAUDE.md에서 그 파일을 @로 언급하고 끌어오기 쉽다. 하지만 이렇게 하면 매 실행마다 전체 파일을 임베딩하여 컨텍스트 윈도우를 부풀린다. 반면 경로만 “언급”하면 Claude가 종종 무시한다. 왜, 언제 그 파일을 읽어야 하는지 에이전트에 설득(pitch)해야 한다. “복잡한 … 사용법이 필요하거나 FooBarError를 만난 경우, 고급 트러블슈팅은 path/to/docs.md를 참조하세요.”--foo-bar 플래그를 쓰지 마라” 같은 부정 제약만 두면, 에이전트는 해당 플래그를 꼭 써야 한다고 생각할 때 막힌다. 항상 대안을 제시하라.CLAUDE.md를 강제 장치(Forcing Function)로 활용하라. CLI 명령이 복잡하고 장황하다면, 이를 설명하기 위한 문단을 쓰지 마라. 그건 사람 문제를 덕지덕지 덮는 것이다. 대신 간단한 bash 래퍼로 명확하고 직관적인 API를 만들고 그걸 문서화하라. CLAUDE.md를 최대한 짧게 유지하는 것은 코드베이스와 내부 툴링을 단순화하도록 만드는 훌륭한 강제 장치다.여기 간단히 축약한 스냅샷이 있다:
# 모노레포
## Python
- 항상 ...
- 테스트는 <command>
... 10개 더 ...
## <내부 CLI 도구>
... 상위 80% 사용 사례에 초점을 둔 10개의 불릿 ...
- <사용 예시>
- 항상 ...
- <x>는 금지, <Y>를 권장
<복잡한 사용법> 또는 <오류>가 있으면 path/to/<tool>_docs.md 참고
...
마지막으로, 우리는 이 파일을 AGENTS.md와 동기화하여, 우리 엔지니어들이 사용할 수 있는 다른 AI IDE들과의 호환성을 유지한다.
문서 작성 팁을 더 찾고 있다면 다음 글을 참고하라: “AI Can’t Read Your Docs”, “AI-powered Software Engineering”, “How Cursor (AI IDE) Works”
굵은 요약: CLAUDE.md는 고수준의, 큐레이션된 가드레일과 포인터 모음으로 다뤄라. 포괄적인 매뉴얼을 만들려 하기보다 어디에 더 AI(와 인간) 친화적인 도구 투자가 필요한지 이 파일을 통해 이끌어내라.
코딩 세션 중간에 최소 한 번은 /context를 실행해 200k 토큰 컨텍스트 윈도우를 어떻게 쓰고 있는지 확인하길 권한다(설령 Sonnet-1M이라도, 전체 컨텍스트가 실제로 효과적으로 사용된다고 믿지 않는다). 우리 기준으로 모노레포에서 새 세션은 기본 비용이 약 2만 토큰(10%)이고, 나머지 18만 토큰이 실제 변경 작업에 쓰인다 — 그리고 이건 꽤 빨리 찬다.
최근 사이드 프로젝트에서 본 /context 스크린샷. 기능을 개발하며 차오르는 디스크 공간처럼 생각하면 된다. 몇 분 혹은 몇 시간이 지나면 계속 작업할 공간을 만들기 위해 메시지(보라색)를 비워야 한다.
내 주요 워크플로는 세 가지다:
/compact(비추천): 가능하면 피한다. 자동 압축은 불투명하고, 오류가 잦으며 최적화도 잘 되어 있지 않다./clear** + /catchup(간단 재시작):** 내 기본 리부트. 상태를 /clear로 비우고, 커스텀 /catchup 명령을 실행해 현재 git 브랜치에서 변경된 모든 파일을 읽도록 Claude에 지시한다..md로 덤프하게 하고, 상태를 /clear로 비운 뒤, 새 세션에서 그 .md를 읽고 이어서 진행하라고 지시한다.굵은 요약: 자동 압축을 신뢰하지 마라. 단순 재시작엔 /clear, 복잡한 작업의 내구성 있는 외부 “메모리”를 만들 땐 “문서화 & 초기화”를 써라.
슬래시 명령은 자주 쓰는 프롬프트에 대한 단순한 단축키일 뿐이라고 생각한다. 내 구성은 최소한이다:
/catchup: 앞서 언급한 명령. 현재 git 브랜치에서 변경된 모든 파일을 읽어오라고 Claude에 프롬프트한다./pr: 코드를 정리하고, 스테이징하고, Pull Request를 준비하는 간단한 헬퍼.개인적으로 커스텀 슬래시 명령이 길고 복잡한 리스트가 되면 안티 패턴이라 본다. Claude 같은 에이전트의 요점은 거의 “아무 말이나” 해도 유용하고 머지 가능한 결과를 준다는 데 있다. 엔지니어(혹은 비엔지니어)에게 업무를 하기 위해 꼭 알아야 하는 마법 명령어 목록을 새로 배우게 만든 순간 실패한 것이다.
굵은 요약: 슬래시 명령은 개인적인 단축키로만 써라. 직관적인 CLAUDE.md와 더 나은 툴링을 대체하려 하지 마라.
이론적으로, 커스텀 서브에이전트는 컨텍스트 관리를 위한 Claude Code의 가장 강력한 기능이다. 피치는 단순하다: 복잡한 작업은 입력 컨텍스트 X(예: 테스트 실행 방법), 작업 중 컨텍스트 Y, 그리고 결과 Z 토큰을 필요로 한다. N개의 작업을 돌리면 메인 윈도우에는 (X + Y + Z) * N 토큰이 든다.
서브에이전트 해법은 (X + Y) * N에 해당하는 일을 특화 에이전트로 외주 주고, 최종 Z만 반환하게 하여 메인 컨텍스트를 깔끔하게 유지하는 것이다.
나는 이 아이디어가 강력하다고 본다. 그러나 실제로는, 커스텀 서브에이전트가 두 가지 새로운 문제를 만든다:
PythonTests 서브에이전트를 만들면, 이제 모든 테스트 컨텍스트가 메인 에이전트에서 숨겨진다. 메인 에이전트는 변경을 전체적으로 추론할 수 없게 되고, 자신의 코드를 검증하는 방법을 알기 위해서라도 서브에이전트를 호출해야 한다.내가 선호하는 대안은 Claude의 내장 Task(...) 기능을 써서 “일반” 에이전트의 클론을 스폰하는 것이다.
핵심 컨텍스트는 전부 CLAUDE.md에 둔다. 그리고 메인 에이전트가 스스로 언제, 어떻게 자신의 복제본에게 일을 위임할지 결정하게 둔다. 이렇게 하면 서브에이전트의 장점(컨텍스트 절약)은 그대로 누리면서 단점은 피할 수 있다. 에이전트가 자체적으로 동적으로 오케스트레이션을 관리한다.
내 글 “Building Multi-Agent Systems (Part 2)”에서 이를 “마스터-클론(Master-Clone)” 아키텍처라고 불렀고, 커스텀 서브에이전트가 권장하는 “리드-스페셜리스트(Lead-Specialist)” 모델보다 훨씬 선호한다.
굵은 요약: 커스텀 서브에이전트는 쉽게 부서지는 해법이다. 메인 에이전트에 CLAUDE.md로 컨텍스트를 주고, 위임 관리는 에이전트의 Task/Explore(...) 기능에 맡겨라.
단순한 수준에서, 나는 claude --resume과 claude --continue를 자주 쓴다. 버그가 난 터미널을 재시작하거나 오래된 세션을 재부팅할 때 좋다. 며칠 지난 세션을 claude --resume으로 열어 특정 오류를 어떻게 극복했는지 요약해 달라고 요청하고, 그걸 CLAUDE.md와 내부 툴링 개선에 반영하곤 한다.
좀 더 파고들면, Claude Code는 모든 세션 히스토리를 ~/.claude/projects/에 저장한다. 원시 히스토리 데이터를 직접 살펴볼 수 있다. 나는 이 로그에 메타 분석을 돌려, 흔한 예외, 권한 요청, 오류 패턴을 찾아 에이전트가 보는 컨텍스트를 개선한다.
굵은 요약: 세션 재시작과 묻혀 있던 과거 컨텍스트를 발굴하는 데 claude --resume과 claude --continue를 활용하라.
Hooks는 매우 중요하다. 취미 프로젝트에서는 쓰지 않지만, 복잡한 엔터프라이즈 레포를 다룰 때는 Claude를 올바르게 유도하는 데 핵심적이다. CLAUDE.md의 “해야 한다(should-do)” 제안들을 보완하는, 결정론적 “반드시 한다(must-do)” 규칙이다.
우리는 두 가지 타입을 쓴다:
Bash(git commit) 명령을 감싸는 PreToolUse 훅이 있다. 이 훅은 /tmp/agent-pre-commit-pass 파일을 확인하는데, 이 파일은 모든 테스트가 통과한 경우에만 테스트 스크립트가 만든다. 파일이 없으면 커밋을 차단하고, 빌드가 초록불이 될 때까지 Claude를 “테스트-수정” 루프에 넣는다.우리는 의도적으로 “쓰기 시 차단”(예: Edit나 Write 단계) 훅은 쓰지 않는다. 계획 중인 에이전트를 중간에 막으면 에이전트가 혼란스럽거나 심지어 “좌절”한다. 작업을 끝까지 하게 둔 뒤, 최종 결과를 커밋 단계에서 검증하는 편이 훨씬 효과적이다.
굵은 요약: 훅은 커밋 시점(제출 차단)의 상태 검증을 강제하는 데 쓰고, 쓰기 시점 차단은 피하라—에이전트가 계획을 끝내게 두고 최종 결과를 점검하라.
계획(Planning)은 AI IDE로 “큰” 기능을 바꿀 때 필수다.
취미 프로젝트에서는 내장 계획 모드만 쓴다. 시작 전에 Claude와 정렬하는 방식으로, 무엇을 어떻게 만들지와 어디서 “검사 체크포인트”를 세우고 중간 결과를 보여줄지 정한다. 이를 자주 쓰면 최소한의 컨텍스트로 좋은 계획을 얻고, Claude가 구현을 망치지 않게 하는 직관이 생긴다.
업무용 모노레포에서는 Claude Code SDK 위에 맞춤 계획 도구를 만들기 시작했다. 기본 계획 모드와 비슷하지만, 기존 기술 설계 포맷과 출력이 맞춰지도록 강하게 프롬프트되어 있다. 코드 구조부터 데이터 프라이버시와 보안까지 내부 모범 관행도 기본으로 강제한다. 덕분에 엔지니어들은 시니어 아키텍트처럼(적어도 그런 피치다) 새 기능을 바이브 플랜할 수 있다.
굵은 요약: 복잡한 변경에는 항상 내장 계획 모드를 써서 에이전트가 작업을 시작하기 전에 계획을 정렬하라.
나는 Simon Willison의 의견에 동의한다: Skills는 (어쩌면) MCP보다 더 큰 일이다.
내 글들을 따라온 사람이라면, 대부분의 개발 워크플로에서 MCP에서 멀어져 대신 단순한 CLI를 만드는 쪽으로 기울었다는 걸 알 것이다(이는 “AI Can’t Read Your Docs”에서 주장했다). 에이전트 자율성에 대한 내 멘탈 모델은 다음 세 단계로 진화했다:
이 모델을 염두에 두면, 에이전트 Skills는 다음에 나올 자명한 기능이다. “스크립팅” 레이어의 정식 제품화다.
나처럼 이미 MCP보다 CLI를 선호해 왔다면, 사실 Skills의 이점을 암묵적으로 계속 누려온 셈이다. SKILL.md는 이런 CLI와 스크립트를 문서화하고 에이전트에 노출하는 더 조직적이고 공유 가능하며 검색 가능한 방법일 뿐이다.
굵은 요약: Skills는 올바른 추상화다. 이는 API 같은 경직된 MCP 모델보다 더 견고하고 유연한 “스크립팅” 기반 에이전트 모델을 정식화한다.
Skills가 MCP의 종말을 뜻하는 건 아니다(참고: “Everything Wrong with MCP”). 이전에는 많은 이들이 끔찍하고 컨텍스트-무거운 MCP를 만들었는데, 수십 개의 도구로 REST API를 그대로 거울처럼 복제했다(read_thing_a(), read_thing_b(), update_thing_c() 같은 식).
“스크립팅” 모델(이제 Skills로 정식화됨)은 더 낫지만, 환경에 접근할 안전한 방법이 필요하다. 이게 내가 생각하는, 더 집중된 MCP의 새로운 역할이다.
부풀어 오른 API 대신, MCP는 몇 개의 강력하고 고수준 도구를 제공하는 단순하고 안전한 게이트웨이가 되어야 한다:
download_raw_data(filters…)take_sensitive_gated_action(args…)execute_code_in_environment_with_state(code…)이 모델에서 MCP의 일은 에이전트를 위해 현실을 추상화하는 것이 아니라, 인증/네트워킹/보안 경계를 관리하고 나서는 비켜서는 것이다. MCP는 에이전트에 대한 입구 를 제공하고, 에이전트는 자신의 스크립팅과 markdown 컨텍스트로 실제 일을 수행한다.
내가 여전히 쓰는 유일한 MCP는 Playwright다. 복잡하고 상태가 있는 환경이라 말이 된다. Jira, AWS, GitHub 같은 무상태 도구는 전부 단순 CLI로 옮겼다.
굵은 요약: MCP는 데이터 게이트웨이로 쓰라. 에이전트에 한두 개의 고수준 도구(예: 원시 데이터 덤프 API)를 주고, 그 위를 스크립팅하게 하라.
Claude Code는 대화형 CLI에 그치지 않고, 코딩/비코딩 작업 모두를 위한 완전한 신규 에이전트를 만들 수 있는 강력한 SDK이기도 하다. 대부분의 새 취미 프로젝트에서 LangChain/CrewAI 같은 도구 대신 기본 에이전트 프레임워크로 쓰기 시작했다.
나는 세 가지 방식으로 주로 쓴다:
claude -p "in /pathA change all refs from foo to bar"를 병렬로 호출한다. 메인 에이전트가 수십 개의 서브에이전트 작업을 관리하게 하려 애쓰는 것보다 훨씬 확장 가능하고 통제 가능하다.굵은 요약: Claude Code SDK는 강력한 범용 에이전트 프레임워크다. 대량 코드 처리, 내부 도구 구축, 복잡한 프레임워크로 가기 전의 빠른 에이전트 프로토타이핑에 써라.
Claude Code GitHub Action(GHA)은 아마 내가 가장 좋아하고, 또 가장 저평가된 기능일 것이다. 개념은 단순하다: GHA에서 Claude Code를 실행한다. 그런데 이 단순함이 바로 강점이다.
Cursor의 백그라운드 에이전트나 Codex의 매니지드 웹 UI와 비슷하지만 훨씬 더 커스터마이즈 가능하다. 컨테이너와 환경 전체를 당신이 통제하므로 데이터 접근이 넓고, 무엇보다 다른 어떤 제품보다 더 강력한 샌드박싱과 감사 통제가 가능하다. 게다가 Hooks와 MCP 같은 고급 기능도 모두 지원한다.
우리는 이를 사용해 커스텀 “어디서나 PR” 툴링을 만들었다. 사용자는 Slack, Jira, 심지어 CloudWatch 알림에서도 PR을 트리거할 수 있고, GHA가 버그를 고치거나 기능을 추가한 뒤 완전히 테스트된 PR을 돌려준다1.
GHA 로그가 곧 전체 에이전트 로그이므로, 회사 차원에서 이 로그를 정기적으로 리뷰하는 운영 프로세스를 갖고 있다. 흔한 실수, bash 에러, 정렬되지 않은 엔지니어링 관행을 찾는다. 이렇게 데이터 기반 플라이휠이 만들어진다: 버그 -> 개선된 CLAUDE.md / CLI -> 더 나아진 에이전트.
$ query-claude-gha-logs --since 5d | claude -p “see what the other claudes were getting stuck on and fix it, then put up a PR“
굵은 요약: GHA는 Claude Code를 운영화하는 궁극의 방법이다. 개인 도구를 넘어, 감시 가능하고 스스로 개선되는 엔지니어링 시스템의 핵심 구성요소로 만든다.
마지막으로, 취미와 업무 모두에 필수적이라고 느낀 몇 가지 settings.json 설정이 있다.
HTTPS_PROXY/HTTP_PROXY: 디버깅에 훌륭하다. Claude가 정확히 어떤 프롬프트를 보내는지 원시 트래픽을 들여다보는 데 쓴다. 백그라운드 에이전트 환경에서는 미세한 네트워크 샌드박싱을 위한 강력한 도구이기도 하다.MCP_TOOL_TIMEOUT/BASH_MAX_TIMEOUT_MS: 나는 값을 키운다. 길고 복잡한 명령을 돌리는 걸 좋아하는데, 기본 타임아웃은 종종 보수적이다. bash 백그라운드 태스크가 생긴 지금도 여전히 필요한지는 잘 모르겠지만, 일단 유지한다.ANTHROPIC_API_KEY: 업무에선 엔터프라이즈 API 키를 쓴다(apiKeyHelper 경유). “시트당” 라이선스에서 “사용량 기반” 과금으로 전환되어, 우리의 작업 방식에 훨씬 맞는다.
"permissions": Claude가 자동 실행하도록 허용한 명령 목록을 가끔 셀프 감사한다.굵은 요약: settings.json은 고급 커스터마이즈를 위한 강력한 지점이다.
양이 많았지만, 유용했길 바란다. 아직 Claude Code나 Codex CLI 같은 CLI 기반 에이전트를 쓰지 않는다면, 아마 써야 할 것이다. 이런 고급 기능에 대한 좋은 가이드는 드물다. 배우는 유일한 방법은 직접 뛰어드는 것이다.
내게 꽤 흥미로운 철학적 질문은, 고객 요청으로 직접 생성된 PR(내부 인간 프롬프터 없음)은 리뷰를 몇 명 받아야 하는가?라는 점이다. 우리는 현재 AI가 시작한 PR에는 사람 승인 2개를 요구하는 것으로 정했다. 하지만 더 이상 “사람이 무언가를 만들고 다른 사람이 리뷰하는” 구조가 아니라는 점에서(적어도 내겐) 묘한 패러다임 전환처럼 느껴진다.