CLAUDE.md에 지시 사항을 작성했다. 처음에는 제대로 작동했다.

하지만 항목이 20개를 넘어가면서부터, 지켜지는 지시와 무시되는 지시가 생겨나기 시작했다.

다른 프로젝트를 열었더니, 관계없는 절차서가 읽혀서 방해가 되었다.

고치고 싶지만, 어느 줄이 원인인지 알 수 없다.

원인은 "쓰는 방식"이 아니라 "두는 위치"다.

이 글을 다 읽고 나면, 지시 사항이 안정적으로 전달되는 위치를 설계할 수 있게 된다.

필자가 실제로 운용하고 있는 3계층 구성을 파일 내용과 함께 공개한다.

(제1계층·제2계층는 실제 운용 파일에서 고유명사만 제외한 것이며, 제3계층는 보안상의 이유로 구조를 유지한 가공의 예시로 대체하였다.)

1. 한 장짜리 CLAUDE.md는 이렇게 망가진다

CLAUDE.md를 사용하기 시작한 사람 대부분은 프로젝트 직하에 단 한 장만 둔다.

그러다 보면 비대해진다. 망가지는 방식에는 3가지 패턴이 있다.

패턴 A: 무관한 지시가 항상 컨텍스트(Context)에 포함됨

"이 리포지토리의 테스트는 pytest로 실행한다"라는 지시는 해당 리포지토리 이외에서는 완전히 무의미하다.

그런데 그것이 매 세션마다 읽힌다.

1줄이라면 오차 범위다. 50줄이 되면, 정말로 지켜줬으면 하는 지시 옆에 무관한 50줄이 나란히 늘어선다.

모델 입장에서는 전부 동일한 가중치를 가진 입력이다.

패턴 B: 프로젝트의 절차가 다른 프로젝트를 오염시킴

"작업 전에 반드시 대장 파일을 읽는다"라는 절차를, 위치를 잘못 지정하여 글로벌(Global)에 작성해 버린다.

그러면 대장 같은 것이 존재하지 않는 다른 프로젝트에서, AI가 대장을 찾기 시작한다.

찾고, 찾지 못해서, 멋대로 만들려고 한다.

이는 지시가 "너무 잘 들어서" 발생하는 실패다. 지시가 안 들어서 발생하는 실패보다 까다롭다.

패턴 C: 어디를 고쳐야 할지 알 수 없게 됨

가장 흔한 경우다.

"경어를 쓰지 말아달라", "도표는 SVG로 그려달라", "이 프로젝트에서는 브랜치를 생성한 뒤 커밋하라"

——성질이 완전히 다른 지시들이 한 장에 공존하고 있으면, 동작이 이상할 때 원인을 분리할 수 없다.

지시를 삭제하며 테스트하는 과정을 반복하게 된다.

세 가지 모두, 원인은 분류의 결여다. 쓰는 방식의 문제가 아니다.

2. 해결 방법 — 3계층으로 나누기

필자는 지시 파일을 3계층으로 나누어 운용하고 있다.

나누는 원칙은 한 문장으로 말할 수 있다.

글로벌에는 "자신의 취향·수용 방식", 프로젝트에는 "업무 절차".

"경어를 쓰지 마"는 어떤 프로젝트에서도 변하지 않는 자신의 취향이다. → 글로벌.

"씨앗을 보관할 때는 대장을 업데이트한다"는 해당 프로젝트의 절차다. → 프로젝트.

판단이 망설여진다면, 이 질문 하나만 스스로에게 던지면 된다.

그 지시는 모든 프로젝트에서 필요한가?

Yes → 글로벌 / No → 프로젝트 측

그리고 또 하나의 철칙이 있다.

같은 지시를 두 곳에 쓰지 마라.

이중 관리는 모순의 온상이다. 한쪽만 수정하고 다른 한쪽은 그대로 남게 된다.

어느 쪽이 적용되고 있는지 모르는 채로 동작이 흔들린다.

중복을 발견하면 반드시 둘 중 하나를 지워야 한다.

이하, 실제 파일을 공개한다.

~/.claude/CLAUDE.md

(실물)

3. 제1계층: 글로벌 필자의 글로벌에는 4개 항목만 들어있다. "취향"만 두기로 결정했기 때문에 이 이상 늘어나지 않는다.

