CLAUDE.md에 규칙 추가하는 걸 멈추고 인프라를 구축하면 어떻게 되는가
What happens when you stop adding rules to CLAUDE.md and start building infrastructure instead
TL;DR Highlight
CLAUDE.md 규칙 파일 기반 방식이 100줄을 넘으면서 규칙 준수율이 떨어지자, hooks·skill·campaign 파일 등 환경 기반 인프라로 전환하여 준수율 저하를 개선했다.
Who Should Read
Claude Code(구 claude.ai Projects)나 Claude 에이전트를 활용해 코딩 워크플로우를 자동화하려는 개발자. 특히 CLAUDE.md가 점점 길어지는데 Claude가 지시를 자꾸 무시한다고 느끼는 분들에게 직접적으로 유용하다.
Core Mechanics
- CLAUDE.md는 100줄을 넘어가면 규칙 준수율이 급격히 떨어진다. 작성자가 직접 190줄짜리 파일을 감사해보니 40%가 중복이었고, 서로 모순되거나 이미 유효하지 않은 규칙도 섞여 있었다. 123줄로 줄이자 즉시 준수율이 개선됐다.
- 진짜 해결책은 파일 트리밍이 아니라 '강제성의 위치'를 바꾸는 것이다. 'typecheck를 항상 실행해라'는 규칙 대신, 파일 저장 시 자동으로 typecheck를 실행하는 lifecycle hook으로 교체하면 Claude가 선택할 여지 자체가 없어진다.
- 반복적으로 설명하던 도메인 지식은 skill 파일(마크다운)로 분리한다. 에이전트가 현재 태스크에 맞는 skill 파일만 로드하기 때문에 불필요한 context 토큰이 0이 된다. 코드 리뷰 프로세스처럼 매 세션마다 재설명하던 것들이 여기에 해당한다.
- 세션이 끊기면 컨텍스트가 사라지는 문제는 campaign 파일로 해결한다. 무엇을 만들었는지, 어떤 결정을 내렸는지, 무엇이 남았는지를 구조화된 문서로 추적해서 다음 날 세션을 재개할 때 처음부터 설명할 필요가 없다.
- 인프라 수준을 5단계로 정의한다: 1) Raw prompting → 2) CLAUDE.md → 3) Skills(모듈식 전문성) → 4) Hooks(환경 기반 품질 강제) → 5) Orchestration(병렬 에이전트, 캠페인). 대부분의 프로젝트는 Level 2~3으로 충분하다.
- 작성자는 이 시스템을 668K 줄 코드베이스에서 198개 에이전트를 돌리며 27번의 실패를 통해 다듬었고, Citadel이라는 이름으로 오픈소스화했다. /do 명령어 하나로 태스크를 적절한 orchestration 레벨로 자동 라우팅해준다.
Evidence
- 작성자는 CLAUDE.md를 190줄 → 123줄로 줄인 직후 Claude의 규칙 준수율이 즉각 향상됐다고 보고했다. 40% 중복 제거와 모순 규칙 정리가 핵심이었다.
- '파일 저장 시 typecheck 자동 실행' hook을 도입한 뒤 리뷰 시간이 크게 줄었다고 한다. PR 리뷰 시점에는 타입 에러와 broken import가 이미 제거된 상태라, 의도와 설계만 검토하면 됐다.
- 668K 줄 규모의 실제 코드베이스에서 198개 에이전트를 운영하며 27번의 문서화된 실패를 거쳐 시스템을 구축했다고 명시되어 있다. 각 규칙은 실제로 무언가가 깨진 경험에서 도출됐다.
- session context 압축(compaction) 직전에 자동으로 상태를 저장하는 hook, 동일 이슈에서 3번 연속 실패 시 에이전트를 종료하는 circuit breaker 등 구체적인 hook 예시들이 실제 운영 중임을 시사한다.
How to Apply
- 지금 당장 CLAUDE.md를 열어서 감사해보자. 비슷한 말을 반복하는 규칙, 서로 모순되는 규칙, 더 이상 유효하지 않은 규칙을 찾아 제거한다. 100줄 이하를 목표로 프로젝트 컨벤션·기술 스택·가장 중요한 5가지만 남긴다.
- 자주 어기는 규칙이 있다면 그걸 규칙으로 유지하지 말고 환경으로 이전한다. 예를 들어 'lint 실행해라'는 규칙은 pre-save hook 스크립트로 교체하고, 코드 리뷰 프로세스는 별도 skill 마크다운 파일로 분리한다.
- Citadel 레포(https://github.com/SethGammon/Citadel)를 클론해서 skill 시스템, hooks, campaign 파일 구조를 참고한다. 전체 시스템을 도입하지 않더라도 campaign 파일 패턴만 가져와도 세션 간 컨텍스트 유실 문제를 즉시 줄일 수 있다.
Terminology
관련 논문
OpenKnowledge – Obsidian/Notion의 오픈소스 AI-first 대안
Git 기반 동기화와 Claude/Codex/Cursor 연동을 내장한 로컬 우선 마크다운 에디터로, AI 에이전트의 두 번째 뇌(LLM Wiki)로 활용할 수 있는 오픈소스 도구다.
Unfireable Safety Kernel: AI 에이전트를 위한 Execution-Time AI Alignment
AI 에이전트가 자신의 안전장치를 우회할 수 없도록, 에이전트 프로세스 바깥에 수학적으로 증명된 강제 통제 게이트를 배치하는 아키텍처
RubyLLM: 주요 AI 프로바이더를 모두 지원하는 Ruby 프레임워크
OpenAI, Claude, Gemini 등 주요 AI 프로바이더를 단일 인터페이스로 통합한 Ruby 프레임워크로, Rails 통합과 에이전트 기능까지 지원해 Ruby 개발자가 AI 기능을 빠르게 붙일 수 있다.
Qwen-AgentWorld: 범용 에이전트를 위한 Language World Model
Alibaba Qwen 팀이 AI 에이전트가 행동 결과를 미리 시뮬레이션할 수 있는 'Language World Model'을 공개했다. 에이전트 훈련과 실행 경로 검증에 새로운 패러다임을 제시하는 연구다.
SHERLOC: Code Repair Agent를 위한 구조화된 Diagnostic Localization 프레임워크
버그 위치만 알려주는 게 아니라 '왜, 어떻게 고쳐야 하는지'까지 진단 리포트를 생성해서 코드 수정 에이전트의 성능을 높이는 training-free 프레임워크
peerd – 브라우저에서 완전히 실행되는 AI Agent Harness
백엔드 서버 없이 Chrome/Firefox 확장 프로그램으로만 동작하는 AI 에이전트 실행 환경으로, 브라우저 탭을 직접 조작하고 WASM Linux VM까지 구동할 수 있어 프라이버시와 보안을 동시에 챙길 수 있다.