가이드

작성자 Matt Connor 2026-08-12 · 업데이트됨 2026-08-13

코딩 에이전트가 지시사항을 무시하는 이유와 해결법

Q: Claude Code가 CLAUDE.md를 무시하는 이유는 무엇입니까?

무시되었다고 단정하기 전에 파일이 로드되었는지 확인하십시오. /context을 실행하여 Memory files 목록을 확인하십시오. 해당 목록에 없는 파일은 대화에 포함되지 않은 것입니다. 지침 파일은 시스템 프롬프트 이후 사용자 메시지로 전달되며, 강제된 설정이 아닌 컨텍스트로 취급되므로 엄격한 준수가 보장되지 않습니다. 대부분의 실제 사례는 다음 네 가지 중 하나입니다. 에이전트가 읽지 않은 하위 디렉터리에 파일이 있거나, 두 파일의 내용이 충돌하여 모델이 임의로 하나를 선택했거나, 규칙이 너무 모호하여 동작을 검증할 수 없거나, 주변 코드가 규칙과 반대되는 내용을 보여주는 경우입니다.

Q: /compact 명령을 사용해도 지침이 유지됩니까?

로드 방식에 따라 다릅니다. 프로젝트 루트의 CLAUDE.md, 범위가 지정되지 않은 규칙, 자동 메모리는 압축 후 디스크에서 다시 주입됩니다. paths: 프런트매터가 포함된 규칙과 하위 디렉터리의 CLAUDE.md 파일은 일치하는 파일이 다시 읽히기 전까지는 유실됩니다. 채팅에 직접 입력한 내용은 요약 과정에서 유지된 경우에만 살아남습니다. 규칙이 세션 전체에 걸쳐 유지되어야 한다면, paths: 프런트매터 없이 프로젝트 루트 파일에 작성하십시오.

코딩 에이전트가 지침 파일을 무시하고 작업을 강행하는 원인을 분석합니다. 컨텍스트 윈도우의 우선순위 문제와 하니스 동작 방식을 이해하여 에이전트가 규칙을 정확히 따르도록 만드는 진단 방법과 실질적인 해결 전략을 제시합니다.

코딩 에이전트가 지시사항을 무시하는 이유

코딩 에이전트가 지시사항을 무시하는 데에는 네 가지 이유가 있으며, 그중 어느 것도 사용자가 너무 정중했기 때문은 아닙니다. 첫째, 규칙이 컨텍스트 윈도우에 포함되지 않았을 수 있습니다. 둘째, 규칙이 너무 모호하여 동작을 검증할 수 없었을 수 있습니다. 셋째, 컨텍스트 내의 다른 요소, 보통 에이전트가 방금 읽은 코드가 해당 규칙과 충돌했을 수 있습니다. 마지막으로, 규칙이 로드되어 있더라도 현재 대화 순서에서 너무 멀리 떨어져 있어 에이전트가 가까운 내용 위주로 작업하고 있을 수 있습니다.

각 원인마다 해결 방법이 다르므로, 가장 먼저 해야 할 일은 원인을 구분하는 것입니다. 대문자를 사용하거나 IMPORTANT라는 단어를 붙이는 것은 진단 방법이 아닙니다. 아래의 메커니즘은 2026년 8월 기준으로 로딩 및 압축 동작이 상세히 문서화된 Claude Code를 예시로 사용합니다. 다른 도구들은 세부 사항은 다르지만, 전체적인 작동 방식은 동일합니다.

먼저 두 가지 용어를 정의합니다. 컨텍스트 윈도우(context window)는 특정 시점에 모델이 확인하는 텍스트 블록으로, 시스템 프롬프트, 사용자의 지시 파일, 대화 내용, 그리고 에이전트가 읽은 모든 파일을 포함합니다. 하니스(harness)는 모델을 둘러싼 프로그램으로, 디스크에서 파일을 읽어 해당 블록을 구성하는 역할을 합니다. 이 글에서 제기하는 거의 모든 불만 사항은 사실 모델이 아니라 하니스에 대한 것입니다.

지침 파일은 설정이 아닌 메시지입니다

지침 파일은 설정이 아닙니다. 런타임 환경에서 CLAUDE.md를 읽고 이를 강제하는 기능은 없습니다. 하네스(harness)가 디스크에서 파일을 읽어 대화창에 텍스트를 붙여넣는 방식입니다. Claude Code에서 해당 내용은 시스템 프롬프트 뒤에 배치된 사용자 메시지로 전달되므로, 모델은 귀하의 규칙을 귀하가 입력한 다른 모든 텍스트와 동일하게 인식합니다.

