CLAUDE.md에 썼는데도 지켜지지 않는 이유 — 그 정체는 '전달하는 장소'의 설계였다

이 기사의 개요 (2026년 6월): Claude Code에 '메커니즘 (仕組み)'을 전달하기 위한 부품론을 정리한 Zenn Book Vol.4 「코드를 쓰지 못하는 내가 Claude Code에 『메커니즘』을 전달하기까지」를 소개한다. 「CLAUDE.md에 썼는데도 지켜지지 않는다」, 「서브 에이전트 (Sub-agent)에게 지시를 전달했는데도 움직이지 않는다」라는 답답함의 정체를, Claude Code가 스스로 움직일 수 있게 되기 위한 7가지 레이어 (CLAUDE.md / 서브 에이전트 / 스킬 (Skill) / Playbook / 메모리 (Memory) / 설정·권한 / MCP)로서 한 장씩 해부한 책이다. 이 책을 관통하는 질문은 「무엇을 전달할 것인가」와 동시에 「무엇을 전달하지 않을 것인가」 —— 너무 많이 전달하지 않는 것이다. 가격 900엔, 서장은 무료 공개. Vol.1~3에 이어지는 시리즈 제4권이지만, 단독으로 완결되도록 쓰여 있다.

CLAUDE.md에 「썼는데도, 지켜지지 않는다」 —— 그 답답함의 정체

이것은 코드를 쓸 수 있느냐 없느냐의 문제가 아니다. Claude Code에 「무엇을, 어디에, 어떻게 전달할 것인가」라는 설계의 문제다. 그렇기에 평소 코드를 쓰지 않는 사람에게도, 쓰는 사람에게도 똑같이 해당된다.

Claude Code를 깊게 사용하다 보면, 일종의 막다른 길에 부딪히게 된다.

CLAUDE.md에 규칙을 적었다. 「일본어로 응답할 것」, 「커밋 전에 브랜치를 확인할 것」 —— 적어두면 세션 시작 시 반드시 읽히기 때문에, 그대로 움직여 줄 것이라 믿는다. 그런데 지켜지지 않는 경우가 있다. 서브 에이전트에게 역할을 부여하고 지시를 내렸는데도 생각처럼 움직이지 않는다. 스킬 (Skill)이나 Playbook을 만들기 시작했지만, 어디까지 적어야 할지 판단의 기준이 없다.

「썼는데도, 효과가 있는 것 같지 않다」. 이런 느낌을 받은 적이 있지 않은가.

나 자신도 처음에는 이렇게 생각했다. CLAUDE.md는 처음에 읽히는 파일이니까, 적으면 적을수록 안전해질 것이라고. 이것은 절반은 맞고, 절반은 틀렸다.

틀린 절반의 정체는 —— 「전달하는 장소」의 설계에 있다.

규칙이 지켜지지 않는 것은 규칙의 내용이 나쁘기 때문만은 아니다. 「어디에, 어떤 형태로 전달할 것인가」가 어긋나 있으면, 적은 내용은 읽히지 않거나, 읽히더라도 효과가 없다. CLAUDE.md는 「규칙을 적으면 효과가 나타나는 장소」가 아니라, 「규칙이 읽히는 메커니즘을 설계하는 장소」였다. 그리고 이것은 CLAUDE.md만의 이야기가 아니다. 서브 에이전트에게도, 스킬에도, Playbook에도 각각 고유한 「전달 방식의 설계」가 있다.

Zenn Book Vol.4 「코드를 쓰지 못하는 내가 Claude Code에 『메커니즘』을 전달하기까지」는 이 「전달하는 장소」를 7가지 레이어로 나누어 하나씩 해부한 책이다.

Claude Code에 전달할 수 있는 장소는 7가지로 나뉘어 있다 —— 이 책의 지도

「더 잘 심어 넣을 수 있을 텐데」라는 느낌이 들더라도, 무턱대고 무언가를 써 내려가면 되는 것이 아니다. Claude Code에 「전달할 수 있는 장소」는 구조적으로 몇 가지 레이어로 나뉘어 있다. 이 책은 그 레이어를 장의 축으로 삼고 있다.

