SSD Nodes Learn Hosting plans →
가이드 Matt Connor작성자 Matt Connor · 업데이트됨 2026-10-26

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

코딩 에이전트가 지침 파일을 무시하는 기술적 원인을 분석합니다. 컨텍스트 윈도우의 우선순위 문제와 하니스 동작 방식을 이해하고, 규칙이 충돌할 때 발생하는 문제를 진단하여 에이전트의 제어력을 높이는 구체적인 방법을 확인해 보시기 바랍니다.

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

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

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

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

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

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

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

공식 문서에도 이 점이 명시되어 있습니다. 지침 파일은 강제되는 설정이 아니라 컨텍스트로 취급됩니다. 모델의 판단과 관계없이 특정 동작을 차단하려면 문장이 아닌 후크(hook)가 필요합니다. 이 점을 명심하십시오. 이 글의 마지막에 제시된 대부분의 해결책은 이 원칙을 특정 사례에 적용한 것입니다.

지침 파일이 로드되는 시점과 방식

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

작업 디렉터리 하위에 있는 파일들은 다르게 동작합니다. 이 파일들은 실행 시점에 로드되지 않습니다. 에이전트가 해당 디렉터리에 있는 파일을 읽을 때 로드됩니다. .claude/rules/ 내의 경로 범위 규칙에 paths: 프런트매터 필드가 포함된 경우도 마찬가지입니다. 이 규칙들은 매 턴마다 적용되는 것이 아니라, 일치하는 파일을 읽을 때 컨텍스트에 포함됩니다. v2.1.309 버전부터는 이러한 방식으로 로드되는 파일에 파일당 크기 제한(200K 컨텍스트 윈도우 기준 40,000자)이 적용됩니다. 에이전트는 긴 파일의 시작 부분만 수신하므로, 큰 중첩 파일의 끝부분에 있는 규칙은 컨텍스트에 도달하지 못할 수 있습니다.

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

AGENTS.md을 표준으로 사용하는 저장소에는 또 다른 로딩 함정이 있습니다. v2.1.277 버전부터 Claude Code는 작업 디렉터리나 상위 디렉터리에 CLAUDE.md, .claude/CLAUDE.md, CLAUDE.local.md가 없을 때만 기본적으로 AGENTS.md을 프로젝트 지침으로 읽습니다(개인용 ~/.claude/CLAUDE.md는 포함되지 않습니다). 이 중 하나라도 추가하면, 개인 메모용 CLAUDE.local.md이라 할지라도 Claude Code는 CLAUDE.md 파일을 읽고 AGENTS.md은 완전히 제외합니다. 두 파일을 모두 로드하려면 /config에서 Project instructions를 claude-md-and-agents-md로 설정하십시오. v2.1.277 이전 버전이거나 CLAUDE.md을 유지하고 싶다면, 첫 줄이 @AGENTS.md인 CLAUDE.md를 브리지로 사용하십시오. 이 파일은 실행 시점에 대상 파일을 가져오며, 그 아래에 Claude 관련 메모를 추가할 수 있습니다. 추가할 내용이 없다면 심볼릭 링크를 사용해도 됩니다. 애초에 어떤 내용을 해당 파일에 포함할지 결정하는 것은 별개의 문제이며, 에이전트 지침과 인간용 문서 분리하기에서 다룹니다.

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

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

세션 내에서 /context을 실행하십시오. 이 명령은 현재 창을 범주별로 분류하여 출력하며, Memory files 목록에는 시작 시 로드된 모든 명령 파일의 이름이 표시됩니다. 이 목록에 없는 파일은 시작 시 로드되지 않은 것이므로, 로드되기 전까지는 해당 파일에 작성하는 내용이 아무런 영향을 미치지 않습니다. 하위 디렉터리에 있는 중첩 파일은 필요할 때 로드되므로 이 목록에 나타나지 않습니다. 파일이 로드될 때 터미널에 해당 경로와 함께 Loaded 줄이 나타납니다. /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를 사용하여 이를 모니터링하십시오. 이 이벤트의 종료 상태는 무시되므로 후크는 관찰만 가능하며 차단할 수는 없습니다. 중첩 파일이 로드될 것으로 예상되는 세션 동안 해당 로그에 나타나지 않는다면, 수정을 중단하십시오. 문제는 파일 위치에 있습니다. 한 가지 예외로, Claude Code가 직접 읽는 AGENTS.md은 이 이벤트를 발생시키지 않으므로 대신 /memory에서 해당 경로를 찾으십시오. CLAUDE.md에서 가져온 AGENTS.md은 평소와 같이 이벤트를 발생시킵니다.

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

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