이로 인해 불편한 결과가 발생합니다. 귀하의 규칙은 대화창 내의 다른 모든 텍스트와 동등한 위치에서 경쟁하게 됩니다. 규칙은 하나의 주장일 뿐입니다. 에이전트가 방금 연 파일은 증거가 됩니다. 둘의 내용이 충돌하면 종종 증거가 우선하며, 모델의 관점에서는 아무런 문제가 발생한 것이 아니기에 오류도 출력되지 않습니다.

공식 문서에도 명시되어 있듯이, 지침 파일은 강제되는 설정이 아니라 문맥으로 처리됩니다. 모델의 판단과 관계없이 특정 동작을 차단하려면 문장이 아닌 훅(hook)이 필요합니다. 이 점을 명심하십시오. 이 게시물 끝에 제시된 대부분의 해결책은 이 원칙을 특정 사례에 적용한 것입니다.

어떤 지침 파일이 언제 로드되는가

Claude Code는 실행을 시작한 디렉터리에서부터 상위 디렉터리 트리로 거슬러 올라갑니다. 파일 시스템 루트부터 작업 디렉터리까지의 모든 CLAUDE.md 및 CLAUDE.local.md 파일은 실행 시점에 전체가 로드됩니다. 이 파일들은 순서대로 연결되므로, 실행 위치와 가장 가까운 파일이 마지막에 읽히며, 동일 디렉터리 내에서는 .local 파일이 메인 파일 뒤에 추가됩니다.

작업 디렉터리 하위에 있는 파일들은 다르게 동작합니다. 이 파일들은 실행 시점에 로드되지 않습니다. 에이전트가 해당 디렉터리의 파일을 읽을 때 로드됩니다. .claude/rules/ 내의 경로 범위 규칙에 paths: 프런트매터 필드가 포함된 경우도 마찬가지입니다. 이 규칙들은 매 턴마다 적용되는 것이 아니라, 일치하는 파일이 읽힐 때 컨텍스트에 진입합니다.

이러한 차이점 하나가 보고된 실패 사례의 상당 부분을 설명합니다. 사용자가 packages/api/CLAUDE.md에 규칙을 넣고 API에 대해 질문하면, 에이전트는 packages/api/ 하위의 파일을 열지 않은 채 답변합니다. 규칙이 무시된 것이 아니라, 애초에 존재하지 않았던 것입니다. 저장소가 모노레포 내 패키지별 지침 파일로 지침을 분리하고 있다면, 매번 가장 먼저 확인해야 할 사항입니다.

로드와 관련된 또 다른 함정이 있으며, 이는 "에이전트가 내 지침을 무시했다"는 보고 중 가장 흔한 유형입니다. Claude Code는 AGENTS.md이 아닌 CLAUDE.md를 읽습니다. AGENTS.md를 표준으로 사용하고 CLAUDE.md가 없는 저장소의 경우, Claude Code는 로드할 파일을 전혀 찾지 못합니다. 지원되는 브리지 방식은 첫 줄이 @AGENTS.md인 CLAUDE.md 파일을 사용하는 것이며, 이는 실행 시점에 파일을 가져오고 그 아래에 Claude 관련 참고 사항을 추가할 수 있게 합니다. 추가할 내용이 없다면 심볼릭 링크를 사용해도 됩니다. 애초에 어떤 내용을 해당 파일에 포함할지 결정하는 것은 별개의 문제이며, 에이전트 지침과 인간용 문서 분리하기에서 다룹니다.

파일을 다시 작성하기 전에 로드되었는지 확인하십시오

에이전트가 파일을 인식하고 있다는 증거를 확보하기 전까지는 내용을 수정하지 마십시오. 두 가지 확인 방법이 있으며, 비용이 적게 드는 방법을 먼저 수행합니다.

세션 내에서 /context을 실행하십시오. 이 명령은 현재 창을 범주별로 분류하여 출력하며, Memory files 목록에는 실제로 로드된 모든 명령 파일의 이름이 표시됩니다. 이 목록에 없는 파일은 대화에 포함되지 않은 것이므로, 그 안에 작성하는 내용은 아무런 의미가 없습니다. /memory는 파일 위치를 나열하고 편집을 위해 파일을 엽니다. 여기에는 아직 존재하지 않는 파일도 포함됩니다.

