Claude Code 대화가 줄어도 경로를 잃지 않게, 경로대장과 작업일지

대화가 길어져 압축되면 지나가듯 말한 경로가 사라져요. 운영자가 같은 말을 두 번 한 날 만든 경로대장·작업일지와 읽는 순서예요.

한 줄 답

운영자가 말한 경로·계정·값은 대화에만 두지 말고 «경로대장» 파일에, 날마다 한 일과 운영자 말은 «작업일지»에 적으세요. 일을 시작할 때 이 둘부터 읽게 하되, 적힌 값도 틀릴 수 있으니 안 맞아 보이면 물어요.

준비물

도구Claude Code, 저장소 안의 문서 폴더(docs)
돈따로 드는 돈은 없어요.
걸리는 시간파일 두 개와 규칙 몇 줄이라 처음 만드는 데 길지 않아요.
난이도입문. 마크다운 파일을 만들 줄 알면 돼요.

차례

한 화면에 한 단계씩 넘기며 보세요.

한 쪽에 모두 보기

Claude Code는 대화가 길어지면 앞부분을 요약으로 바꿔 자리를 비워요(압축). 그때 운영자가 지나가듯 말한 것이 요약에서 빠질 수 있어요. 2026년 9월 8일 한 저장소의 커밋에 운영자 말이 이렇게 남아 있어요.

«C:\…\블로그\… 여기 월별 폴더에 다 있어 이거 저번에 한번 얘기했었는데 컴팩트할때 사라졌나보다. 컴팩트할때마다 주요내용들을 일자별로 정리한 폴더하나 있으면 좋을 것 같고, 작업시작하기전에 한번 스캔하고 가는쪽으로 워크플로우를 만들어주면 좋을거같은데»

제품 사진이 있는 폴더 경로를 앞에서 한 번 알려 줬는데, 압축 뒤 AI가 그것을 잃어서 운영자가 다시 말해야 했어요. 커밋에는 «대화 이력은 믿을 수 있는 저장소가 아니다. 남겨야 할 것은 파일로 남긴다.»라고 적었어요.

공식 문서의 설명

Claude Code 공식 문서도 같은 말을 해요.

If an instruction disappeared after compaction, it was given only in conversation, lives in a nested CLAUDE.md that hasn't reloaded yet, or is a path-scoped rule that hasn't matched a file since. Add conversation-only instructions to CLAUDE.md to make them persist.

그날 만든 세 가지

운영자가 말한 값을 AI가 경로대장과 작업일지에 적고, 다음에 일을 시작할 때 정해진 순서로 읽고, 값이 안 맞아 보일 때만 묻는 네 단계.

경로대장(docs/경로대장.md). 지금 유효한 경로·계정·값을 한곳에 모아요. 코드는 git이 기억하니 적지 않고, 다른 문서에 이미 있는 것은 링크만 둬요.
작업일지(docs/작업일지/날짜.md). 대화가 압축될 때와 일이 끝날 때 그날 기록을 덧붙여요. 운영자가 한 말은 요약하지 않고 그대로 옮겨요. 줄여 적으면 그 자리에서 또 빠져요. 커밋에도 «요약하면 그 자리에서 또 사라진다»로 적혀 있어요.
일을 열 때 읽는 순서. 경로대장, 최근 사흘 작업일지, 중단 기록, 그 영역의 인수인계 문서 순으로 읽어요. 이 순서는 모든 세션에 들어가는 개인 설정 파일(~/.claude/CLAUDE.md)과 저장소의 CLAUDE.md 에 적었어요.

경로대장에는 처음부터 단서를 하나 달았어요.

경로대장은 «먼저 볼 곳»이지 «묻지 않아도 되는 근거»가 아니다. 값이 안 맞아 보이면 묻는다. 다만 적혀 있는데 또 묻지는 않는다.