먼저 밝혀두자면, 7가지를 모두 한꺼번에 파악할 필요는 없다. 각 장의 비중이 균등하지 않으며, 당신의 현재 관심사에 맞춰 1~2개의 레이어부터 시작할 수 있도록 쓰여 있다. 지도는 다음과 같다.

레이어	장	무엇을 전달하는가	너무 많이 전달하면 어떤 일이 일어나는가
CLAUDE.md	제1장	행동 규범과 트리거 조건	너무 많이 적으면 AI가 읽지 않게 됨
...
이 7가지는 성질에 따라 두 종류로 나뉜다.

처음 6개 (CLAUDE.md ~ 설정·권한)는 스스로 설계하여 만들어가는 것이다. 위에서부터 순서대로 쌓아 올리는 이미지로 나열되어 있다. CLAUDE.md로 토대 규칙을 전달하고, 서브 에이전트로 역할을 나누고, 스킬로 절차를 내재화하며, Playbook으로 판단의 지도를 그리고, 메모리로 실패의 기억을 축적하고, 설정·권한으로 경계선을 긋는다.

일곱 번째인 MCP (Model Context Protocol: 외부 도구에 Claude Code를 연결하는 메커니즘)만은 성질이 다르다. 이것은 스스로 적어서 설계하는 것이 아니라, 이미 존재하는 것 중에서 골라 연결하는 것이다. 1~6이 「어떻게 설계할 것인가」를 묻는다면, MCP는 「어떻게 선택할 것인가」를 묻는다. 그래서 이 책에서는 별도의 항목으로 다루고 있다.

오른쪽 끝의 「너무 많이 전달하면 어떤 일이 일어나는가」 열에 주목해 주길 바란다. 이 책이 단순한 기능 카탈로그와 다른 점은 바로 이 열이 있다는 것이다.

이 책을 관통하는 질문 —— 「너무 많이 전달하지 않기」라는 뺄셈

이 책에는 7개의 장 전체를 관통하는 하나의 질문이 있다.

「무엇을 전달할 것인가」와 동시에 「무엇을 전달하지 않을 것인가」—— 너무 많이 전달하지 않는 것이다.

구조를 전달하는 책이면서도, 이 책은 줄곧 뺄셈에 대해 이야기하고 있다. 각 레이어(Layer)에서 저자는 동일한 질문을 반복한다. 무엇을 전달하고, 무엇을 전달하지 않을 것인가. 어디까지 전달할 것인가. 그리고 너무 많이 전달했을 때 어떤 일이 벌어지는가. 에필로그에서는 이 질문이 다음과 같이 하나의 문장으로 묶인다—— "깎아내는 설계야말로, 전달하기 위한 설계였다"라고.

왜 뺄셈이 필요한가. 이 책에서 다루는 7개 레이어의 설계는 추상론에서 도출된 것이 아니다. 90개의 플레이북(Playbook)과 21건의 사고 기록에서 추출한, 실운용의 산물이다 (이 책 집필 시점의 실측치). 숫자가 보여주듯, 투박한 경험의 축적으로부터 나온 결과물이다.

그중 이 책에서 실제로 해부하고 있는 사례 두 가지만 들어보겠다.

하나는 설정·권한을 너무 많이 전달해서 발생한 사고다. 2026년 4월, Zenn으로의 자동 동기화를 제어하는 플래그(Flag)를 사전 확인 없이 기본값(Default)으로 활성화해 버렸다. 결과적으로 Zenn 게시물 5개가 일시적으로 비공개 상태가 되었다. "일단 허용해 두면 편리하겠지"라는 발상이 그대로 사고의 입구가 된 사례이다.

또 다른 하나는 스킬(Skill)을 "전달했는데도 사용되지 않은" 사례다. 2026년 5월, 그때까지 만든 스킬들을 점검하여 3개를 퇴역시키기로 결정했다. 현재 환경에서는 작동하지 않는 것, 제작 의도를 정리할 수 없게 된 것—— "나중에 쓸지도 몰라"라는 생각으로 늘려놓은 도구들은 대개 사용되지 않은 채 쌓여만 간다.

