세션이 바뀌어도 남는 프로젝트 맥락

Claude Code는 프로젝트 폴더에서 시작할 때마다 루트에 CLAUDE.md라는 파일이 있는지 먼저 찾아보고, 있으면 그 내용을 읽습니다. 읽은 내용은 여러분이 메시지를 입력하기 전에 프롬프트 앞쪽에 붙습니다. 그래서 여기에 적어 둔 규칙·제약·명령은 매 세션 첫 프롬프트부터 이미 적용된 상태가 됩니다. 매번 다시 설명하지 않아도 되는 것이죠.

/init 명령을 쓰면 Claude Code가 코드베이스를 훑어서 CLAUDE.md 초안을 만들어 줍니다. 이 초안은 출발점으로 쓰기 좋지만, 그대로 쓰기 전에 한번 검토해 보는 것이 좋습니다. 프롬프트의 결과를 좌우하는 규칙들 — 테스트 명령, 프레임워크 규약, 에이전트가 건드리면 안 되는 경로, 기본값과 다른 스타일 결정 — 을 담도록 다듬으면 됩니다.

가장 흔한 실패는 파일이 너무 커지는 것입니다. 새 지시가 생길 때마다 CLAUDE.md에 계속 덧붙이다 보면, 정작 중요한 규칙이 묻히기 쉽습니다. 파일이 커질수록 맥락 창을 더 많이 차지하고, 그만큼 규칙 하나하나가 전체에서 차지하는 비중은 작아집니다. 그러면 실수를 잡아 줄 바로 그 규칙 하나를 에이전트가 놓칠 가능성도 함께 커집니다. CLAUDE.md에는 행동을 실제로 바꾸는 제약만 남기고, 나머지는 필요할 때만 불러오는 스킬(Skill)로 옮겨 두는 편이 좋습니다.

CLAUDE.md는 프로젝트 전체에 걸쳐 항상 적용되니, 어디서나 통하는 지시를 담기에 좋습니다. 그런데 코드베이스의 특정 부분에서만 필요한 안내라면 어떻게 할까요. 이럴 때 쓰는 것이 룰 파일입니다. 모든 세션에 무조건 싣는 대신, 관련 있는 곳에서만 지시가 적용되도록 범위를 좁혀 줍니다.

CLAUDE.md는 언제나 켜져 있는 기본 층이고, 룰 파일은 그 위에 더 좁은 층을 얹습니다. 룰 파일은 프로젝트의 .claude/rules/ 폴더에 두고, 프론트매터파일 맨 위에 --- 로 감싸 적는 설정 영역. 룰 파일은 여기에 적용 범위를 적는다.의 paths 글로브glob — * 나 ** 같은 기호로 여러 파일 경로를 한 번에 가리키는 패턴.로 특정 경로에 묶을 수 있습니다. 이렇게 범위를 정해 둔 규칙은 Claude Code가 그 패턴에 맞는 파일을 다룰 때만 맥락으로 불러옵니다. 덕분에 코드베이스의 한 부분에만 필요한 규칙을, 나머지 맥락을 어지럽히지 않고 적용할 수 있습니다.

여기서 한 가지 짚어 둘 점은, 범위를 정하는 것은 프론트매터이지 파일 위치가 아니라는 것입니다. 룰 파일을 .claude/rules/database/처럼 하위 폴더로 정리할 수는 있지만, 그 폴더 구조는 정리용이며, 동작과는 무관합니다. paths 항목이 없는 룰 파일은 어디에 있든 시작 시점에 무조건 불러와지고, 우선순위도 CLAUDE.md와 같습니다.

정리하면, 넓은 프로젝트 기억과 어디서나 통하는 제약은 CLAUDE.md에, 특정 경로에만 해당하는 좁은 안내는 paths로 범위를 정한 룰 파일에 두면 됩니다. 예를 들어 '스키마는 절대 수정하지 않는다'는 제약은 어디서나 통하니 CLAUDE.md에 둡니다. 반면 '데이터베이스 모듈의 모든 SQL은 트랜잭션 경계를 명시해야 한다'처럼 좁은 규칙은 .claude/rules/database.md에 두고, 프론트매터에 이렇게 적습니다.

