클로드 코드 설계자가 CLAUDE.md를 최소화하는 이유
앤트로픽의 데이지 홀먼은 CLAUDE.md를 길게 쓰기보다 모든 작업에 공통으로 적용되는 규칙만 남기고, 나머지는 훅·스킬·서브에이전트로 나누어 사용한다고 설명한다. 영상은 각각을 언제 활용해야 하는지 살펴보고, 서비스가 커질수록 중요한 것은 규칙을 많이 적는 일이 아니라 필요한 절차를 불러오고 위험한 행동을 막는 작업 환경을 설계하는 능력이라고 강조한다.
1. CLAUDE.md를 줄이는 이유
클로드 코드의 플러그인과 에이전트 팀 등 주요 기능 설계를 이끈 앤트로픽 엔지니어 데이지 홀먼은 이제 CLAUDE.md를 거의 사용하지 않는다고 말한다. 직접 만든 플러그인에서는 CLAUDE.md 기능을 의도적으로 제외하기도 했다.
영상은 흔히 "CLAUDE.md를 잘 활용해야 한다"는 조언을 듣지만, 홀먼의 방식을 살펴보면 오히려 프로젝트의 하네스를 다시 설계하게 될 수 있다고 소개한다. 여기서 하네스란 클로드 코드가 작업할 때 따를 규칙과 절차, 도구 등을 갖춰 놓은 작업 환경을 뜻한다.
홀먼은 한 콘퍼런스에서 메시지를 주고받을 때마다 CLAUDE.md 전체에 대한 토큰 비용이 발생하고, 그중 상당 부분은 현재 작업과 관련 없는 내용이라고 설명했다.
"CLAUDE.md 전체에 대한 토큰 비용을 매번 지불하는데, 그 비용의 90%는 지금 하는 작업과 관계없는 내용에 쓰입니다."
그래서 그는 CLAUDE.md를 모든 작업에 적용되는 몇 줄의 규칙을 담는 용도로만 적합하다고 본다. 영상 진행자 역시 파일이 길어질수록 규칙 준수율이 떨어진다는 공식 문서의 설명을 언급하며, 200토큰 미만으로 유지할 것을 권장한다고 전한다.
2. 기준은 컨텍스트 윈도우를 쓰는 방식
홀먼의 도구 선택을 이해하려면 먼저 컨텍스트 윈도우를 알아야 한다. 이는 클로드 코드가 한 번에 읽고 처리할 수 있는 정보의 공간이다. 영상 설명에 따르면 CLAUDE.md는 대화를 시작할 때 이 공간의 앞부분에 들어가므로, 파일이 길수록 실제 작업에 사용할 공간이 줄어든다.
홀먼은 도구가 컨텍스트를 언제, 얼마나 차지하는지를 기준으로 하네스를 구성했다.
- 훅: 정해진 시점에 명령을 자동 실행한다. 현재 작업과 관련이 없으면 컨텍스트에 내용을 추가하지 않는다.
- 스킬: 평소에는 짧은 설명만 두고, 해당 절차가 필요할 때 전체 내용을 불러온다.
- 서브에이전트: 별도의 컨텍스트에서 작업한 뒤 요약된 결과만 가져온다.
즉, 매번 전체 내용을 포함하는 대신 필요할 때만 정보를 사용하도록 구성한 것이다. 진행자는 홀먼이 컨텍스트 사용 방식에 대한 이해를 바탕으로 이런 기준을 세웠다고 설명한다.
3. 적어 둔 규칙이 지켜지지 않는 이유
진행자도 클로드 코드를 처음 사용할 때 CLAUDE.md에 규칙을 많이 적었지만, 실제 코드 작성 결과를 보면 종종 무시되는 것을 경험했다고 한다.
"규칙을 많이 적어 뒀는데, 결과물을 보면 클로드 코드가 그 규칙을 무시하고 코드를 작성하는 경우가 많았습니다."
영상에 따르면 CLAUDE.md는 규칙을 강제로 집행하는 장치가 아니라 참고하도록 제공하는 문서다. 게다가 문서가 길어지면 규칙을 따르는 비율도 떨어진다. 따라서 홀먼은 중요한 규칙을 문서에 적어 두는 데 그치지 않고, 위반한 순간 클로드 코드에 알려 주고 수정을 유도하는 더 적극적인 장치를 사용한다.
진행자는 이를 문서 편집기에서 맞춤법을 틀렸을 때 생기는 빨간 밑줄에 비유한다. 잘못된 코드나 행동을 나중에 발견하는 것이 아니라, 작업 중 즉시 피드백을 주는 방식이다.
4. 훅으로 위험한 행동을 바로 차단하기
이런 장치의 예가 훅이다. 미리 조건을 정해 두고, 클로드 코드가 그 조건을 위반하는 행동을 하려 하면 곧바로 막도록 만들 수 있다.
다만 진행자는 홀먼이 강연에서 훅을 사용한다고 언급했을 뿐 구체적인 사용 예를 공개하지는 않았다며, 이어서 자신의 사례를 소개한다. 그는 일어난 뒤 되돌리기 어려운 행동을 실행 직전에 차단하는 데 훅을 쓴다.
"비밀 키가 노출되거나 복구할 수 없는 삭제가 일어나려 할 때, 훅으로 즉시 막습니다."
영상에서는 진행자의 강의에서 만든 구독 관리 서비스를 예로 보여 준다. 클로드 코드가 파일에 비밀 키를 직접 쓰려다가 차단되고, 이후 그 차단을 우회하지 않겠다고 응답하는 장면이다. 강의 링크도 고정 댓글에서 확인할 수 있다고 안내한다.
직접 적용해 보고 싶다면 클로드 코드에 위험한 작업을 실행 직전에 훅으로 차단하는 장치를 설계해 달라고 요청해 보라고 조언한다.
5. 필요한 절차는 스킬로 옮기기
홀먼이 자주 쓰는 또 다른 도구는 스킬이다. 진행자는 CLAUDE.md에 프로젝트 전체에 적용되는 규칙만 남기고, 나머지 절차는 스킬로 옮길 것을 권한다.
홀먼은 스킬을 언제 사용해야 하는지 짧은 설명이 붙어 있는 마크다운 파일로 설명한다. 평소에는 용도를 나타내는 간략한 설명만 컨텍스트에 남고, 실제로 그 절차가 필요해지면 전체 내용을 불러온다.
"평소에는 짧은 설명만 남겨 두고, 그 절차가 정말 필요할 때 전체 내용을 불러옵니다."
진행자는 CLAUDE.md가 이미 200줄을 넘었다면, 꼭 필요한 규칙을 제외한 나머지를 스킬로 옮겨 달라고 클로드 코드에 요청해 보라고 제안한다. 앞서 언급한 200토큰 권장치와는 별도로, 파일이 길어진 경우를 가리키는 실천 예시다.
6. 서브에이전트와 오래 머무는 에이전트
서브에이전트는 메인 대화와 별도의 컨텍스트에서 작업한다. 클로드 코드가 알아서 호출하기도 하지만, 진행자는 필요할 때 의도적으로 활용할 수 있으면 더 좋다고 말한다.
특히 검색 결과나 로그가 많이 생기지만 사용자는 최종 결과만 확인하면 되는 작업에 유용하다. 서브에이전트가 별도 공간에서 자료를 처리하고 요약만 돌려주면, 메인 대화에는 그 요약만 남아 불필요하게 컨텍스트를 차지하지 않는다.
"스킬은 컨텍스트 안에서 실행되고, 서브에이전트는 그 밖에서 실행됩니다."
홀먼은 여기서 더 나아가, 작업이 끝나면 사라지는 서브에이전트와 달리 각 작업 공간에 오래 머무는 에이전트도 활용한다. 영상에 따르면 그는 같은 프로젝트를 서로 겹치지 않게 여러 작업 공간으로 나누는 워크트리 16개를 마련하고, 각각에 이름과 메모를 남긴 뒤 개별 에이전트를 두었다.
홀먼은 이 에이전트들을 팀원처럼 생각한다고 한다. 발표 자료를 담당하는 에이전트도 있었는데, 호텔에서 걸어오는 동안 휴대전화로 그 에이전트와 대화하며 발표의 일부를 작성했다고 소개한다. 진행자 역시 이 사례에서 배운 점이 있었다고 말한다.
7. 규칙을 나누고 불필요한 내용은 덜어내기
진행자는 지금까지의 내용을 바탕으로, 규칙을 모두 마크다운 파일에 몰아넣었다면 다음처럼 하네스를 다시 구성해 보라고 정리한다.
- 반드시 지켜야 하는 규칙은 위반을 차단하거나 피드백할 수 있도록 훅으로 옮긴다.
- 특정 상황에서 사용하는 절차와 방법은 스킬로 옮긴다.
- 과정보다 최종 결과가 중요한 작업은 서브에이전트에 맡긴다.
- 어디에도 둘 필요가 없고 지난 한 달 동안 필요하지 않았던 규칙은 삭제를 검토한다.
"규칙은 훅으로, 특정 시점에 쓰는 절차는 스킬로, 결과만 받으면 되는 일은 서브에이전트에 맡겨 보세요."
영상에서는 규칙 파일을 하나씩 직접 살펴보지 않아도 클로드 코드에서 /doctor를 실행하면 삭제 후보를 제안받을 수 있다고 안내하며, 제안된 목록은 직접 검토하라고 덧붙인다.
진행자는 자신이 유료 서비스 EdgeLink를 거의 1년 동안 혼자 운영하며 수익화했다고 소개한다. 클로드 코드의 초기 사용자로서 모델이 지금만큼 똑똑해지기 전부터 여러 시도와 시행착오를 겪었고, 시청자들은 이번 내용을 통해 불필요한 시행착오를 줄였으면 한다고 말한다.
8. 서비스 운영과 시스템 설계의 중요성
서비스가 커질수록 관리해야 할 규칙도 늘어난다. 진행자는 영상에서 다룬 내용이 실제 운영에 필요한 지식과 노하우 중 기본적이고 작은 부분이라며, 이미 서비스가 성장해 관리하기 어려운 '위험 구간'에 들어선 사람도 있을 수 있다고 말한다.
그는 특히 클로드 코드로 서비스를 만들 때 흔히 겪는 상황을 짚는다. 처음에는 10분 만에 화면이 나와 놀랍지만, 기능을 추가하면 기존 기능이 망가지고, 하나를 고치면 다른 곳이 깨지는데 원인도 알기 어려워진다는 것이다.
"처음 화면이 10분 만에 나올 때는 놀랍지만, 새 기능을 추가하면 기존 것이 망가지고 하나를 고치면 또 다른 곳이 망가집니다."
특히 비개발자는 유튜브에서 단편적인 팁을 따라 하다가 토큰만 소모할 수 있다고 설명한다. 반면 규칙을 어기는 순간 자동으로 막는 시스템을 설계할 수 있다면 같은 문제를 반복하지 않고 앞으로 나아갈 수 있다고 강조한다.
진행자는 가드레일을 만들려면 반드시 코딩을 배워야 하거나 개발자여야 하는지 고민하는 사람들에게, 클로드 코드를 활용해 시스템을 잘 설계하는 능력이 중요해지고 있다는 자신의 견해를 전한다. 샘 올트먼이 코딩 능력이 더 이상 중요하지 않다는 확신을 갖게 되었다고 언급한 발언도 함께 소개한다.
9. 강의 소개와 마무리
영상 후반부에서 진행자는 자신의 '모두의 클로드 코드' 강의를 소개한다. 이미 60명 이상이 수강 중이며, 서비스를 처음부터 끝까지 만들면서 개발자 수준의 판단 기준과 안전장치를 체계적으로 익히도록 구성했다고 설명한다.
강의에는 진행자가 주제를 더 깊이 연구해 만든 템플릿과 8년 이상의 개발 경험을 담은 클로드 코드 플러그인도 제공된다고 한다. 설치부터 영상에서 다룬 CLAUDE.md 하네스 설계, 배포, 배포 후 운영과 수익화까지 하나의 흐름으로 다룬다는 소개다.
진행자는 강의를 듣지 않더라도 목차를 살펴보고 모르는 주제나 키워드가 있으면 찾아 공부해 보라고 권한다. 결국 중요한 것은 여러 가지를 직접 시도하고, 경험을 쌓으며, 더 나아지려는 마음으로 공부하는 것이라고 마무리한다.
"강의를 듣지 않더라도 목차를 보면서 모르는 주제와 키워드가 있다면 직접 찾아보고 공부해 보세요."
강의는 영상 설명에 안내된 '모두의 클로드 코드' 링크에서 확인할 수 있다.