더한다고 해서 더 좋아지는 것은 아니다. CLAUDE.md는 길어질수록 AI가 읽지 않게 된다. 플레이북(Playbook)은 오래되어도 아무도 알아차리지 못한다. 메모리(Memory)는 비대해져 컨텍스트(Context)를 압박한다. 모든 레이어에는 너무 많이 전달했을 때 효율을 떨어뜨리는 고유한 메커니즘이 있다. 이 책은 그것을 장마다 명시하는 동시에, "어떻게 깎아낼 것인가"를 세트로 보여준다. 이것이 이 책을 다른 활용법 서적들과 차별화하는 지점이다.

4부작이 완성되었다 —— 시리즈 전체의 지도와 이 책의 위치

2026년 6월, 이로써 시리즈가 4권이 되었다.

Vol.1 「코드를 쓸 줄 모르는 내가 Claude Code로 『AI 팀』을 만들기까지」: 에이전트 팀을 설계하기까지의 기록. 역할 정의 파일 작성법, 분업 설계, 첫 팀을 런칭하기까지의 시행착오 -
Vol.2 「코드를 쓸 줄 모르는 내가 Claude Code로 『AI 팀』을 운영하기까지」: "만든 다음 날 아침"부터 시작되는 기록. 플레이북(Playbook) 설계, 3층 품질 게이트(Quality Gate), 실제로 발생한 사고의 상세 내용 -
Vol.3 「코드를 쓸 줄 모르는 내가 Claude Code로 『AI 팀』과 계속 써 내려가기까지」: 팀이 돌아가기 시작한 이후의 기록. "준비한다·쓴다·전달한다·회수한다"의 4단계 루프 -
Vol.4 「코드를 쓸 줄 모르는 내가 Claude Code에 『구조』를 전달하기까지」: 팀을 지탱하고 있는 "부품" 그 자체의 해부서

앞선 세 권과의 관계를 한마디로 말하자면, Vol.13이 이야기와 장치 설계의 기록이었던 것에 반해, Vol.4는 부품 그 자체의 해부서이다. Vol.13을 통해 "AI 팀을 만들고, 운영하고, 계속 써 내려가는" 이야기가 진행되었다. 그 이야기를 배후에서 지탱하던 부품들——CLAUDE.md, 서브 에이전트(Sub-agent), 스킬(Skill), 플레이북(Playbook), 메모리(Memory), 설정·권한, MCP——을 하나씩 꺼내어 단면을 보여주는 것이 Vol.4에 해당한다.

Vol.4부터 읽기 시작해도 가능한가?

가능하다. 이 책은 단독으로 완결되도록 쓰였으며, 이전 권에 대한 참조도 각 장에서 최소한으로 제한되어 있다. Vol.1~3을 읽지 않았더라도 7개 레이어의 해부는 그대로 읽어 내려갈 수 있다. "애초에 AI 팀을 어떻게 만드는가"부터 알고 싶다면 Vol.1부터 읽는 것이 토대를 다지는 데 도움이 되겠지만, "Claude Code의 구조를 어떻게 설계할 것인가"만을 알고 싶다면 Vol.4 단독으로도 목적을 달성할 수 있다.

참고로, 이 책은 "부품이 무엇인가"에서 완결된다. 그 부품을 사용하여 실제로 어떻게 일상의 업무를 진행할 것인가——일상의 업무를 Claude에게 맡겨 나가는 경험——는 이어질 Vol.5로 넘어간다. 다만 이 책을 다 읽은 후 Vol.5를 기다릴 필요는 없다. 오히려 기다리지 말고 자신의 손으로 직접 조합을 시도해 보길 바라는 것이 이 책의 스탠스다.

Zenn Book Vol.4는 어떤 사람에게 적합한가

이 책이 적합한 사람

• Claude Code를 깊게 사용하고 있지만 "더 잘 활용할 수 있을 것 같다"고 느끼는 분
• CLAUDE.md를 작성했지만 "효과가 있는지 모르겠다"는 분
• 스킬(Skill)·플레이북(Playbook)을 만들기 시작했지만, 설계의 판단 기준이 없는 분
• AI 팀의 운영을 지탱하는 "부품"의 설계 사상을 체계적으로 파악하고 싶은 분