더 확실한 확인을 위해 로드 과정을 기록하십시오. InstructionsLoaded 훅 이벤트는 CLAUDE.md 또는 규칙 파일이 컨텍스트에 들어올 때마다 발생하며, 해당 매처는 로드가 발생한 이유를 알려줍니다: session_start, nested_traversal, path_glob_match, include 또는 compact. 이를 .claude/settings.json에 추가하십시오:

{
  "hooks": {
    "InstructionsLoaded": [
      {
        "matcher": "nested_traversal",
        "hooks": [
          {
            "type": "command",
            "command": "cat >> /tmp/instructions-loaded.log"
          }
        ]
      }
    ]
  }
}

훅은 표준 입력으로 JSON 형식의 페이로드를 수신하므로, cat은 전체 기록을 추가합니다. 작업하는 동안 tail -f /tmp/instructions-loaded.log로 이를 모니터링하십시오. 이 이벤트의 종료 상태는 무시되므로 훅은 관찰만 가능하며 차단할 수는 없습니다. 파일이 로드될 것으로 예상되는 세션 중에 해당 로그에 중첩된 파일이 나타나지 않는다면, 수정을 중단하십시오. 문제는 파일의 위치에 있습니다.

긴 세션이 규칙에 미치는 영향

여기에는 두 가지 별개의 효과가 적용되며, 각각 다른 대응이 필요합니다.

거리(Distance). 1턴에 명시된 규칙은 90턴이 지난 시점에도 컨텍스트 윈도우에 남아 있지만, 현재 수행 중인 작업과 더 밀접하고 최근에 작성된 90턴 분량의 텍스트와 경쟁하게 됩니다. 이를 설정으로 해결할 수는 없지만 측정할 수는 있습니다. 새로운 세션에서 동일한 작업을 실행해 보십시오. 규칙이 새 세션에서는 유지되지만 긴 세션의 후반부에서 실패한다면, 원인은 거리 때문입니다.

압축(Compaction). 윈도우가 가득 차면 하네스(harness)는 지금까지의 대화를 요약하고 해당 요약본을 바탕으로 대화를 이어갑니다. 이때 살아남는 정보는 요약기가 중요하다고 판단한 내용이며, 이는 사용자가 중요하게 생각하는 것과 다를 수 있습니다. Claude Code는 메커니즘별로 결과를 문서화하며, 그 차이는 큽니다. 프로젝트 루트 CLAUDE.md 및 범위가 지정되지 않은 규칙은 압축 후 디스크에서 다시 주입됩니다. 자동 메모리(Auto memory)도 디스크에서 다시 주입됩니다. paths: 프런트매터가 포함된 규칙은 일치하는 파일이 다시 읽힐 때까지 소실됩니다. 하위 디렉터리에 중첩된 CLAUDE.md 파일은 해당 하위 디렉터리의 파일이 다시 읽힐 때까지 소실됩니다.

지침을 위 표에 따라 순위를 매기면 취약성 순서가 드러납니다. 채팅에만 입력한 규칙은 세션에서 가장 취약합니다. 요약 과정에서 운 좋게 유지되는 경우에만 지속됩니다. packages/api/CLAUDE.md에 있는 규칙은 그다음으로 취약합니다. 한 번 로드된 후 요약 과정에서 사라지며, 해당 디렉터리에서 다시 읽기가 발생할 때만 복구되기 때문입니다. 프로젝트 루트 파일에 있는 규칙이 가장 내구성이 높습니다. 매번 디스크에서 다시 읽어오기 때문입니다.

따라서 지침이 전체 세션 동안 유지되어야 한다면, paths: 프런트매터 없이 프로젝트 루트 파일에 작성해야 합니다. 그 외의 모든 방식은 의도적으로 선택해야 하는 트레이드오프입니다. 컨텍스트 윈도우 유지 관리에서는 focus 인수를 사용한 /compact와 관련 없는 작업 간의 /clear을 다룹니다. 이 두 가지 모두 요약기가 사용자의 규칙을 결정하는 빈도에 영향을 미칩니다.

왜 주변 코드가 규칙을 압도하는가

이는 사람들이 가장 자주 언급하지만 가장 적게 진단하는 실패 사례입니다. 파일에는 데이터베이스 접근이 repository 계층을 거쳐야 한다고 명시되어 있습니다. 하지만 에이전트는 ORM(object relational mapper)을 직접 호출하는 핸들러를 작성합니다. 이는 스타일 문제로 무시당한 것이 아닙니다. 증거에 의해 투표에서 밀린 것입니다.

