다만, 그런 마음이 무색하게도 이제 저는 클로드 코드에 불만이 아주 많습니다. 왜 더 많은 일을 하지 않지? 왜 알아서 해주지 않지? 왜 이렇게 멍청해지는 거지? 그 문제를 해결하고자 이런저런 곳을 떠돌다, 클로드 코드 팀의 엔지니어인 Daisy Hollman의 워크숍 영상을 접했습니다.

“이 시점에서 소프트웨어 엔지니어의 일은, 자신의 작은 복제를 만들어 여러 에이전트에 걸쳐 능력을 스케일하는 것입니다.”

발표를 보고 정신이 번쩍 들었습니다. 여기저기서 눈으로는 봤지만, 머리로는 이해하지 못했던 ‘하는 일을 더 잘 하기 위해’ AI를 쓰라는 말을 제대로 이해할 수 있었습니다. 그러기 위해서는 클로드 코드를 어떻게 세팅해야 하는지도요. 정말 좋은 이야기가 많아, 핵심을 정리해 다시 나누고자 글을 썼습니다. 최대한 지금 제 문제에 와닿는 이야기를 중심으로 다시 구성해 봤습니다.

- Daisy Hollman, 〈Beyond the Basics with Claude Code〉, Code with Claude.

글에서 이탈릭 체로 처리한 모든 대화체는 발표에서 인용한 글입니다.

왜 클로드 코드를 커스텀해야 하는가?

클로드 코드를 있는 그대로 쓰다 보면 왜 이렇게 아쉬운 느낌이 들까요? 답은 명쾌했습니다.

여러분이 할 수 있는 모든 걸 할 수 없다면, 클로드는 당신의 일을 함께할 수 없습니다.

Daisy는 클로드 코드의 커스텀이 필요한 이유를 접근(Access), 지식(Knowledge), 도구 세팅(Tooling) 세 가지 문제로 나눠 설명합니다.

1. 접근(Access)

클로드 코드가 접근하지 못하는 곳에 있는 정보는 모두 핸디캡이 됩니다. 이를테면 결정은 슬랙에서 일어났는데, 디자인 문서는 피그마에 있고, 로그는 컨플루언스에 있다고 합시다. 흔한 상황이죠. 다만, 사람이 그 사이를 쉽게 오가는 반면 AI는 그렇지 않습니다. 이 페이지들을 클로드에 연결하다 보면, 생각보다 정말 많은 맥락이 누락된 것을 깨달을 수 있습니다.

종일 클로드 코드 터미널을 떠나지 않고 일해보세요. 만약 (터미널을 벗어나) Alt-Tab을 누르면, 그건 클로드가 못 보고 있는 정보일 거예요.

그렇다면 반드시 연결해야 하는 것들로는 뭐가 있을까요? 프로페셔널한 엔지니어링 업무에 필요한 것은, 특히 규모가 클수록, 대부분 실제 소스 코드 바깥에 있습니다. 채팅, CI/CD, 대시보드, 사내 문서, 디자인 문서…. 사실상 일할 때 보는 모든 것이 맞겠습니다.

2. 지식(Knowledge)

다만, 이런 봐야 하는 것들에는 암묵지인 ‘지식’들 역시 있습니다. 코드를 쓰는 규칙, 기업에 특화된 정보, 사내에서만 쓰는 표현들. 다만, 이런 정보를 모델 자체에 학습시키는 건 나쁜 생각이라고 합니다. 실제 특수 정보로 모델을 파인튜닝하면 환각이 늘 수 있다는 연구가 있는 데다가, 프론티어 모델 주기가 워낙 빨라 효율도 안 나오니까요. 결국 장기적으로는 일반 AI가 특화 AI 보다 나아질 가능성이 높습니다.

남은 건 ICL(in-context learning)입니다. ICL은 똑똑해 보이고 싶을 때 쓰는 말인데, 사실 그냥 텍스트 파일입니다. CLAUDE.md, SKILL.md, Sub-agent를 정의하는 파일들. 이런 것들이 모두 ICL에 해당합니다.