적합하지 않은 사람

• Claude Code의 구현 테크닉이나 코드 작성법을 원하는 분 (본서는 논프로그래머(Non-programmer) 관점에서 작성되었으며, 코드 작성법 그 자체는 다루지 않습니다)
• 설정 파일 샘플 모음이나 복사해서 바로 쓸 수 있는 템플릿 모음을 기대하는 분 (본서는 CLAUDE.md의 전문을 전재하는 대신, "왜 그런 형태가 되었는가"라는 설계 판단에 초점을 맞추고 있습니다)

두 번째 사항에 대해 보충하자면, 본서는 의도적으로 설정 파일의 전문을 붙여넣지 않습니다. 그렇게 하면 "설정 파일 샘플 모음"처럼 보여 독자가 자신의 프로젝트에 가져갈 수 있는 부분이 줄어들기 때문입니다. 대신 구조—왜 3개 층으로 나누는지, 왜 트리거(Trigger)를 표 형식으로 만드는지, 왜 역할별로 분리하는지—라는 설계 판단에 더 많은 지면을 할애하고 있습니다.

가격과 무료 공개 범위——서장을 읽고 나서 판단해 주세요

가격: 900엔 (서장 "무엇을 전달하는 책인가"는 무료 공개)

서장에는 본서의 핵심인 "장비의 부여와 업무의 대행은 별개"라는 출발점, 7레이어(7-layer)의 전체 지도, 그리고 "너무 많이 전달하지 않는다"라는 본서를 관통하는 질문에 대한 예고가 담겨 있습니다. 구매 전에 서장을 읽고 자신에게 필요한 책인지 확인해 보시기 바랍니다.

Vol.4 서장(무료)·구매는 이쪽으로

코드를 쓸 줄 모르는 내가 Claude Code에 "메커니즘(Mechanism)"을 전달하기까지

※ 본서의 내용을 실천하려면 Anthropic의 유료 플랜(월 $20~) 계약이 필요합니다.

Vol.1·Vol.2·Vol.3은 이쪽으로

• Vol.1 "만들 때까지": https://zenn.dev/tottoko_hamu/books/leading-ai-agents-without-code (900엔, 서장+제1부는 무료 공개)
• Vol.2 "운영할 때까지": https://zenn.dev/tottoko_hamu/books/operating-ai-team-without-code (900엔, 서장은 무료 공개)
• Vol.3 "계속 쓸 때까지": https://zenn.dev/tottoko_hamu/books/writing-with-ai-team-without-code (900엔, 서장은 무료 공개)

Zenn 팔로우: 신간 및 업데이트 알림을 받고 싶으신 분은 Zenn에서 저(@tottoko_hamu)를 팔로우해 주세요.

블로그 구독: 이 블로그(blog.saitoko.net)를 구독하시면 신간 및 새 글 소식을 알려드립니다.

CLAUDE.md를 딱 한 줄만 고치기——메커니즘을 전달하는 첫걸음

본서를 다 읽은 후, 가장 먼저 해보셨으면 하는 일이 있습니다.

자신의 CLAUDE.md를 열어 딱 한 줄만 고쳐보는 것입니다. 한 줄을 추가해도 좋고, 한 줄을 삭제해도 좋습니다. "썼는데도 지켜지지 않는다"라는 답답함의 해답은 규칙을 대량으로 추가하는 것이 아니라, "무엇을 어디에 어떻게 전달할 것인가"를 하나씩 다시 설계하는 데 있습니다. 그 첫걸음이 바로 한 줄을 고치는 것입니다.

그 한 걸음이 메커니즘을 전달하는 작업의 시작이 됩니다.

저자: saitoko / 블로그 「코드를 쓰지 않는 SE 일지」(blog.saitoko.net) / Zenn: @tottoko_hamu

이 기사는 Hatena Blog로부터의 크로스 포스트입니다.

Discussion