CLAUDE.md에 규칙을 많이 적어도 Claude Code가 절반은 무시하는 현상

CLAUDE.md 파일에 규칙을 잔뜩 써도, Claude Code는 여전히 그중 절반 정도를 못 본 척합니다. 이 일은 많은 사람이 경험한 바 있습니다.

HumanLayer 팀이 오픈소스로 공개한 skills 저장소에는 improve-claude-md라는 것이 있는데, 여기서 제공하는 설명이 매우 흥미롭습니다.

Claude Code가 CLAUDE.md를 주입할 때마다 시스템 알림을 하나 붙여서, 이 내용들이 현재 작업과 관련 없을 수 있으니 관련 없으면 무시하라고 합니다.

결국 규칙이 많고 복잡해질수록, 모델은 가장 중요한 몇 가지 규칙까지도 함께 무시하기 쉬워집니다.

이에 대한 그들의 방법은, 특정 상황에서만 사용되는 규칙들을 'important if'라는 태그 안에 넣는 것입니다. 이 태그에는 트리거 조건을 명확히 작성하고, 일반적인 프로젝트 배경 정보는 여전히 가장 위에 노출합니다.

GitHub: https://t.co/saI1WDtEjB

저장소에는 총 6개의 Skill이 있습니다. show-me는 Claude가 긴 설명 대신 의사 코드(pseudo code), 호출 트리(call tree), 컴포넌트 트리(component tree), Mermaid 다이어그램 같은 가장 간결한 형태로 현재 주제를 시각화하도록 합니다.

visual-pr은 동일한 방식으로 PR에 설명을 작성합니다. 변경 사항을 구조도와 diff로 보여주어 코드 검토자가 보기 편리하게 만듭니다.

design-control-loop는 제어 이론(control theory)의 아이디어를 빌려왔습니다. 먼저 우리가 코드베이스의 어떤 지표를 어떤 목표치까지 끌어올리고 싶은지 인터뷰하고, 그 다음 주기적으로 실행되는 Agent 루프를 구성하여 매번 한 작은 단계만 수정하고 PR을 생성합니다.