다만, 정말 이런 정보를 그냥 ‘텍스트 파일’로만 두면 안 됩니다. 대부분 만들기가 쉬우니 “이만하면 됐겠지”하고 멈추지만, 그래서는 진짜 지식으로 작동하지 않습니다. 최적화가 필요합니다.

3. 도구 세팅(Tooling)

그럼 이러한 접근을 열어주고, 지식을 연결했을 때, 클로드를 위한 도구는 무슨 형태가 적합할까요?

Daisy에 따르면 도구는 크게 두 가지, 모델의 지능이 부족한 것을 막아줄 도구, 모델이 좋아질수록 유용해지는 스케일 도구로 나눌 수 있습니다. 지금 우리에게 필요한 건 모델이 좋아질수록 유용해지는 도구입니다.

변수를 잘못 썼거나 함수에 인자 수가 안 맞을 때 뜨는 빨갛고 꼬불꼬불한 선(red squiggles)이 여러분의 뇌에 어떤 일을 하는지 생각해 보세요. 완전히 멈추게 하지는 않지만, “잠깐 다시 생각해볼까?”하는 방향으로 밀어주죠. 그러니까, 무시할 수 있지만, 다시 한 번 생각하게 만듭니다. 에이전트한테도 이런 게 있었으면 합니다

Hook을 쓸 수도 있고, 린터를 돌릴 수도 있고, LSP 연결을 생각해 볼 수도 있을 겁니다. 이런 피드백을 줄 알림을 세팅하는 것도 방법이고요. 어쨌든 아예 정의되지 않은 변수를 ‘절대’ 못 쓰게 막는 방식 같은 건 실수는 줄여도 성장을 만들기는 어렵습니다. 강요는 좋은 결과를 만들기 어렵죠. 넛지(nudge), 즉, 잊기 쉬운 무언가를 떠올리게 해주는 것이 중요합니다.

그런 맥락에서 에이전트를 코드베이스에 잘 맞추는 가장 빠른 방법은 더 똑똑한 모델이 아니라, 더 빡빡한 피드백 루프를 구축하는 겁니다.

+ 컨텍스트 윈도우라는 제약

하나 더, 짚고 넘어가야 할 것이 있습니다. 지난 1년간 프론티어 모델의 컨텍스트 윈도우 크기는 거의 변하지 않았습니다. 요즘 최신 모델들은 1M까지 지원하고, 그 이상은 잘 커지지 않습니다. 모델이 어느 정도는 본질적인 한계처럼 보이는 지점에 와 있기 때문일지도 모릅니다. 그러니 코드베이스 전체를 부어넣을 수는 없습니다. 위키 전체나 사내 문서 전체를 다 부어넣을 수 없죠.

여기에 LLM은 KV 캐시 구조를 적용합니다. 프롬프트를 앞에서부터 읽어나가며, 이를 기록해 두고, 다음 출력에 이를 적용시킨다는 뜻이죠. 그러니 프롬프트 앞쪽에서 무언가 바꾸면, 그 변경 뒤의 컨텍스트 윈도우 전체에 토큰 비용을 내야 합니다. 보통 10배 더 비싼 값을 치뤄야 합니다. 결국 안정적으로 돌아가야 하는 걸 앞단에 두고, 휘발되는 태스크 중심 업무는 뒤쪽에 배치해야 합니다.

안 쓰는 거에 돈을 내지 마라(Don’t pay for what you don’t use). 이건 지키면 좋은 수준(nice-to-have)의 규칙이 아닙니다. 결국 적절한 정보를 적절한 시점에 넣을 더 나은 방법을 반드시 찾아야 합니다.

그래서 무슨 도구로 커스텀을 해야 할까?: MCP, Skills, Hooks, Agents

그렇다면 이런 커스터마이징을 어떻게 해야 할까요? 사실 지금까지 개발자들이 제대로 일하기 위해, 이런 환경은 모두 만들어뒀습니다. 필요한 도구는 이미 다 있죠. 클로드에 제대로 된 도구를 주기만 하면 됩니다.

그 중 클로드 코드에서 쓰이는 가장 대표적인 4가지 추상화 도구는 MCP, Skills, Hooks, Agents(Sub-agents)입니다.