같은 커밋에는 낡은 메모가 일을 헛돌게 한 예도 남았어요. «재로그인 필요»라는 옛 메모 때문에, 이미 로그인돼 있던 배포 도구를 두고 두 번 헛돌았다는 기록이에요. 경로대장에는 «지금 유효한 값»만 두고, 바뀌면 그 자리에서 고쳐요.

이 방식은 그 뒤 다른 저장소로 옮겨 갔어요. 저장소마다 경로대장이 처음 생긴 커밋은 9월 11일, 9월 15일, 9월 19일이에요.

막혔던 곳

문서에 있는데 추측했어요

장치를 만든 다음 날 작업일지에 이런 반성이 적혔어요. AI는 그동안 여러 번 «Cloudflare Pages는 main 브랜치를 본다»고 말했는데, 배포 문서에는 다른 브랜치가 적혀 있었어요.

문서에 있는 값을 안 읽고 추측으로 말했다. 경로대장에 박아 둔다.

경로대장의 값도 틀렸어요

9월 11일에는 경로대장에 적힌 브랜드 이름의 표기가 틀려 고친 커밋이 있어요. 경로대장도 사람과 AI가 손으로 적는 파일이라 틀릴 수 있어요. 단서 조항이 필요한 이유가 여기 있어요.

지시문이라 건너뛸 수 있어요

읽는 순서는 CLAUDE.md 에 적은 지시문이에요. 공식 문서는 이렇게 설명해요.

Claude treats them as context, not enforced configuration. To block an action regardless of what Claude decides, use a PreToolUse hook instead.

그래서 AI가 이 순서를 건너뛰면 막을 장치는 없어요. 막혔던 곳의 «문서에 있는데 추측했어요»가 그런 경우예요. 꼭 막아야 하는 일은 훅으로 만들어야 하고, 이 운영이 훅으로 막는 것들은 Claude Code 훅 글에 있어요.

따라 할 때

저장소에 docs/경로대장.md 를 만들고, 운영자가 알려 준 경로·계정·값을 칸별로 적어요. 비밀번호·토큰 같은 비밀값은 적지 않아요.
docs/작업일지/ 폴더를 만들고, 압축될 때와 일이 끝날 때 그날 파일에 덧붙여요. 운영자 말은 원문 그대로 옮겨요.
CLAUDE.md 맨 위에 «일을 시작하기 전에 경로대장, 최근 작업일지 순으로 읽는다»를 적어요.
경로대장에 «적힌 값이 안 맞아 보이면 묻는다, 적혀 있는데 또 묻지는 않는다»를 함께 적어요.
값이 바뀌면 경로대장을 그 자리에서 고치고, 옛 메모는 지워요.

확인하지 못한 것

경로대장 덕분에 다시 묻지 않은 횟수. 그런 집계는 남아 있지 않아요.
운영자가 «저번에 한번 얘기했었는데»라고 한 그 앞 대화의 원문

근거

Claude Code 공식 문서, How Claude remembers your project · 2026-10-10 확인. 압축 뒤 대화에서만 준 지시는 사라질 수 있다는 문장, 메모리를 맥락으로만 다룬다는 문장.
운영자의 안경원 홈페이지 저장소 · 2026-10-10 열어 확인. 9월 8일 경로대장·작업일지를 만든 커밋(운영자 말, 단서 조항, 옛 메모 사례), 9월 9일 작업일지(«추측으로 말했다»), 9월 11일 경로대장 표기 정정 커밋.
다른 저장소들의 경로대장 첫 커밋 시각, 개인 설정 파일의 작업 시작 전 읽는 순서.

이 글을 만든 방법

바탕운영자가 실제로 돌린 작업의 기록(작업 일지·설정 파일·오류 기록)
쓴 쪽AI(Claude)가 썼어요
독립 검수2026-10-10에 쓴 AI와 다른 AI가 원본과 대조해 통과시켰어요
사실 확인2026-10-10

발행 2026-10-10