database.md 프론트매터 — 이 경로의 파일을 다룰 때만 규칙이 켜진다

---
paths:
  - "src/db/**/*.sql"
---

이렇게 적어 두면 Claude가 src/db 아래의 SQL 파일을 다룰 때에만 이 규칙이 맥락에 들어옵니다. 다른 작업을 할 때는 이 규칙이 자리를 차지하지 않습니다.

훅은 도구 호출이 실행되기 전이나 후에 끼어들어 그 호출을 다룰 수 있게 해 줍니다. 예를 들어 '파일을 수정할 때마다 Prettier(코드 정렬 도구)를 실행하라'는 규칙을 CLAUDE.md에 적어 두면, 에이전트는 대체로 그 규칙을 따릅니다. 반면 같은 일을 훅으로 걸어 두면, 모델이 무엇을 하기로 결정하든 상관없이 그 일이 매번 예외 없이 일어납니다. 훅은 모델의 판단과 독립적으로 실행되기 때문입니다.

훅은 설정 파일에 정의하고 /hooks 명령으로 설정합니다. 훅 하나하나는 라이프사이클 이벤트 하나에 묶이고, 특정 도구 종류로 범위를 좁히는 매처matcher — 훅을 특정 도구 종류에만 적용되도록 걸러 주는 조건.를 선택적으로 붙이며, 이벤트가 발생하면 실행할 명령을 함께 지정합니다. 가드레일과 자동화에 주로 쓰이는 핵심 이벤트는 다음과 같습니다.

LIFECYCLE EVENTS — 훅을 걸 수 있는 주요 지점

PreToolUse 이벤트로 프로덕션(실서비스) 설정 경로의 수정을 막는 훅을 걸어 두면, 그 제약은 퍼미션 모드와 상관없이 모든 세션의 모든 도구 호출에서 강제됩니다. 이것이 가드레일과 관행의 차이입니다 — 관행은 대체로 지켜지고, 가드레일은 예외 없이 지켜집니다.

서브에이전트는 Claude Code가 특정 작업을 대신 맡길 수 있는 보조 에이전트입니다. 각 서브에이전트는 자기만의 별도 맥락에서 작업을 처리하고, 그 결과만 돌려줍니다. 메인 대화 기록도, 지금까지 맥락에 쌓인 파일도, 현재 세션 상태도 물려받지 않습니다. 작업을 넘기면 빈 상태에서 시작해 일을 끝낸 뒤 결과를 건네주는 것이죠.

Claude Code에 기본으로 들어 있는 서브에이전트들은 시작할 때 무엇을 불러오는지가 서로 다르고, 이 차이가 프로젝트 규칙이 어떻게 적용되는지를 결정합니다. 종류는 시간이 지나며 늘어 왔으니 최신 목록은 Claude Code 문서에서 확인하는 것이 좋습니다. 다만 프로젝트 규칙에 영향을 주는 갈림은 버전이 바뀌어도 유지됩니다. Explore와 Plan 서브에이전트는 조사를 빠르고 가볍게 하려고 CLAUDE.md와 git 상태를 건너뜁니다. 속도에 맞춰져 있어서, CLAUDE.md에 적어 둔 프로젝트 규칙이나 저장소 상태가 이들이 동작할 때는 맥락에 없습니다. 반면 general-purpose 서브에이전트는 둘 다 불러옵니다. Explore나 Plan에 작업을 맡겼는데 CLAUDE.md의 규칙이 지켜지지 않는다면, 그 맥락이 애초에 로드되지 않았기 때문입니다. 프로젝트 제약을 반드시 지켜야 하는 작업이라면 general-purpose 서브에이전트를 쓰거나, 필요한 규칙을 직접 불러오도록 만든 커스텀 서브에이전트를 씁니다.