앞서 본 대로, 스케일을 만들기 위한 대규모 동작을 가정하고 볼 겁니다. 당장 업무 한 두 개만 처리한다고요? 아뇨. 앞으로 우리는 더 AI에 의존적인 시대에 살 겁니다. 그러니 이런 도구가 10,000개, 100,000개는 더 많은 상황을 상정해야 합니다.

그래야 우리에게 쥐어진 모델을 ‘더 잘 하기 위해’ 쓸 수 있겠죠.

1. MCP

MCP는 이 4가지 도구 중 가장 먼저 등장했습니다. 즉, LLM이 지금에 비해 훨씬 단순하던 시기에 설계됐다는 거죠. 그래서 컴퓨터 파일에 접근하지 못하고, 명령어도 못 돌리는 데다, CLI도 못 쓰는 챗봇 환경을 전제로 두었습니다.

여러분에게 이미 CLI가 있다면, 그걸 MCP로 감쌀 이유가 없어요. 그냥 ‘클로드한테 이 CLI 이렇게 써’하고 알려주는 Skills가 훨씬 쉽거든요. 그러니 나 혼자 쓰거나 사내에서 쓸 작업을 MCP로 포장하는 건 권장되지 않습니다.

물론, 회사에서 외부에 클로드와 통합한 무언가를 출시하고 싶을 때는 일단 MCP 서버부터 시작하는 것이 좋습니다. 변환이나 인증을 대부분 처리해 주니까요. 그런 특징 덕에 다른 도구와 이어주는 MCP 서버는 써야 합니다. 슬랙, 지라, 깃허브 같은 도구와의 연동은 여전히 MCP 서버를 거쳐야 합니다.

2. Skills

Daisy는 초기에 Skills를 ‘게으른 시스템 프롬프트(lazy system prompt)’라고 불렀다고 합니다. 쉬운 표현 같아요. 해야하는 일의 순서와 필요한 것들을 자연어로 적어둔 것이니까요. 본질로 들어가도 이건 사실 폴더 하나입니다. 마크다운 문서와 이걸 요약한 무언가들이 함께 있는 폴더죠.

그래서 여기저기 만들어 두기 정말 쉽습니다. 물론 이건 장점이자 단점입니다. 품질을 통제하지 않으면 문제가 생기거든요. 실제로 Skills를 설명(Description)하는 부분은 늘 로드합니다. 언제 호출할 지 알아야 하니까요. 다만 이 설명이 길어지면 비용이 커지고, 짧아지면 필요할 때 쓸 수가 없습니다.

---
description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff.
---

## Current changes

!`git diff HEAD`

## Instructions

Summarize the changes above in two or three bullet points, then list any risks you notice such as missing error handling, hardcoded values, or tests that need updating. If the diff is empty, say there are no uncommitted changes.

Skills.md 예시 <출처: Anthropic>

그러니 어느 정도는 스케일하지만, 레포 하나에 Skill 10만 개가 들어가는 시기는 앤트로픽 내부에서도 미리 생각하지 못했다고 합니다. (결국 Skills에는 아직 계층이 없기 때문에 생기는 문제인데, 몇 주 안에 sub-skill을 노출하는 구조를 작업하고 있다고 합니다. 기대해 봐야겠습니다.)

3. Hooks

그래서 가장 추천하는 방식은 Hooks입니다. 에이전트 루프에서 뭔가 이벤트가 생기고, 그러면 컴퓨터에서 무언가가 실행됩니다. 그 실행 결과를 기준으로 컨텍스트 윈도우에 추가할지 결정합니다. … 매우 제약이 큰 자원의 부담을 훨씬 제약이 덜한 자원으로 떠넘긴 거죠. 이런 시스템을 디자인할 때 찾아야 할 특징은 바로 이런 겁니다.

Hook을 돌릴 때는 토큰을 안 씁니다. 비용이 0원이죠. 이를테면, 한글로 이메일을 쓸 때 필요한 Skills를 만들었다고 합시다. 그런데, 우연찮게 영어로 이메일을 쓸 일이 생겼습니다. 이때 Skills가 돌지 않도록 하려면, “영어일 때는 쓰지 마”라는 규칙을 추가해야 합니다. 이걸 읽고 무시하는 것도 결국은 토큰이고 비용입니다. 하지만 이 타입을 체크하는 Hook이 있으면, 토큰을 쓰지 않고도 알아서 영어인 걸 확인해 Skills를 접근조차 안 하게 해줍니다. 안 쓰는 거에는 확실하게 아무런 비용도 내지 않는 겁니다.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [{ "type": "command", "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write" }]
      }
    ],
    "Notification": [
      {
        "matcher": "",
        "hooks": [{ "type": "command", "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'" }]
      }
    ]
  }
}