3-1. 답변 스타일

## 답변 스타일 (최우선)
토큰(Token) 소비를 최소한으로 하기 위해 다음 규칙을 절대 준수한다.
- 경어, 인사, 사과, 서론(입니다/합니다, 감사합니다 등)은 일절 사용하지 않는다.
...

목적은 토큰 절약이다. 덤으로 읽는 시간도 줄어든다.

이런 종류의 압축 지시는 쓰는 방식에 몇 가지 요령이 있지만, 그것은 별개의 이야기(다른 글의 영역)이므로 여기서는 다루지 않는다.

이 글에서 말하고 싶은 것은 "이것은 글로벌에 두어야 할 지시다"라는 점이다.

문체의 취향은 프로젝트에 따라 변하지 않는다. 그러므로 글로벌. 판단은 순식간에 끝난다.

3-2. 파일 경로 제시 방법

이것은 환경에 특화된 실무 규칙이지만, 역시 모든 프로젝트에 공통되므로 글로벌(Global)에 둔다.

## 파일 경로 제시 방법
에디터 확장 기능은 비ASCII(일본어 등)를 포함하는 경로의 markdown 링크를 해결할 수 없다
(클릭해서 이동할 수 없다).
...

포인트는 "왜 그렇게 하는가"를 한 줄 넣어두는 것이다.

이유가 없으면, AI는 조건이 조금 다른 상황에서 응용할 수 없다.

반대로 이유만 적어두면, 예를 들어 "일본어를 포함하는 폴더명을 출력하는 상황"에서도 동일한 판단을 내린다.

3-3. 그림 그리기 규약

도구 선택의 고정이다. 내버려 두면 매번 mermaid가 나오기 때문에, 명시적으로 금지하고 있다.

## 처리 플로우도·데이터 플로우도를 그릴 때
mermaid / Graphviz 등의 자동 레이아웃은 사용하지 않는다.
자작 스킬을 발동하여, 좌표를 직접 지정한 SVG를 직접 작성한다.
...

"트리거(Trigger)"를 열거하고 있는 것이 핵심이다.

"어떤 발화가 있을 때 이 규약을 적용할 것인가"를 적어두면, 발동률이 올라간다.

규약만 적어두고 언제 사용하는지를 적지 않은 CLAUDE.md는 자주 보이지만, 이는 아까운 일이다.

3-4. 판단 요청 포맷

글로벌에서 가장 효과가 큰 것이 이것이다.

AI에게 판단을 구할 때의 출력 형식을 정형화하여 고정하고 있다.

## 판단 요청의 출력 형식
판단·재정·확인을 요구하는 부분은 다음 형식으로만 출력한다.
설계·구현·조사 보고 등, 그 외의 출력 형식에는 일절 영향을 주지 않는다.
...

출력 예시도 함께 적어두면 정밀도가 올라간다. 가상의 소재로 하나 작성했다.

■ 재고 수의 자릿수 초과
결정 사항: 정수부 8자리 이상이 들어왔을 때 어떻게 할 것인가
권장 사항은 "전체 이상으로 간주하고 정지". 예상치를 기준으로 반올림하는 것보다 안전함
...

왜 이것이 "취향"인가.

이것은 내가 판단하기 쉬운 정보의 배열 순서이기 때문이다. 업무 절차가 아니다.

어떤 프로젝트에서도 필자는 "결정할 것을 먼저, 사실은 요약하지 말고" 내놓기를 원한다.

그래서 글로벌에 둔다.

글로벌은 이 4가지로 끝이다. 늘리지 않는 것 자체가 규칙이라고 생각해주길 바란다.

<프로젝트군 상위 폴더>\CLAUDE.md

(실물)

4. 제2층: 허브(Hub) 여기가 3계층 구성의 핵심이다. 자주 보이지 않는 계층이므로 자세히 쓰겠다.

필자는 프로젝트를 하나의 상위 폴더 아래에 나열하고 있다.

그리고 그 상위 폴더 자체에도 CLAUDE.md를 두고 있다. 역할은 "입구"다.

# 프로젝트 허브
이 폴더는 신규 프로젝트의 입구(허브). **여기서 본 작업을 수행하지 않는다**.
역할은 서브 프로젝트의 전개와 `INDEX.md`의 유지뿐이다.
...