규칙은 선호 사항을 기술합니다. 코드는 실제 사례를 보여줍니다. 에이전트가 수정하려는 모듈에서 3개의 파일을 열었는데 그 3개 모두 ORM을 직접 호출한다면, 컨텍스트에는 한쪽에는 추상적인 문장 하나가, 다른 쪽에는 구체적이고 최근이며 작업과 일치하는 예시 3개가 놓이게 됩니다. 로컬 패턴을 복사하는 것은 보통 올바른 동작입니다. 하지만 여기서는 당신만이 알고 있는 사실, 즉 해당 파일들이 레거시라는 점 때문에 잘못된 동작이 됩니다.

따라서 이를 규칙에 명시하십시오. 자신의 반대 증거를 스스로 명시하는 규칙만이 실제 저장소와의 접촉에서 살아남습니다. 단순히 선호 사항만 나열하는 규칙은 살아남지 못합니다.

새로운 데이터베이스 접근은 app/repositories/을 거쳐야 합니다. app/legacy/ 하위의 파일들은 여전히 ORM을 직접 호출합니다. 이는 오래된 코드이며 패턴이 아닙니다. 이를 복사하지 마십시오.

두 번째 문장이 핵심적인 역할을 합니다. 에이전트가 코드를 발견하기 전에 무엇을 찾게 될지, 그리고 그것을 어떻게 해석해야 할지 미리 알려줍니다. 동일한 수정 방식이 저장소와 명백히 모순되는 모든 규칙에 적용됩니다. 커밋 기록이 따르지 않는 커밋 스타일, 테스트 스위트의 절반이 무시하는 테스트 레이아웃, 새로운 코드에서만 유지되는 import 관례 등이 이에 해당합니다. 코드가 파일의 내용과 일치하지 않는 곳이 있다면, 그 불일치 사항을 파일에 명시하십시오.

모호한 규칙은 검증할 수 없으므로 준수할 수도 없습니다

"깔끔한 코드를 작성하십시오.", "과도한 엔지니어링을 피하십시오.", "단순하게 유지하십시오.", "마이그레이션 시 주의하십시오." 이 중 어떤 것도 에이전트나 사용자가 특정 동작을 기준으로 테스트할 수 없습니다. 자신의 출력 결과가 규칙에 부합하는지 확인할 수 없는 에이전트는 추측할 뿐이며, 사용자는 그 추측을 느낌에 의존해 평가하게 됩니다.

파일의 모든 줄에 다음 테스트를 적용하십시오. 규칙을 위반했을 때 0이 아닌 종료 코드를 반환하는 셸 명령어를 작성해 보십시오. 해당 명령어를 작성할 수 없다면 그 규칙은 검증 불가능한 것입니다. 다음 쌍을 비교해 보십시오.

검증 불가: "함수를 작게 유지하십시오." 검증 가능: "60줄이 넘는 함수는 그 이유를 설명하는 주석을 위에 작성해야 합니다."
검증 불가: "변경 사항을 테스트하십시오." 검증 가능: "작업 완료를 선언하기 전에 npm test를 실행하고 실패 횟수를 붙여넣으십시오."
검증 불가: "파일을 체계적으로 정리하십시오." 검증 가능: "HTTP 핸들러는 src/api/handlers/에 위치해야 합니다. 해당 디렉터리에는 다른 파일이 포함될 수 없습니다."
검증 불가: "코드를 올바르게 포맷하십시오." 검증 가능: ".ts 파일에는 2칸 들여쓰기를 사용하십시오."

"과도한 엔지니어링을 피하십시오"는 사람들이 가장 먼저 포기하는 규칙입니다. 해결책은 문장을 짧게 만드는 것이 아니라 더 길게 만드는 것이기 때문입니다. 작동하는 가장 작은 변경이 무엇인지 구체적으로 명시하면 에이전트가 자신의 diff 결과와 대조할 수 있는 기준을 제공하게 됩니다.

