클로드 코드의 플러그인과 에이전트 팀 설계를 이끈 앤트로픽 엔지니어 데이지 홀먼은 CLAUDE.md 가 모든 작업에 정말로 적용되는 몇 줄의 규칙에만 괜찮다고 평가합니다. 왜 그런지를 컨텍스트 윈도우로 풀고, 그 대신 쓰는 훅, 스킬, 서브에이전트를 지금 내 프로젝트에 옮겨 담는 순서까지 적었습니다.
CLAUDE.md 를 잘 써야 한다는 이야기, 많이 들으셨을 겁니다. 그래서 규칙을 열심히 적어뒀는데 클로드 코드가 안 지킵니다. 그래서 더 적습니다. 적을수록 더 안 지킵니다.
그런데 클로드 코드에 플러그인과 에이전트 팀이라는 굵직한 기능을 설계한 사람은 CLAUDE.md 를 아주 좁게 봅니다. 자기가 만든 플러그인에는 CLAUDE.md 기능을 일부러 넣지 않았고요. 지금 공식 문서에도 그대로 적혀 있습니다. 클로드 코드는 플러그인 루트의 CLAUDE.md 를 읽지 않는다고요.
이 글을 다 읽고 나면 아마 내 프로젝트의 하네스를 다시 짜게 되실 겁니다. 그 사람이 CLAUDE.md 대신 무엇을 쓰는지, 그리고 우리가 분명히 적어둔 규칙을 클로드 코드가 왜 안 지키는지까지 같이 보겠습니다.
매번 전체 값을 내는 문서
데이지 홀먼은 앤트로픽에서 클로드 코드의 플러그인과 에이전트 팀의 설계와 구현을 이끈 엔지니어입니다. 2026년 6월 NDC 코펜하겐 강연에서 CLAUDE.md 를 이렇게 평가합니다.
- 대화를 주고받을 때마다 CLAUDE.md 전체만큼의 토큰 비용을 낸다
- 그 비용의 90%는 지금 하는 작업과 상관없는 내용이다
- 그래서 모든 곳에 정말로 적용되는 몇 줄의 규칙에만 괜찮다
슬라이드 마지막 문장 그대로 옮기면 이렇습니다.
Fine for the handful of rules that truly apply everywhere.
그런데 저희는 보통 반대로 씁니다. 생각나는 규칙을 다 거기에 넣죠.
클로드 코드 공식 문서도 같은 방향입니다. CLAUDE.md 는 200줄 이하를 권하고, 길어질수록 더 많은 컨텍스트를 쓰고 규칙을 지키는 정도가 떨어진다고 적어놨습니다.
먼저 컨텍스트 윈도우부터
데이지의 하네스를 보려면 컨텍스트 윈도우를 먼저 짚어야 합니다.
클로드 코드가 한 번에 읽고 처리할 수 있는 최대 분량을 컨텍스트 윈도우라고 합니다. CLAUDE.md 는 대화를 시작할 때마다 내용 전체가 이 컨텍스트 윈도우 맨 앞에 들어갑니다. 그만큼 실제 작업에 쓸 공간이 줄어듭니다.
데이지가 강연에서 한 말도 같습니다. 앞에 넣는 게 많을수록 실제 일을 할 자리가 줄어든다고요.
CLAUDE.md 가 길면 손해가 두 번입니다. 매번 그 길이만큼 값을 내고, 그만큼 클로드가 일할 자리가 줄어듭니다. 지금 작업과 상관없는 줄에도 똑같이요.
언제 자리를 차지하느냐로 고릅니다
데이지는 하네스 장치를 컨텍스트 윈도우를 언제, 얼마나 차지하느냐로 골랐습니다. 그 기준으로 세우면 순서가 훅, 스킬, 서브에이전트입니다. 강연 정리 슬라이드의 표현으로는 프롬프트 비용 기준의 순서입니다.
| 장치 | 무엇인가 | 컨텍스트 윈도우를 언제 쓰나 |
|---|---|---|
| 훅 | 특정 시점에 지정한 명령을 자동으로 실행하는 장치 | 지금 작업과 관련이 없으면 아무것도 넣지 않는다 |
| 스킬 | 절차를 적어둔 파일 | 짧은 설명만 늘 들어가고, 본문은 정말 필요할 때만 불러온다 |
| 서브에이전트 | 따로 떨어져서 일하는 에이전트 | 별도의 컨텍스트 윈도우에서 일하고, 결과만 요약해서 가져온다 |
셋 다 CLAUDE.md 처럼 매번 전부 들어가는 게 아닙니다. 필요할 때만 자리를 차지합니다. 데이지의 하네스는 결국 컨텍스트 윈도우를 어떻게 쓰는지에 대한 이해에서 출발한 설계입니다.
적어둔 규칙이 안 지켜지는 이유
이 기준으로 보면 CLAUDE.md 에 분명히 적어둔 규칙이 왜 가끔 안 지켜지는지도 보입니다.
저도 처음 클로드 코드를 쓰던 시절에 CLAUDE.md 에 규칙을 정말 많이 적었습니다. 그런데 결과물을 보면 클로드 코드는 그 규칙을 무시하고 코드를 짜놨더라고요.
이유는 두 가지입니다.
첫째, 앞에서 본 것처럼 길수록 덜 지킵니다. 공식 문서가 직접 그렇게 적어놨습니다.
둘째, CLAUDE.md 는 클로드 코드에 강제성을 주는 문서가 아닙니다. 일할 때 참고해 달라고 부탁하는 문서예요. 공식 문서 표현으로는 클로드가 읽고 따르려고 하지만, 엄격하게 지켜진다는 보장은 없습니다. 이 구조는 카파시 하네스 글에서 더 자세히 다뤘습니다.
그래서 데이지는 자기 프로젝트에서 CLAUDE.md 가 아닌 다른 장치들을 더 적극적으로 씁니다.
장치 하나, 실수한 그 자리의 빨간 밑줄
문서 편집기에서 글을 쓰다 맞춤법이 틀리면 바로 빨간 밑줄이 생기죠. 사람은 틀린 글자를 치는 순간 압니다. 그런데 클로드는 코드를 쓰는 동안 그런 신호를 못 받습니다.
데이지는 그 빨간 밑줄을 클로드 코드에게 달아줍니다. 클로드 코드가 규칙을 어긴 바로 그 순간에, 어겼으니 고쳐야 한다고 알려주는 장치를 설계해서 넣는 겁니다. 그 장치 중 하나가 훅입니다. 강연 슬라이드에는 이런 용도가 적혀 있습니다. 클로드가 CLAUDE.md 의 규칙에서 벗어났을 때 알려주기.
여기서 하나 짚을 게 있습니다. 데이지가 말하는 쪽은 막는 것보다 알려주는 쪽에 가깝습니다. 강연에서 데이지는 이렇게 설명합니다. 주니어에게는 특정 파일을 못 고치게 막는 도구를 줄 수 있지만, 시니어가 되면 그 도구를 다시 바꿔줘야 한다. 시니어도 가끔 같은 실수를 하지만, 그게 실수가 아닐 때도 안다. 그러니 툭 건드려 주는 알림이어야 경력이 쌓여도 계속 쓸 수 있다고요.
다만 본인 프로젝트에서 구체적으로 어떤 규칙에 거는지는 밝히지 않았습니다.
되돌리기 어려운 일은 실행 직전에 막습니다
그래서 제가 훅을 쓰는 방식을 하나 더 보태겠습니다.
저는 한 번 일어나면 되돌리기 어려운 일은 훅으로 아예 실행하기 직전에 막습니다. 비밀 키가 노출되는 일, 복구할 수 없는 삭제 같은 것들이요. 클로드 코드가 그런 작업을 하려고 하면 그 자리에서 막아버립니다.
실습용으로 만든 구독 관리 서비스에서 이 차단 훅이 실제로 걸린 적이 있습니다. 클로드 코드가 비밀 키를 파일에 직접 적으려다 막혔는데, 막히자 우회하지 않겠다고 답하더라고요. 부탁이었으면 지나갔을 일을 구조가 붙잡은 겁니다.
따라 하는 법은 간단합니다. 클로드 코드에게 「훅을 이용해서 위험한 작업을 실행 직전에 막는 장치를 설계해 줘」라고 부탁해보세요. 장치를 만드는 일도 클로드 코드에게 시키면 됩니다.
장치 둘, 필요할 때만 열리는 스킬
훅 다음으로 데이지가 자주 쓰는 장치는 스킬입니다. 스킬은 이미 많이들 쓰고 계실 텐데, 하나만 짚겠습니다. 프로젝트 전반에서 항상 쓰이는 규칙 말고 나머지는 다 스킬로 빼시는 게 좋습니다.
데이지는 스킬을 이렇게 설명합니다. 언제 이 스킬을 읽어야 하는지 알려주는 짧은 요약이 붙은 CLAUDE.md.
평소에는 용도를 적은 짧은 요약만 컨텍스트 윈도우에 들어 있다가, 그 절차가 정말 필요할 때만 본문 전체를 불러옵니다. 공식 문서도 CLAUDE.md 의 한 부분이 사실이 아니라 절차로 커졌을 때 스킬로 옮기라고 적어놨습니다. CLAUDE.md 와 달리 스킬 본문은 쓸 때만 들어간다고요.
CLAUDE.md 가 지금 200줄이 넘는다면 클로드 코드에게 이렇게 말해보세요. 항상 필요한 규칙 말고는 전부 스킬로 빼 줘.
장치 셋, 밖에서 일하고 요약만 가져오는 서브에이전트
서브에이전트는 잘 쓰시는 분도 있고 아닌 분도 있을 겁니다. 의도하지 않아도 클로드 코드가 알아서 불러 쓰는 경우가 있어요. 공식 문서에도 클로드 코드에는 내장 서브에이전트가 있고, 적절할 때 클로드가 알아서 쓴다고 적혀 있습니다. 그래도 필요할 때 의도적으로 쓸 수 있으면 더 좋습니다.
서브에이전트는 메인 세션의 컨텍스트 윈도우 밖에서 돌아가는 장치입니다. 데이지도 강연에서 이렇게 정리합니다. 스킬은 컨텍스트 안에서, 서브에이전트는 컨텍스트 밖에서 돌아간다.
공식 문서가 꼽는 쓰임은 이렇습니다. 검색 결과나 로그, 다시 볼 일 없는 파일 내용처럼 과정에서 잔뜩 쌓이는 일. 이런 곁가지 일을 서브에이전트에게 맡기면 자기 컨텍스트에서 처리하고 요약만 돌려줍니다. 메인 대화에는 그 요약만 남으니 쓸데없이 자리를 차지하지 않습니다.
데이지는 한 발 더 갑니다
여기까지는 잘 아시는 분도 꽤 계실 텐데, 데이지는 여기서 한 발 더 나갑니다.
일을 마치면 끝나서 사라지는 서브에이전트와 달리, 작업 공간마다 오래 머무는 에이전트를 세팅해둡니다. 같은 프로젝트를 서로 겹치지 않게 여러 벌 펼쳐둔 작업 공간을 워크트리라고 하는데, 강연 슬라이드에 적힌 데이지의 실제 세팅이 워크트리 16개입니다.
- 워크트리마다 이름과 메모를 적어두고, 에이전트를 하나씩 둔다
- 데이지는 이 에이전트들을 팀원을 기억하듯이 기억한다고 합니다
- 그중 하나는 바로 이 강연 슬라이드를 맡은 에이전트였습니다
심지어 호텔에서 걸어오면서 휴대폰으로 그 에이전트와 이야기를 주고받으며 발표 일부를 썼다고 합니다. 이건 저도 한 수 배운 지점이었습니다.
이 세팅은 데이지가 강연에서 보여준 본인 방식입니다. 처음부터 따라 하실 필요는 없습니다. CLAUDE.md 를 덜어내고 장치를 나눠 쓰는 게 먼저입니다.
오늘 하는 하네스 재설계
처음에 이 글을 다 읽으면 하네스를 다시 짜게 될 거라고 했습니다. CLAUDE.md 와 훅, 스킬, 서브에이전트처럼 클로드 코드에서 쓰는 장치들을 묶어서 하네스라고 부릅니다. CLAUDE.md 에만 규칙을 잔뜩 만들어두셨다면 이렇게 옮기면 됩니다.
| 지금 CLAUDE.md 에 있는 것 | 옮길 곳 |
|---|---|
| 엄밀하게 지켜져야 하는 규칙 | 훅 |
| 특정 시점에 쓰는 절차나 방법 | 스킬 |
| 결과만 받아 보면 되는 작업 | 서브에이전트에게 맡기기 |
| 어디에도 둘 필요가 없는 규칙, 최근 한 달 동안 필요 없었던 규칙 | 삭제 |
| 모든 작업에 정말로 적용되는 몇 줄 | CLAUDE.md 에 남기기 |
지울 규칙을 직접 하나씩 볼 필요는 없습니다. 클로드 코드에서 /doctor 를 실행하면
CLAUDE.md 에서 지울 후보와 스킬로 옮길 후보를 짚어줍니다. 그 목록부터 검토해보세요.
저도 1년 가까이 유료 서비스 하나를 혼자 운영하고 있습니다. 모델이 지금처럼 똑똑하기 전부터 이것저것 시도하고 삽질도 많이 했는데, 이 글을 읽는 분들은 겪지 않아도 될 시행착오를 오늘 내용으로 피해 가셨으면 좋겠습니다.
이 프로젝트의 CLAUDE.md 를 하네스 기준으로 다시 정리하고 싶어. 아직 파일은 고치지 말고 표부터 만들어줘. CLAUDE.md 의 줄마다 아래 다섯 중 하나로 분류해줘. 1. 훅으로 옮길 것: 엄밀하게 지켜져야 하는 규칙. 특히 비밀 키 노출이나 복구할 수 없는 삭제처럼 되돌리기 어려운 일은 실행 직전에 막는 쪽으로. 2. 스킬로 옮길 것: 특정 시점에만 쓰는 절차나 방법. 3. 서브에이전트에게 맡길 것: 검색이나 로그 확인처럼 결과만 받아 보면 되는 작업. 4. 지울 것: 어디에도 둘 필요가 없거나, 코드만 봐도 알 수 있는 내용. 5. 남길 것: 모든 작업에 정말로 적용되는 몇 줄. 표에는 원래 줄, 분류, 이유를 한 줄씩 적어줘. 표를 내가 확인하면, 그다음에 훅과 스킬을 하나씩 만들어줘.