hooks 예시 <출처: Anthropic>

물론 그래서 모든 일에 적합하지는 않습니다. 모든 걸 다 할 수 없고 완벽하지도 않습니다. 이걸 넣을지 말지 결정하려면 다시 토큰이 필요합니다. 트레이드오프죠. 그래도 앞서 Daisy가 강조한 에이전트를 위한 도구의 역할, 즉, 빨갛고 꼬불꼬불한 선(red squiggles)에 적합한 영역이 Hooks입니다.

4. Sub-Agents

Sub-Agents는 시스템 프롬프트로 들어가는 설명(description)과 그 자체 시스템 프롬프트로 구조화됩니다. 특정 태스크를 수행하는 데 적합한 구조인데요. 특징적인 건 ‘별도 컨텍스트’를 가지고 돌아간다는 겁니다.

그러니까, CLI에서 사람이 조작하는 메인 루프의 컨텍스트 윈도우를 먹지 않는 게 가장 큽니다. 물론 토큰이 공짜는 아니지만, 에이전트 하나가 토큰을 어떻게 효율적으로 쓸지 생각할 때는 스케일에 효율적입니다. 에이전트가 50개 파일을 읽을 수 있고, 메인 루프는 그 짐을 지지 않아도 되니까요.

다만, 에이전트마다 여전히 설명이 연결되어야 하고, 그러니 10만 개가 생기면 그 설명도 10만 개가 들어가야 한다는 거죠. Skills와 엄청 다른 구조라 보기 어렵습니다.

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---

You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.

Sub-Agent.md Frontmatter 예시 <출처: Anthropic>

+ 플러그인과 CLAUDE.md

사실 클로드 코드가 나온 초기에는 이 CLAUDE.md가 커스텀의 만능 비법처럼 소개되기도 했는데요. 실제로 플러그인에 이걸 넣으면 스케일을 키우기가 매우 쉬워 보이기도 합니다. 다만, Daisy는 ‘플러그인에 CLAUDE.md를 넣어 스케일을 만드는 방식’은 별로 추천하지 않는다고 합니다.

(CLAUDE.md는)매우 비싼 추상인데, 저렴해 보이죠. … 마치 스케일되는 것처럼 보일 뿐입니다. 파일 하나니까요. 그러니 정말정말 하고 싶으면, 세션을 시작하는 훅(session start hook)에서 텍스트를 반환할 수 있게는 열어 두었습니다. 그렇게 하면 ‘내가 사용자에게 매번, 무조건 비용을 내게 하고 있다’게 드러나니까요.

마치며

이제 우리는 어떻게 일해야 하는 걸까요?

클로드 코드 팀이 클로드 코드를 쓰고 만들며 가져가는 두 가지 핵심 테마는 비동기(asynchrony)와 병렬(parallelism)이라고 합니다. 쉽게 말하면 컴퓨터를 떠나 잠시 일을 시키고 돌아올 수 있어야 하며, 여러 개를 동시에 굴리고 싶다는 거죠. 결국 이 역시도 원래 처리하던 일의 수준을 폭발적으로 늘려주는 방식이라고 느껴졌습니다.

그런 만큼 나만을 위해 빨간 선을 그어줄 도구를 미리 세팅하는 게 꼭 필요할 겁니다. 그 때마다 영상에서 본 이 세 가지 격언이 떠오를 것 같아요.

접근 권한을 줄 것(Give it access)
(컨텍스트 윈도우란) 상자를 신경 쓸 것(Mind the box),
스케일할 추상을 고를 것(Pick abstractions that scale).

앞으로는 더 많은 일을 하면서도 더 잘 하는 것이 기본일 겁니다. 쉽지는 않겠지만, 해내야 겠죠. 모두에게 도움이 되었으면 좋겠습니다.