컨텍스트 엔지니어링 실패모드 위키

불변 규칙·쓰기보호 — CLAUDE.md/AGENTS.md 계층·Hook·Constitutional AI

9 min read

상위: 07_00_MOC

불변 규칙과 쓰기보호 — 기준 재정의를 원천 차단하는 계층

기준 재정의(07_01-문제정의-룰침범과-기준재정의)를 막으려면 어떤 규칙은 재정의 불가능해야 한다. 관건은 텍스트로 쓰인 규칙을 어떻게 진짜로 불변하게 만드느냐다. Claude Code의 CLAUDE.md 계층은 이 불변성을 가장 잘 문서화한 실제 구현이면서, 동시에 소프트 규칙의 한계도 솔직하게 드러낸다.

1. 로드 우선순위 계층 — 권위의 서열

CLAUDE.md는 위치에 따라 권위가 다르다. 넓은 스코프(조직)가 먼저 로드되고, 좁은 스코프(개인)가 나중에 온다.

Managed Policy CLAUDE.md   ← 배제 불가·불변 (조직)
  • Linux/WSL: /etc/claude-code/CLAUDE.md
  • macOS:     /Library/Application Support/ClaudeCode/CLAUDE.md
  • Windows:   C:\Program Files\ClaudeCode\CLAUDE.md