이 파일이 해결하고 있는 문제는 두 가지가 있다.

(1) 프로젝트 목록이 부패하지 않는다

INDEX.md는 status / last-touched / next의 3개 열을 가진 표다.

이것을 수동으로 계속 업데이트하는 것은 불가능하다. 3일이면 멈춘다.

허브에 "진척 보고를 받으면 표를 업데이트한다"라고 적어두면,

"그거 끝났어"라고 한 줄 말하는 것만으로 표가 유지된다.

(2) 쓰기 권한이 하나로 고정된다

INDEX.md를 업데이트할 수 있는 것은 허브 측 세션뿐이라고 명시하고 있다.

서브 프로젝트 측의 CLAUDE.md에도 "INDEX.md 쓰기 금지"라고 적혀 있다.

동일한 파일을 여러 세션에서 동시에 건드리지 않게 하기 위한 약속이다.

이것을 적어두지 않으면, 서브 측 AI가 친절을 베풀려다가 목록을 업데이트하려고 시도하여 표가 망가진다.

그리고 가장 중요한 것이 **"여기서 본 작업을 수행하지 않는다"**라는 한 줄이다.

허브에서 대화를 시작하면 그대로 허브에서 작업이 진행되어 버린다.

"다시 열어줘"라고 유도함으로써, 작업은 반드시 올바른 컨텍스트(Context) 안에서 시작된다.

<프로젝트>\CLAUDE.md

(가상 예시)

5. 제3층: 프로젝트 실제 프로젝트의 내용은 보여줄 수 없으므로, 구조만 동일하게 만든 가상의 예시를 만들었다.

"독서 메모 관리" 프로젝트의 CLAUDE.md다.

# dokusho — 독서 메모 관리
읽은 책의 메모를 축적하고, 테마를 넘나들며 찾아볼 수 있는 상태를 유지한다.
이 파일이 워크플로우(Workflow)의 정의이다. 세션 시작 시 반드시 따른다.
...

구조를 봐달라. 프로젝트 측의 CLAUDE.md는 대략 이 5개 블록이면 충분하다.

폴더 구성 (Folder Structure) — 어디에 무엇이 있는가 -
대장 / 단일 진실 공급원 (Single Source of Truth) — 상태를 어디에서 유지하는가 -
상태 전이 (Status Transition) — 취할 수 있는 상태와 전이 -
트리거 단어 → 동작 (Trigger Word → Action) — "이 발화가 오면 이 절차를 수행"
금지 사항 (Prohibitions) — 하고 싶지 않은 것

4번이 가장 효과적이다.

"~해 주세요"가 아니라 "이 발화가 오면 이 절차를 실행"이라는 형태로 작성하면,

매번 동일한 입구에서 동일한 절차로 진입하게 된다.

반대로, 트리거가 적혀 있지 않은 절차는, 사용자가 매번 절차를 떠올려 지시해야 한다. 그렇게 되면 의미가 없다.

마지막 줄에 주목해 주길 바란다. 허브(Hub) 측의 금지 사항과 짝을 이룬다.

한쪽 면의 금지만으로는 빠져나갈 구멍이 생긴다. 양쪽 모두에 적어야 비로소 기능한다.

(이것은 "같은 지시를 두 곳에 적지 않는다"의 예외다. 중복이 아니라, 경계 양쪽에서의 약속이므로 의도적으로 이중으로 작성하는 것이다.)

6. 어디에 적을 것인가 — 판정 절차

새로운 지시를 추가하고 싶을 때, 필자는 위에서부터 순서대로 딱 3가지 질문만 던진다.

Q1. 그 지시는 모든 프로젝트에서 필요한가?
Yes → 글로벌 (~/.claude/CLAUDE.md)
No → Q2로
...

Q3를 건너뛰면, 조만간 이중 관리 상태가 된다. 여기가 가장 게으름을 피우고 싶어지는 지점이다.

실무적으로는, 지시를 추가하기 전에 글로벌과 프로젝트 양쪽을 모두 열어 훑어보는 것만으로도 방지할 수 있다.

30초면 끝난다.

또 하나, 경험적인 구분 기준을 공유한다.