커스텀 서브에이전트도 여러분의 스킬을 자동으로 보지는 않습니다. .claude/agents에 커스텀 서브에이전트를 정의했고 특정 스킬이 필요하다면, 그 스킬을 에이전트 프론트매터에 직접 적어 줘야 합니다. 기본 에이전트에는 미리 불러와 둔 스킬이 없습니다. 기본 에이전트에 스킬 기반 동작이 필요하다면, 필요한 스킬을 설정에 적은 커스텀 서브에이전트를 새로 만드는 것이 맞는 방법입니다.

지금까지 본 네 가지 장치 — CLAUDE.md, 룰 파일, 훅, 서브에이전트 — 는 각각 다른 절충을 합니다. 맥락을 얼마나 쓰는지와 얼마나 확실하게 적용되는지가 서로 달라서, 어떤 프로젝트 지식을 어디에 담을지 정할 때 이 차이를 기준으로 삼으면 됩니다. 아래 표는 각 장치가 무엇을 불러오고, 언제 실행되고, 맥락을 얼마나 쓰고, 무엇을 담기에 알맞은지를 정리한 것입니다.

MECHANISM MAP — 네 장치의 성격 비교

WHEN IT PAYS OFF — 설정에 시간 들일 값어치가 있을 때 / 없을 때

CLAUDE.md가 계속 커진 이유는, 새 규칙이 생길 때마다 그게 다 추가할 만해 보였기 때문입니다. 규칙 하나하나는 그럴듯했고, CLAUDE.md가 그걸 담을 자리로 맞아 보였습니다. 그런데 몇 주가 지나자 파일은 800줄을 넘겼습니다.

아래는 두 달에 걸쳐 팀이 규칙을 더해 온 어느 프로젝트의 세션 기록 일부입니다. 규칙 위반이 어떻게 일어났는지 순서대로 따라가 보겠습니다.

SESSION TRACE — 규칙은 있었지만 지켜지지 않은 기록

Session context window loaded:
  CLAUDE.md: 847 lines
  framework preferences (1–40), testing conventions (41–90),
  style guide (91–210), dependency rules (211–320),
  path restrictions (321–360), historical decisions (361–700),
  archived notes (701–847)

User: "Refactor the auth module to use the new token service.
       Do not modify the /legacy/tokens/ directory."

Claude Code: [Reading auth module ...]
Claude Code: [Editing auth/service.ts ...]
Claude Code: [Reading /legacy/tokens/store.ts for reference ...]
Claude Code: [Editing /legacy/tokens/store.ts to update interface ...]

CLAUDE.md line 347: "Do not modify files in /legacy/tokens/."

User: "You just edited /legacy/tokens/store.ts. I said not to
       touch that directory."
Claude Code: "I apologize. The restriction is in the project
instructions. The edit was made while updating the token
interface. I did not flag the conflict before proceeding."

규칙은 분명히 파일에 있었고, 에이전트도 그 규칙에 접근할 수 있었습니다. 문제는 규칙이 묽어졌다는 데 있었습니다. 나머지 846줄이 정작 중요한 그 한 줄의 무게를 떨어뜨린 것입니다. 과거 결정 기록과 보관용 메모는 어딘가에 적어 둘 만한 내용이긴 했지만, CLAUDE.md에 있을 내용은 아니었습니다.

이번 점검은 경로 제한을 강제하는 훅을 설정하는 상황입니다. 아래 설정에는 빈칸이 두 곳 있습니다. 도구 호출이 실행되기 전에 동작하는 라이프사이클 이벤트가 무엇인지, 그리고 .env.production 읽기를 막으려면 훅이 어떤 명령을 실행해야 하는지 골라 보세요.

HOOK CONFIG — 빈칸 두 곳을 채우는 문제

{
  "hooks": {
    "____________": [          // 빈칸 1: 이벤트
      {
        "matcher": "Read",
        "hooks": [{ "type": "command",
          "command": "____________" }]   // 빈칸 2: 명령
      }
    ]
  }
}

정답을 먼저 떠올려 본 뒤 골라 보세요. 맞히면 설명이 나옵니다.