크기 문제도 같은 맥락입니다. Claude Code의 지침은 지침 파일당 200줄 미만을 권장하며, 파일이 길어질수록 준수율이 떨어진다고 명시합니다. 700줄짜리 파일이 더 강력한 지침이 되는 것은 아닙니다. 이는 서로 모순될 가능성이 큰 700줄의 주장일 뿐이며, 모든 턴마다 컨텍스트 윈도우를 소모하므로 토큰 사용량에 직접적으로 나타납니다. 독자가 훑어볼 수 있도록 각 규칙을 제목 아래에 배치하여 파일을 구조화하는 방법은 에이전트가 실행 가능한 지침 파일 작성하기에서 다룹니다.

10분 안에 진단하는 방법

다음 순서대로 실행하십시오. 마지막 단계로 바로 건너뛰면 작동하지 않는 규칙들만 잔뜩 나열된 긴 파일이 만들어질 뿐입니다.

로드 여부 확인. /context를 실행하여 Memory 파일 목록을 읽으십시오. 파일이 목록에 없다면 위치를 수정하고 중단하십시오. 이 목록의 다른 단계는 아직 적용되지 않습니다.
새 세션에서 재현. 새 세션을 시작하고 해당 규칙이 트리거되어야 하는 가장 작은 작업을 수행하십시오. 여기서 성공하지만 긴 세션에서 실패한다면 거리(distance)나 압축(compaction) 문제일 가능성이 큽니다. 여기서도 실패한다면 규칙 자체가 문제입니다.
경합 요소 제거. 이미 규칙을 따르고 있는 디렉터리에서 동일한 변경을 요청하십시오. 준수 상태가 돌아온다면 주변 코드가 작성한 규칙보다 우선순위를 가졌던 것입니다.
충돌 검색. 동일한 동작에 대해 서로 다른 지침을 제공하는 두 개의 파일은 문서화된 오류입니다. 모델은 임의로 하나를 선택할 수 있으며, 이 사실을 사용자에게 알리지 않습니다.
검증 가능하게 만들고 재테스트. 구체적인 경로와 조건을 사용하여 규칙을 다시 작성하십시오. 준수율이 크게 상승했다면 문구 설정이 원인이었던 것입니다.

4단계는 하나의 명령어로 수행할 수 있습니다. 편집 중인 파일뿐만 아니라 모든 명령어 소스에서 해당 주제를 grep 하십시오.

grep -rni "migration" --include="CLAUDE.md" --include="CLAUDE.local.md" .
grep -rni "migration" .claude/rules/ ~/.claude/CLAUDE.md ~/.claude/rules/ 2>/dev/null

서로 다른 내용을 담은 두 파일에서 결과가 검색된다면 그것이 버그입니다. 하나를 삭제하십시오. 더 강한 어조로 우선순위를 정하려 하지 마십시오. 적용할 수 있는 순위 결정 엔진이 존재하지 않기 때문입니다.

영향력 순서에 따른 해결책

아래의 각 단계는 이전 단계보다 더 큰 영향력을 가지며, 설정에 더 많은 비용이 듭니다. 규칙을 수정하는 비용이 저렴할 때는 상단부터 시작하십시오. 가끔 발생하는 누락조차 허용할 수 없을 정도로 규칙이 중요해지는 순간 아래 단계로 이동하십시오.

규칙을 구체화하십시오. 경로, 명령어 또는 조건을 명시하십시오. 앞서 설명한 것처럼 에이전트가 저장소에서 찾을 수 있는 반증 사례를 추가하십시오. 이는 비용이 들지 않으며 놀라울 정도로 많은 사례를 해결합니다.
규칙을 적용 대상에 더 가깝게 배치하십시오. 중첩된 CLAUDE.md, .claude/rules/ 내의 경로 범위 규칙, 또는 파일 최상단의 주석을 활용하십시오. 이렇게 하면 규칙이 적용되는 코드와 함께 규칙을 읽게 됩니다. 트레이드오프를 수용하십시오. 이런 방식으로 로드된 모든 항목은 다음 압축(compaction) 시 제거되고, 다음 일치 읽기(matching read) 시 다시 돌아옵니다.
강제 적용을 훅(hook)으로 옮기십시오. 산문은 요청할 뿐이지만, 훅은 결정합니다. 훅은 고정된 라이프사이클 이벤트에서 코드로 실행되며, 모델의 판단과 관계없이 적용됩니다.
결정론적 도구에 규칙을 맡기고 산문을 삭제하십시오. 포맷팅, 임포트 순서, 줄 길이, 금지된 임포트, 커밋 메시지 형식이 이에 해당합니다. ruff format, prettier --write, eslint, pre-commit 훅을 사용하십시오. 포맷터는 항상 정확하며 토큰 비용이 0입니다. 문장은 대부분의 경우에 정확하지만 매번 토큰 비용이 발생합니다.

