다른 레포를 건드리면 그 레포 CLAUDE.md를 안 따른다 — 레포별 세션과 SendMessage

MSA 로 나뉜 서비스 레포 여러 개를 Claude Code 로 개발하고 있습니다. 그중 하나는 독자 프레임워크 위에 오래 쌓인 레거시 레포입니다. 건드리면 안 되는 코드가 있고 개발 방법과 절차도 따로 정해져 있어서, 그 내용을 레포의 하네스에 꼼꼼히 적어 두었습니다.

문제는 다른 서비스 레포에서 작업하던 세션이 이 레거시 레포를 건드릴 때 생겼습니다. 적어 둔 규칙을 세부까지 따르지 않았고, 그 때문에 문제가 여러 번 났습니다. 규칙을 더 자세히 적으면 해결될까요?

규칙이 부족해서가 아니었습니다. 그 세션은 레거시 레포의 하네스를 온전히 들고 있지 않았습니다. 2026년 9월 공식 문서와 Claude Code v2.1.270 기준으로 정리합니다.

하네스는 세션을 시작한 디렉토리를 따라갑니다

memory 문서에 따르면 Claude Code 는 시작할 때 작업 디렉토리와 모든 상위 디렉토리의 CLAUDE.md 를 읽고, 하위 디렉토리의 CLAUDE.md 는 그 안의 파일을 읽을 때 불러옵니다.

~/work/service-a 에서 시작한 세션이 ~/work/legacy-core 의 파일을 연다고 해 봅시다. 이 레포는 상위도 하위도 아닌 형제 디렉토리라서 어느 규칙에도 걸리지 않습니다.

hooks 와 권한 규칙은 더 좁습니다. permissions 문서는 "Hooks and other .claude/settings.json keys load from the current working directory's .claude/ folder with no parent-directory fallback" 라고 적고 있습니다.

--add-dir 로 열면 절반만 따라옵니다

그렇다면 레거시 레포를 작업 디렉토리로 추가하면 되지 않을까요? 방법에 따라 결과가 다릅니다. 같은 문서의 표를 정리하면 이렇습니다.

CLAUDE.md 까지 불러오려면 환경변수를 같이 줍니다.

CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 claude --add-dir ../legacy-core

그래도 settings 파일에서는 enabledPlugins 와 extraKnownMarketplaces 두 키만 읽습니다. 레거시 레포가 hook 으로 막아 둔 동작은 이 세션에서 막히지 않습니다.

이게 왜 문제일까요? memory 문서는 CLAUDE.md 를 두고 "Claude treats them as context, not enforced configuration" 이라며, 반드시 막아야 하는 동작은 PreToolUse hook 으로 막으라고 합니다. 건드리면 안 되는 코드처럼 꼭 지켜야 하는 규칙일수록 hook 에 두게 되는데(클로드 코드 Hooks), --add-dir 로는 바로 그 부분이 빠집니다.

CLAUDE.md 를 불러와도 문제가 하나 남습니다. 두 레포의 CLAUDE.md 가 한 컨텍스트에 이어 붙고, 규칙이 부딪히면 문서 표현대로 "Claude may pick one arbitrarily" 입니다. 새 서비스 레포와 독자 프레임워크 레거시 레포의 컨벤션은 부딪히기 쉽습니다.

/cd 는 하네스를 바꿔 끼웁니다

v2.1.246 부터 /cd <path> 로 작업 디렉토리를 옮기면 새 디렉토리의 CLAUDE.md, 설정, hooks, MCP 서버, skills 가 적용됩니다(permissions 문서). 레거시 규칙이 온전히 걸립니다.

하지만 대화는 이어지고 규칙만 바뀝니다. 서비스 A 의 맥락을 들고 레거시 규칙 아래에서 일하는 셈이라 두 레포의 전문성을 동시에 갖지 못합니다. 이전 디렉토리 설정의 env 값도 남습니다.

한 세션으로는 --add-dir 면 hooks 를, /cd 면 원래 레포의 규칙을 포기합니다. 그렇다면 세션을 나누면 어떨까요?

레포마다 세션을 두고 메시지로 협업시킵니다

v2.1.224 부터 Claude Code 세션끼리 메시지를 주고받을 수 있습니다(macOS·Linux 기준, Windows 는 v2.1.234). cross-session messaging 문서에 따르면 Claude 가 ListAgents 로 세션을 찾고 SendMessage 로 이름을 지정해 보냅니다. 따로 켤 설정은 없습니다.

