CLAUDE.md에 규칙 추가하는 걸 멈추고 인프라를 구축하면 어떻게 되는가

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

관련 논문

• 프로덕션 AI 에이전트를 GPT-5.6으로 마이그레이션: 2.2배 빠르고 27% 저렴

  마케팅 웹사이트를 자동 생성하는 프로덕션 AI 에이전트를 Claude Opus 4.8에서 GPT-5.6 Sol로 전환한 실전 경험담으로, 단순 모델 교체가 아니라 eval 하네스, 툴 스키마, 캐싱, 추론 리플레이까지 손봐야 했던 과정을 구체적인 수치와 함께 정리했다.

• xAI Grok Build CLI가 xAI 서버로 전송하는 데이터: 네트워크 레벨 분석

  xAI의 공식 코딩 CLI 도구 Grok Build가 사용자 동의 없이 전체 Git 저장소와 .env 시크릿 파일을 xAI 서버로 업로드한다는 사실이 네트워크 트래픽 분석으로 밝혀졌다.

• 중요할 때 기억하라: Long-Horizon 에이전트를 위한 Proactive Memory Agent

  LLM 에이전트가 긴 작업 중 중요한 정보를 잊어버리는 문제를 별도의 메모리 에이전트가 '적절한 타이밍에' 끼어들어 해결하는 방법

• WebSwarm: 깊고 넓은 웹 검색을 위한 재귀적 Multi-Agent Orchestration

  복잡한 웹 검색을 재귀적으로 분해하고 각 노드에 적합한 검색 모드를 동적으로 할당하는 멀티에이전트 프레임워크

• 웹 앱을 리버스 엔지니어링해서 AI Agent 도구로 자동 변환하기

  로그인된 웹 앱의 API 호출을 브라우저에서 감시해 자동으로 MCP 도구로 변환하는 에이전트를 만들었다. 소스 코드나 공식 API 문서 없이도 Jira, Spotify 같은 서비스에 AI 어시스턴트를 붙일 수 있다.

• FableCut – AI 에이전트가 조작할 수 있는 브라우저 기반 비디오 에디터 (zero deps)

  타임라인 전체를 JSON 파일 하나로 표현하고 MCP/REST로 AI 에이전트가 직접 편집할 수 있는 브라우저 비디오 에디터로, Claude 같은 AI가 프롬프트 하나로 영상을 자동 컷편집하고 결과를 실시간으로 UI에 반영해준다.

Related Resources

• https://www.reddit.com/r/ClaudeAI/comments/1rz2oo3/what_happens_when_you_stop_adding_rules_to/
• https://github.com/SethGammon/Citadel