3단계를 상세히 설명합니다. 마이그레이션 파일은 에이전트가 절대 수정해서는 안 된다고 가정해 보겠습니다. .claude/settings.json에 다음을 넣으십시오:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/guard-migrations.sh"
          }
        ]
      }
    ]
  }
}

그리고 .claude/hooks/guard-migrations.sh에 다음을 넣으십시오:

#!/usr/bin/env bash
set -euo pipefail

path=$(jq -r '.tool_input.file_path // empty')

case "$path" in
  */migrations/*)
    echo "Files under migrations/ are written by hand. Stop and ask first." >&2
    exit 2
    ;;
esac

exit 0

chmod +x .claude/hooks/guard-migrations.sh을 실행한 다음, 새 세션을 시작하고 에이전트에게 migrations/ 아래의 파일을 수정하도록 요청하십시오. 수정은 거부되며 귀하의 메시지가 이유로 반환됩니다. PreToolUse에서 종료 상태 2는 도구 호출이 실행되기 전에 이를 차단하며, 귀하의 stderr 텍스트는 차단 메시지로서 모델에 전달됩니다. ${CLAUDE_PROJECT_DIR}는 프로젝트 루트로 해석되므로, 에이전트가 어느 디렉터리에 있든 훅은 작동합니다. 에이전트는 규칙에 동의하거나, 규칙을 기억하거나, 규칙을 컨텍스트에 유지할 필요가 없습니다. 수정은 일어나지 않습니다.

논리가 없는 단순한 금지의 경우, 설정의 permissions.deny가 유지 관리할 스크립트 없이 동일한 작업을 수행하며, 권한 모드가 먼저 묻지 않고 실행 여부를 결정합니다. 지침이 사용자 메시지가 아닌 시스템 프롬프트 수준에 반드시 있어야 한다면, --append-system-prompt을 사용하여 배치하십시오. 단, 이 경우 호출할 때마다 전달되어야 하므로 대화형 작업보다는 스크립트에 더 적합합니다.

지시로 해결할 수 없는 것

어떤 부분이 사용자의 책임인지 명확히 구분해야 합니다. 배치, 문구, 파일 간의 충돌, 파일 크기는 작성자의 문제이며 작성자가 해결해야 합니다. 나머지는 모델의 동작 방식이며, 더 나은 표현을 사용한다고 해서 해결되지 않습니다.

동의가 곧 준수는 아닙니다. 에이전트는 규칙을 인지하고 올바르게 다시 설명할 수 있지만, 두 번의 도구 호출 뒤에 바로 규칙을 어길 수 있습니다. 인지한다는 응답은 비용이 들지 않으며 아무것도 보장하지 않습니다. 이를 해결책으로 간주하거나 테스트 결과로 보지 마십시오.

일부 습관은 끈질깁니다. 주석 추가, 방어적 오류 처리 추가, 마무리 요약 작성, 당연한 다음 명령 실행 등이 이에 해당합니다. 이러한 행동은 금지 규칙을 설정해도 완전히 사라지지 않고 빈도만 줄어들 뿐입니다. 직접 빈도를 측정해 보십시오. 새로운 세션에서 동일한 작업을 10번 수행하여 위반 횟수를 세어 보는 것입니다. 위반 횟수가 0이어야 하는 작업이라면, 해당 규칙을 프롬프트에서 제거해야 합니다.

사용자의 세션 자체가 예시가 됩니다. 에이전트가 12번째 턴에서 규칙을 어겼는데 이를 그대로 두면, 해당 위반 사례가 컨텍스트에 남아 예시로 작용하게 됩니다. 이는 규칙보다 훨씬 최근의 정보입니다. 위반 사항은 발견 즉시 수정하십시오. 수정되지 않은 위반은 남은 세션 전체에 잘못된 학습을 제공합니다.

지시 파일은 보안 경계가 아닙니다. 이는 행동을 형성할 뿐 강제하지는 않습니다. 자격 증명이나 파괴적인 명령처럼 실수가 치명적인 작업은 권한 설정이나 훅(hook)을 통해 관리해야 합니다. 에이전트가 비밀 정보에 접근하지 못하게 하기는 데이터에 동일한 원칙을 적용합니다. 에이전트에게 파일을 읽지 말라고 요청하는 대신, 파일 자체를 읽을 수 없도록 설정하십시오.

요약하자면 다음과 같습니다. 파일이 로드되었음을 증명하고, 규칙을 검증 가능하게 만들고, 규칙이 적용되는 대상 바로 옆에 배치하십시오. 그럼에도 오답률이 중요하다면, 산문 형태의 지시에서 제외하십시오. 에이전트가 무시할 수 없는 규칙은 애초에 에이전트에게 요청하지 않은 규칙입니다.

FAQ

Claude Code가 CLAUDE.md를 무시하는 이유는 무엇입니까?

무시되었다고 단정하기 전에 파일이 로드되었는지 확인하십시오. /context을 실행하여 Memory files 목록을 확인하십시오. 해당 목록에 없는 파일은 대화에 포함되지 않은 것입니다. 지침 파일은 시스템 프롬프트 이후 사용자 메시지로 전달되며, 강제된 설정이 아닌 컨텍스트로 취급되므로 엄격한 준수가 보장되지 않습니다. 대부분의 실제 사례는 다음 네 가지 중 하나입니다. 에이전트가 읽지 않은 하위 디렉터리에 파일이 있거나, 두 파일의 내용이 충돌하여 모델이 임의로 하나를 선택했거나, 규칙이 너무 모호하여 동작을 검증할 수 없거나, 주변 코드가 규칙과 반대되는 내용을 보여주는 경우입니다.

세션 도중에 지침 파일을 수정하면 변경 사항이 적용됩니까?

이미 대화에 포함된 복사본에는 적용되지 않습니다. 작업 디렉터리 상위의 파일은 시작 시 전체가 로드되므로, 모델이 보유한 텍스트는 시작 시점의 내용입니다. 수정 사항을 반영하려면 새 세션을 시작하거나, 에이전트에게 일반 파일 도구로 해당 파일을 읽도록 요청하여 현재 버전을 새로운 메시지로 대화에 포함시키십시오. 압축(compaction)이 수행되면 프로젝트 루트 파일은 디스크에서 다시 읽히므로, 이때 새로운 버전이 반영됩니다.

루트 CLAUDE.md와 하위 디렉터리의 파일 내용이 충돌하면 어느 것이 우선합니까?

확실하게 우선하는 것은 없습니다. 발견된 파일들은 서로를 덮어쓰는 것이 아니라 컨텍스트에 순차적으로 연결(concatenate)됩니다. 파일 시스템 루트에서 작업 디렉터리 방향으로 읽히므로, 가장 가까운 파일이 마지막에 읽힐 뿐입니다. 모순을 해결하는 우선순위 엔진은 없으며, Claude Code 문서에 따르면 상충하는 규칙은 임의로 해결될 수 있습니다. 하위 파일은 적용 범위를 명시하는 추가적인 내용으로 작성하고, 우선순위를 다투기보다 모순되는 내용을 삭제하십시오.

/compact 명령을 사용해도 지침이 유지됩니까?

로드 방식에 따라 다릅니다. 프로젝트 루트의 CLAUDE.md, 범위가 지정되지 않은 규칙, 자동 메모리는 압축 후 디스크에서 다시 주입됩니다. paths: 프런트매터가 포함된 규칙과 하위 디렉터리의 CLAUDE.md 파일은 일치하는 파일이 다시 읽히기 전까지는 유실됩니다. 채팅에 직접 입력한 내용은 요약 과정에서 유지된 경우에만 살아남습니다. 규칙이 세션 전체에 걸쳐 유지되어야 한다면, paths: 프런트매터 없이 프로젝트 루트 파일에 작성하십시오.

규칙을 산문 대신 훅(hook)으로 만들어야 하는 경우는 언제입니까?

검증이 결정론적이고, 규칙을 놓쳤을 때의 비용이 작은 스크립트를 작성하는 비용보다 클 때입니다. 파일 경로 제한, 커밋 전 필수 명령, 금지된 도구 호출 등이 이에 해당합니다. 상태 코드 2로 종료되는 PreToolUse 훅은 도구 호출을 즉시 차단하고 stderr 텍스트를 이유로 모델에 반환하므로, 규칙이 컨텍스트 내 어디에 있든 상관없이 적용됩니다. 포맷터나 린터가 판단할 수 있는 모든 사항은 해당 도구가 처리하도록 하고 지침 파일에서는 완전히 삭제하십시오.

#claude-code #agents-md #context #prompting #coding-agents