cmux로 에이전트 오케스트레이션을 정리할 때는 통신 채널이 없어서 공유 파일이나 사람이 중계해야 했는데, 이제는 그 채널이 Claude Code 에 들어 있습니다.

레포마다 세션을 하나씩 띄우고 이름을 붙입니다.

# 터미널 1
cd ~/work/service-a && claude --name service-a
 
# 터미널 2
cd ~/work/legacy-core && claude --name legacy-core

legacy-core 세션은 레거시 레포에서 시작했으니 그 레포의 CLAUDE.md, skills, hooks, 권한이 전부 로드됩니다. service-a 세션에서는 @ 로 상대를 지목해 부탁합니다(v2.1.232 이상).

@legacy-core 에 주문 취소 이벤트를 받는 핸들러가 필요하다고 전해줘. 페이로드는 orderId, reason 두 필드야

실제 메시지 문장은 Claude 가 씁니다. 받는 세션이 쉬고 있으면 새 턴을 시작하고, 일하는 중이면 도구 호출 사이에 읽습니다. "legacy-core 가 끝나면 알려줘" 라고 하면 두 세션이 v2.1.236 이상일 때 한 번만 오는 idle 알림으로 받습니다.

받는 세션은 자기 하네스 안에서 일합니다

이 구조가 통하는 이유는 메시지로 넘어가는 것이 텍스트뿐이기 때문입니다. 문서는 "A message is a piece of text one Claude writes to another, never the sender's conversation history or files." 라고 적습니다. 요청은 건너가지만 실행은 받는 세션이 합니다.

받는 세션은 이 메시지를 사용자의 지시와 같게 취급하지도 않습니다.

• 대기 중인 권한 프롬프트를 대신 승인하지 못합니다
• 다른 세션이 요청했다고 CLAUDE.md 나 권한 설정을 바꾸지 않도록 지시돼 있습니다
• 받는 세션에 없는 권한이 필요하면 평소처럼 권한 프롬프트가 뜹니다

그래서 레거시 레포는 레거시 규칙을 전부 들고 있는 세션만 고치고, 요청이 수정 금지 영역에 닿으면 막는 것도 그 세션의 hook 입니다.

경계를 더 분명히 하려면 두 가지를 설정합니다. 먼저 service-a 레포의 .claude/settings.json 에서 레거시 레포를 직접 고치지 못하게 막습니다.

{
  "permissions": {
    "deny": ["Edit(~/work/legacy-core/**)"]
  }
}

deny 규칙은 파일을 스스로 여는 하위 프로세스까지 막지는 못하니, 완전한 격리가 아니라 실수를 막는 울타리입니다.

다음으로 레거시 레포의 CLAUDE.md 에 다른 세션의 요청을 받는 방법을 적어 둡니다.

## 다른 세션에서 요청이 오면
 
- 이 레포는 이 세션에서만 수정한다. 요청한 세션에는 변경 요약과 커밋 해시만 회신한다
- 수정 금지 영역에 걸리는 요청이면 고치지 말고 이유와 대안을 회신한다

이 방식이 맞지 않는 경우

한 레포 안에서 강하게 묶인 변경. large codebases 문서는 공유 타입과 호출부를 함께 고치는 변경이라면 "Give Claude the whole change in one session" 을 권합니다. 세션 분리는 하네스가 서로 다른 레포 사이에서 효과가 있습니다.

컨테이너 안의 세션. 세션은 디스크에 등록된 파일로 서로를 찾기 때문에, devcontainer 안의 세션과 호스트의 세션은 서로 닿지 않습니다.

권한 프롬프트를 끈 세션. crossSessionInbound 를 정하지 않았다면, 받는 세션이 bypassPermissions 모드일 때 보내는 쪽도 bypass 가 아닌 한 메시지를 승인 대기로 잡아 둡니다.

넘어가지 않는 맥락. 대화 기록이 넘어가지 않으니 필드명, 에러 코드 같은 계약은 메시지 안에 담겨 있어야 합니다. 빈약하면 받는 세션은 추측으로 채웁니다.

하네스를 잘 적어 두는 일과, 그 하네스가 로드된 세션이 그 레포를 고치게 하는 일은 다른 문제였습니다.