거리(Distance). 컴팩션(compaction)이 실행되기 전까지는 1턴에 명시한 규칙도 90턴 시점의 윈도우에 여전히 남아 있습니다. 하지만 이제는 현재 수행 중인 작업과 더 관련이 깊고 최신인 90턴 분량의 텍스트와 경쟁하게 됩니다. 컴팩션이 한 번 실행되고 나면, 채팅창에만 입력했던 규칙은 윈도우에서 완전히 사라질 수 있습니다. Claude Code의 자체 문서에서도 대화 초반의 지시 사항이 유실될 수 있다고 경고하는데, 이것이 아래에서 설명할 두 번째 효과입니다. 거리는 설정으로 해결할 수 없지만 측정은 가능합니다. 새로운 세션에서 동일한 작업을 실행해 보십시오. 해당 규칙이 새 세션에서는 유지되다가 긴 세션의 후반부에서만 실패한다면, 원인은 거리나 컴팩션에 있습니다.

컴팩션(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분 안에 진단하는 방법

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

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

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

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

서로 다른 내용을 담은 두 파일에서 검색 결과가 나온다면 그것이 버그입니다. 하나를 삭제하십시오. 더 강한 어조로 순위를 매기려 하지 마십시오. 순위를 결정하는 엔진은 존재하지 않기 때문입니다. Claude Code v2.1.283 이상 버전에서는 /doctor prompt-audit을 통해 지침 파일, 규칙, 기술 전반에 걸쳐 더 광범위한 검색을 수행할 수 있으며, 사용자가 요청하기 전까지는 아무것도 변경하지 않고 모순된 내용을 제안된 수정 사항과 함께 보고합니다.

영향력 순서에 따른 해결책

아래의 각 단계는 이전 단계보다 더 큰 영향력을 가지며, 설정 비용도 더 많이 듭니다. 규칙을 문구 수정만으로 해결할 수 있다면 상단부터 시작하십시오. 규칙이 중요해져서 가끔 발생하는 누락조차 허용할 수 없는 시점이 오면 아래 단계로 이동하십시오.

  1. 규칙을 구체화하십시오. 경로, 명령어 또는 조건을 명시하십시오. 앞서 설명한 것처럼 에이전트가 저장소에서 찾을 수 있는 반증 사례를 추가하십시오. 이는 비용이 들지 않으며 놀라울 정도로 많은 사례를 해결합니다.
  2. 규칙을 적용 대상에 더 가깝게 배치하십시오. 중첩된 CLAUDE.md, .claude/rules/ 내의 경로 범위 규칙, 또는 파일 최상단의 주석을 활용하십시오. 이렇게 하면 코드를 읽을 때 규칙도 함께 확인하게 됩니다. 트레이드오프를 수용하십시오. 이런 방식으로 로드된 내용은 다음 압축(compaction) 시 사라졌다가, 다음 일치하는 읽기 작업 시 다시 돌아옵니다.
  3. 강제 적용을 훅(hook)으로 옮기십시오. 산문은 요청할 뿐이지만, 훅은 결정합니다. 훅은 고정된 라이프사이클 이벤트에서 코드로 실행되며, 모델의 판단과 관계없이 적용됩니다.
  4. 결정론적 도구에 규칙을 맡기고 산문은 삭제하십시오. 포맷팅, 임포트 순서, 줄 길이, 금지된 임포트, 커밋 메시지 형식이 이에 해당합니다. 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이어야 하는 경우, 해당 규칙은 프롬프트에서 제거해야 합니다. 작업이 완료되지 않았는데 완료되었다고 보고하는 것도 같은 유형의 습관입니다. 이에 대한 해결책은 언어적 지시가 아닌 구조적 접근입니다. 게으름을 피우지 않는 기술은 문장 대신 Depth Tree를 사용하고, 에이전트가 완료를 선언하기 전에 반드시 통과해야 하는 게이트 파일을 설정하는 것입니다.

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

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

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

FAQ

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

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

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

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

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

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

/compact 명령을 실행해도 지침이 유지됩니까?

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

규칙을 텍스트가 아닌 훅(hook)으로 만들어야 하는 때는 언제입니까?

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

이 글이 도움이 되었나요?