CLAUDE.md에 규칙을 계속 추가하는 것을 멈추세요. 3계층 에이전트 하네스(3-Layer Agent Harness)를 사용하세요: 짧은 헌법(CLAUDE.md), 전문 기술(specialist skills), 그리고 하위 에이전트(subagents)로 구성됩니다. 이는 150개 지침 준수 예산(compliance budget)을 존중하며 에이전트의 신뢰성을 유지합니다.

핵심 요약 (Key Takeaways)

• CLAUDE.md에 규칙을 계속 추가하는 것을 멈추세요.
• 3계층 에이전트 하네스(3-Layer Agent Harness)를 사용하세요: 짧은 헌법(CLAUDE.md), 전문 기술(specialist skills), 그리고 하위 에이전트(subagents).
• 이는 150개 지침 준수 예산(compliance budget)을 존중하며 에이전트의 신뢰성을 유지합니다.

무엇이 변했는가 — 에이전트를 망가뜨리는 150개 지침 예산

2026년 초에 발표된 HumanLayer의 내부 연구는 파워 유저들이 느껴왔던 점을 수치화했습니다: LLM의 지침 준수(instruction compliance) 능력은 약 150개의 개별적인 행동 지침(behavioral directives) 부근에서 현저히 저하됩니다. 이 임계값 아래에서는 모델이 지침을 안정적으로 따릅니다. 이 임계값을 넘어서면 준수율이 떨어지는데, 이는 균일하게 떨어지는 것이 아니라 선택적으로 발생합니다. 모델은 최근의 지침, 학습된 사전 지식(training priors)과 충돌하는 지침, 그리고 긴 문서 깊숙이 묻혀 있는 지침들을 누락합니다.

300줄에 달하는 당신의 CLAUDE.md는 60%의 확률로만 준수됩니다. 처음 100줄은 작동합니다. 나머지 200줄은 선택적인 제안일 뿐입니다. 시스템 프롬프트(system prompt)가 이미 그 예산의 약 50개를 소비하고 있습니다. 당신은 남은 100개의 슬롯을 두고 경쟁하고 있는 것입니다.

당신에게 의미하는 바 — 3계층 에이전트 하네스 (3-Layer Agent Harness)

12개의 프로덕션 프로젝트를 관리하는 한 개발자는 그가 '3계층 에이전트 하네스(3-Layer Agent Harness)'라고 부르는 아키텍처로 수렴했습니다. 이는 각 계층이 독립적으로 이해 가능하고, 감사 가능하며, 개선 가능하도록 관심사(concerns)를 분리합니다. 이는 Anthropic의 자체 문서와 일치하지만, 이름을 부여하고 왜 분리가 중요한지를 설명합니다.

제1계층: CLAUDE.md (헌법)

CLAUDE.md는 헌법(constitutional document)과 같아야 합니다. 즉, 원칙, 타협 불가능한 사항, 구조적 관례를 담아야 합니다. 절차, 작업 설명, 워크플로우 자동화가 아닙니다. 잘 작성된 헌법은 기억할 수 있을 만큼 충분히 짧아야 합니다.

다음 네 가지 질문에 답하십시오:

1. 이 프로젝트는 무엇인가? (제품 + 스택 + 아키텍처)
2. 절대 금지 사항은 무엇인가? (절대로 일어나서는 안 되는 일들)
3. 신뢰 경계 조건(trust-boundary conditions)은 무엇인가? (보안 제약 사항)
4. 확장된 규칙들은 어디에 있는가? (기술 파일(skill files)에 대한 참조)

구조적 골격:

# 프로젝트 이름

## 이것은 무엇인가
...

이 골격은 80~120행 정도입니다. 한 개발자는 670행에 달하던 CLAUDE.md를 108행으로 줄였으며, 그 결과 까다로운 규칙에 대한 에이전트의 신뢰성(reliability)이 측정 가능한 수준으로 향상되었습니다. 400행에 묻혀 있던 규칙들이 이제는 40행에 위치하게 되었습니다.

제2계층: 기술 (Skills, 전문가들)