"~라는 문체로", "~의 형식으로 출력해", "~는 사용하지 마 (도구 선택)" → 취향. 글로벌.
"~를 먼저 읽어", "~를 업데이트해", "~의 순서로 진행해" → 절차. 프로젝트.

동사가 "출력의 형태"를 향하고 있다면 글로벌, "작업의 순서"를 향하고 있다면 프로젝트다.

대체로 이 기준으로 나뉜다.

7. CLAUDE.md 종류 카탈로그 (보충)

위치는 크게 3가지가 있다. 계층 설계와 거의 대응한다.

(a) 사용자 글로벌 (User Global) ~/.claude/CLAUDE.md

해당 머신의 모든 세션에 적용된다. 자신 전용이며, 공유되지 않는다.

그렇기에 "자신의 취향"을 두기에 적절한 장소다.

(b) 프로젝트 루트의 CLAUDE.md

해당 프로젝트를 열었을 때 적용된다.

리포지토리(Repository)에 체크인하면 팀과 공유할 수 있다.

"이 리포지토리의 방식"을 팀에 배포하는 수단이 된다.

역으로 말하면, 자신만의 취향(문체 등)을 여기에 적으면 팀원 모두에게 강요하게 된다.

분리해 두는 실질적인 이득은 여기에도 있다.

(c) 서브 디렉토리의 CLAUDE.md

모노레포(Monorepo)에서 패키지마다 방식이 다를 때 사용한다.

상위 디렉토리부터 순차적으로 읽히는 형태가 된다.

참고로, 여러 설정 파일의 우선순위나 내부적인 읽기 순서의 세부 사항은

버전에 따라 달라질 수 있는 부분이다.

이 글에서는 단정 짓지 않겠다.

세부 사항이 필요하다면 공식 문서를 확인해 주길 바란다.

본 기사의 주장은 사양(Specification)에 의존하는 것이 아니라, "성질이 다른 지시를 섞지 마라"라는 설계에 관한 이야기다.

8. 운용하며 알게 된 주의점

주의 1: 글로벌은 "늘리지 않는 것"이 가장 중요하다

글로벌은 모든 세션에 적용된다. 적용된다는 것은 방해가 될 수도 있다는 뜻이다.

필자의 글로벌은 4개 항목에서 멈춰 있다.

5번째 항목을 추가하고 싶다면, 먼저 "정말로 모든 프로젝트에서 필요한가"를 의심할 것.

대부분은 프로젝트 측의 지시다.

주의 2: 금지 사항은 구체적인 행동으로 적는다

"대충 하지 마"는 작동하지 않는다.

"대장을 경유하지 않는 파일 생성을 하지 마"는 작동한다.

금지는, 위반 여부를 파일 조작(File Operation) 레벨에서 판정할 수 있는 입도(Granularity)까지 낮추어야 한다.

주의 3: 계층을 가로지르는 모순은 알아채기 어려운 형태로 나타난다

"결론부터 짧게" (글로벌)와 "절차를 순서대로 설명한 뒤 실행" (프로젝트)가 공존하면,

동작이 날마다 흔들린다. 에러는 나지 않는다. 다만 흔들릴 뿐이다.

동작이 불안정하다고 느껴진다면, 우선 양쪽 계층을 나란히 놓고 읽어라.

작성 방식을 고민하기 전에 이것부터 해야 한다. 경험상 원인의 대부분은 여기에 있다.

요약

지시가 통하지 않을 때, 대부분의 사람은 작성 방식을 고치려 한다.

하지만 실제 원인은 성질이 다른 지시가 한 장에 공존하고 있다는 점이다.

취향과 절차를 나눈다. 전체 프로젝트용과 이 프로젝트용을 나눈다. 그것만으로 동작이 안정된다.

내일 바로 실행할 첫걸음은 하나뿐이다.

지금의 CLAUDE.md를 열고, 각 줄의 맨 앞에 "취(취향)" 또는 "절(절차)"라는 한 글자를 적어 넣는 것이다.

「好(취)」＝ 자신의 취향·수용 방식. 「절(절)」＝ 해당 프로젝트의 업무 절차.

두 종류가 섞여 있는 것이 눈에 보인다면, 그곳이 분리의 경계선이다.

「취(好)」를 글로벌(Global)로 옮기는 것부터 시작하면 된다.

이동하는 것만으로 충분하며, 다시 쓸 필요는 없다.

Discussion