~/.claude/CLAUDE.md          ← User Instructions (개인 전역)
~/.claude/rules/*.md         ← User-level Rules
./CLAUDE.md | ./.claude/CLAUDE.md   ← Project Instructions (팀 공유)
./CLAUDE.local.md            ← Local (.gitignore, 개인)
.claude/rules/*.md           ← Path-scoped Rules (매칭 파일 열 때만)

핵심 설계 원칙은 이것이다. Managed Policy CLAUDE.md는 어떤 개인 설정으로도 배제할 수 없다.

“Managed policy CLAUDE.md files cannot be excluded. This ensures organization-wide instructions always apply regardless of individual settings.” — Anthropic(2025)

claudeMdExcludes로 다른 팀의 CLAUDE.md는 제외할 수 있어도 Managed Policy만은 예외 없이 항상 적용된다. MDM이나 Ansible, Group Policy로 배포되는 이 파일이 이 챕터에서 말하는 canonical rule(정전 규칙) 의 표준 사례이며, 4계층 모델의 계층 1, 곧 불변 헌법층에 해당한다(07_08-처방-컨텍스트는-슬롯계약-4계층-모델).

텍스트 파일을 배포하는 대신 managed-settings.json의 claudeMd 키에 규칙 본문을 직접 넣는 방법도 있다. 이 역시 user나 project 설정으로 무효화되지 않는 관리 정책 권위를 갖는다.

2. 소프트 규칙의 한계 — “컨텍스트이지 집행 설정이 아니다”

그러나 CLAUDE.md의 내용은 강제 집행되지 않는다. 공식 문서의 가장 중요한 경고:

“Claude treats them as context, not enforced configuration. To block an action regardless of what Claude decides, use a PreToolUse hook instead.” — Anthropic(2025)

CLAUDE.md 텍스트는 컨텍스트로 주입될 뿐이고, 그것도 시스템 프롬프트가 아니라 사용자 메시지로 전달된다.

“CLAUDE.md content is delivered as a user message after the system prompt, not as part of the system prompt itself … there’s no guarantee of strict compliance, especially for vague or conflicting instructions.” — Anthropic(2025)

모순되는 두 규칙이 있으면 임의로 하나를 고른다(“If two rules contradict each other, Claude may pick one arbitrarily”). 그래서 결론은 분명하다. 소프트 규칙만으로는 기준 재정의를 원천 차단할 수 없다.

3. 진짜 불변성 — 집행 계층(Hook / Managed Settings)

재정의가 불가능해야 하는 규칙이라면 모델의 결정과 무관하게 작동하는 집행 계층으로 내려야 한다. Claude Code는 이를 두 갈래로 제공한다.

  • PreToolUse Hook: Claude의 결정과 상관없이 셸 커맨드를 실행해 위반 행동을 하드 차단한다. “커밋 전 항상 X”, “main 직접 push 금지” 같은 규칙은 텍스트가 아니라 Hook으로 두어야 한다.
  • Managed Settings(permissions.deny, sandbox.enabled): 도구와 경로, 명령을 클라이언트가 강제로 막는다.

공식 문서가 둘의 역할을 명확히 가른다.

“Settings rules are enforced by the client regardless of what Claude decides to do. CLAUDE.md instructions shape Claude’s behavior but are not a hard enforcement layer.” — Anthropic(2025)

관심사설정 위치
특정 도구·명령·경로 차단Managed settings permissions.deny
행동 가이드(코드 스타일·컴플라이언스)Managed CLAUDE.md
특정 시점 필수 실행(커밋 전 등)PreToolUse Hook
시스템 프롬프트 수준 고정--append-system-prompt

여기에 더해 InstructionsLoaded hook으로 어떤 규칙 파일이 언제 로드됐는지 기록하면 규칙의 재정의나 소실을 감사할 수 있다. 거버넌스 관점에서 중요한 가시성 도구다.

graph TD
    A["Managed Policy CLAUDE.md<br/>/etc/claude-code/ · 배제 불가·불변"] --> B["User CLAUDE.md"]
    B --> C["Project CLAUDE.md · 팀 공유"]
    C --> D["Local CLAUDE.local.md · 개인"]
    D --> E[".claude/rules/*.md<br/>경로 스코프(매칭시 로드)"]
    H["PreToolUse Hook<br/>하드 집행 · 결정 무관"] -.->|"위반 행동 차단"| A
    S["Managed Settings<br/>permissions.deny / sandbox"] -.->|"도구·경로 차단"| A
    I["--append-system-prompt"] -.->|"시스템프롬프트 고정"| A
    style A fill:#FF4444,color:#fff
    style H fill:#FF8800,color:#fff
    style S fill:#FF8800,color:#fff
    style I fill:#FF8800,color:#fff

4. AGENTS.md — 도구 중립 규칙 파일 표준

규칙 파일 계층은 Claude Code만의 것이 아니다. AGENTS.md 는 여러 코딩 에이전트가 공유하는 지속 규칙 파일의 사실상 표준으로 자리 잡았다. Claude Code는 AGENTS.md를 직접 읽지는 않지만, @AGENTS.md import나 심볼릭 링크로 단일 진실 원천(single source of truth)을 공유하라고 공식 권장한다.

“Claude Code reads CLAUDE.md, not AGENTS.md. If your repository already uses AGENTS.md … create a CLAUDE.md that imports it so both tools read the same instructions without duplicating them.” — Anthropic(2025)

여기서 얻는 거버넌스 교훈은 규칙을 도구마다 복제하지 말라는 것이다. 복제는 기준 재정의의 온상이 된다. 한 사본만 고치고 다른 사본을 잊으면 두 에이전트가 서로 다른 “canonical” 규칙을 따르게 된다. import나 symlink로 사본을 하나로 묶어야 한다.

5. 이론적 토대 — Constitutional AI

불변 규칙을 “왜 명시적으로 만들어야 하는가”의 이론적 토대는 Constitutional AI(Bai et al., Anthropic, 2022)에 있다. CAI는 윤리 제약을 헌법(constitution) 으로 명시 코드화하고, 자기비판·개정 루프와 RLAIF로 모델을 정렬한다.

“An LLM is now choosing the best response based on principles sampled from a constitution.” — Bai et al.(2022)

에이전트 거버넌스에 적용하면, 시스템 프롬프트 레벨의 불변 규칙이 CAI의 “헌법” 역할을 한다. 요점은 거버넌스 규범을 명시적으로 만들어 검사하고 이의를 제기하고 수정할 수 있게 한다는 데 있다.

저자 견해 — CAI의 진짜 교훈은 규칙을 명시적이고 검사 가능한 형태로 외부화하라는 것이다. 다만 이를 CLAUDE.md나 AGENTS.md 텍스트로만 구현하면 2절에서 본 대로 덮어쓸 수 있다. 명시적 헌법(CAI 원리)과 하드 집행(Hook, Managed Settings)을 결합해야 비로소 완전한 불변성에 도달한다. 텍스트는 왜 를 설명하고, Hook은 반드시 를 보장한다. (실무 적용은 06 해결전략과 08 실전에서 다룬다.)

참고문헌

그래프 뷰

백링크