기술(Skills)은 SKILL.md 프론트매터(frontmatter)를 포함하는 가이드 문서로, 사용자 패턴이나 슬래시 명령(slash commands)에 의해 트리거될 때 자동으로 발견되고 로드됩니다. 이들은 CLAUDE.md의 영구적인 컨텍스트(context)의 일부가 아닙니다. 필요할 때만 로드됩니다.

다음과 같은 경우에 기술을 사용하십시오:

• 배포 시 제약 사항 (운영 사고로부터 얻은 22가지 엄격한 규칙)
• 인증/결제 경로를 위한 보안 체크리스트
• 신규 콘텐츠를 위한 SEO 표준
• 언어별 관례 (TypeScript 패턴, React 패턴)

실패 사례: CLAUDE.md를 학습된 교훈의 실행 로그(running log)로 사용하는 경우입니다. 모든 사고가 발생할 때마다 새로운 규칙이 추가됩니다. 대신 규칙을 적절한 계층으로 라우팅하십시오.

제3계층: 하위 에이전트 (Subagents, 작업자들)

하위 에이전트(Subagents)는 복잡한 다단계 작업을 수행하는 격리된 작업자입니다. 이들은 자신만의 컨텍스트, 자신만의 지침, 그리고 자신만의 출력을 가집니다. 다음과 같은 경우에 사용하십시오:

• 여러 파일에 걸친 리팩터링 (Refactoring)
• 명세서(specification)로부터 기능 구현
• 일괄 테스트 실행 및 실패 수정

지금 바로 시도해 보세요 — 귀하의 CLAUDE.md를 감사(Audit)하십시오

1. CLAUDE.md의 줄 수를 세어보세요. 150줄이 넘는다면 위험 구역에 진입한 것입니다.
2. 모든 규칙을 분류하세요: 헌법적 규칙 (CLAUDE.md에 유지), 전문가 규칙 (기술 파일로 이동), 또는 워크플로 규칙 (하위 에이전트 정의로 이동).
3. .claude/rules/ 디렉토리를 생성하고 전문가 규칙을 그곳으로 이동시키세요.
4. CLAUDE.md에서 @filename 구문을 사용하여 해당 규칙들을 참조하세요.
5. 테스트: 가장 빈번한 작업을 실행해 보세요. 에이전트가 핵심 규칙을 더 일관되게 따르나요?

예시: .claude/rules/deploy-invariants.md 생성:

# 배포 불변 조건 (Deploy Invariants)
- 금요일 오후 3시 이후에는 절대 배포하지 말 것
- 배포 전에는 항상 `npm run typecheck`를 실행할 것
...

그 다음 CLAUDE.md에서 참조합니다: - .claude/rules/deploy-invariants.md — 배포 파이프라인 제약 사항

에이전트는 배포와 관련된 작업을 감지하면 이 파일을 자동으로 로드합니다.

출처: dev.to

(devto_claudecode를 통해 07월 04일 업데이트되었음)

바이럴을 일으키고 있는 GitHub 리포지토리들 — 별 55K를 기록한 mattpocock의 skills 리포, 107K를 기록한 forrestchang의 Andrej Karpathy 컬렉션, 그리고 20K를 넘어서며 트렌딩 중인 shanraisshan의 베스트 프랙티스(best-practices) 편람 — 은 중요한 경고를 강조합니다: 타인의 CLAUDE.md를 복사하는 것은 그들의 .bashrc를 복사하는 것과 같습니다. 1,800개 이상의 제품이 있는 마켓플레이스와 Cloudflare Worker 플릿(fleet)을 포함하여 12개의 프로덕션 프로젝트를 관리하는 3계층 에이전트 하네스(3-Layer Agent Harness)의 개발자는, 타인의 경험이 담긴 300줄의 코드를 붙여넣는 것이 에이전트의 신뢰성을 미묘하게 떨어뜨린다고 언급했습니다 [dev.to 참조]. 해당 프로젝트 포트폴리오에는 커스텀 WordPress 파이프라인과 밤새 실행되는 cron 기반 SEO 리서치 에이전트가 포함되어 있습니다.

원문은 gentic.news에 게시되었습니다.