AI 코딩 도구에 규칙을 적어두는 파일이 있습니다. Claude Code 는 CLAUDE.md, 다른 도구들도 비슷한 이름의 파일을 씁니다. 이 파일들의 공통점이 하나 있는데, 없어도 아무 일이 안 일어난다는 것입니다.
오늘 저희 저장소를 그 관점으로 훑어봤고, 생각보다 많이 새고 있었습니다.
지시 파일은 실패할 때 소리를 내지 않는다
CLAUDE.md 같은 지시 파일이 다른 설정 파일과 결정적으로 다른 지점이 여기입니다. 코드에서 import 가 깨지면 프로그램이 멈춥니다. 설정 파일이 없으면 대개 에러가 납니다.
지시 파일은 다릅니다. 없으면 모델이 그냥 안 읽습니다. 그러고는 평소처럼 답을 합니다.
이게 왜 문제냐면, 결과물이 아니라 결과물의 품질만 달라지기 때문입니다. 빌드는 성공하고 글은 나오고 커밋도 됩니다. 다만 지키기로 한 규칙 몇 개가 안 지켜져 있습니다. 그리고 그걸 알아채는 시점은 보통 한참 뒤입니다.
CLAUDE.md 에만 있던 규칙 두 개
저희는 규칙 대부분을 저장소 안 문서에 두고 있었습니다. 블로그 작성 규칙만 1,243줄짜리 문서 하나에 정리돼 있고, 일부는 검사 스크립트로 강제까지 하고 있었습니다.
그래서 다 들어 있는 줄 알았습니다. 확인해보니 두 개가 빠져 있었습니다.
- 본문에 em dash 를 쓰지 않는다
- 한국어 글은 문장마다 줄을 바꾼다
둘 다 홈 디렉토리의 개인 설정 파일에만 있었습니다. 저장소 문서 어디에도 없습니다.
즉 다른 컴퓨터에서 이 저장소를 클론해 글을 쓰면, 1,243줄은 그대로 따라오고 이 두 줄만 사라집니다. 그리고 사라졌다는 신호가 어디에도 안 뜹니다.
없는 파일을 읽으라는 지시
더 인상적인 걸 하나 찾았습니다.
그 개인 설정 파일 안에 이런 내용이 있었습니다. 특정 주제에서는 홈 디렉토리의 다른 문서 두 개를 읽고 판단하라는 지시입니다.
그 두 파일은 존재하지 않습니다. 이 맥에도 없습니다.
언제부터 없었는지는 모릅니다. 지운 적이 없다면 처음부터 안 만들었을 것이고, 어느 쪽이든 그 지시는 지금까지 한 번도 실행된 적이 없습니다.
그동안 에러는 0번 났습니다. 읽으라고 한 파일이 없으면 도구는 그냥 안 읽습니다.
여기서 성질이 분명해집니다. 지시 파일은 fail-open 입니다. 문제가 생기면 멈추는 게 아니라 조용히 통과합니다.
같은 종류의 새는 구멍이 코드에도 있었다
내친김에 저장소 스크립트도 훑었습니다.
$ grep -rl "/Users/내계정" apps packages | grep -v node_modules29개가 나왔습니다. 전부 자격증명 파일 경로를 절대 경로로 박아둔 것이었습니다.
const SA_PATH =
'/Users/내계정/프로젝트/apps/api/firebase-admin-account.json';다른 기기에 클론하면 29개가 전부 죽습니다. 이쪽은 그래도 낫습니다. 파일을 못 찾으면 에러가 나기 때문에, 적어도 뭔가 잘못됐다는 건 압니다.
부끄러운 부분을 적어두면, 그날 제가 새로 만든 분석 스크립트도 같은 실수를 했습니다. 옆 파일의 패턴을 그대로 복사했기 때문입니다. 환경이 코드에 스며드는 방식이 대개 이렇습니다. 누가 처음에 한 번 박아두면, 그 다음부터는 관행이 됩니다.
어디에 무엇을 둘 것인가
정리하면서 기준을 하나 세웠습니다.
개인 설정 파일에 남겨도 되는 것은 나에 대한 규칙입니다. 어떤 말투로 답해달라거나, 커밋에 내 이름을 어떻게 넣어달라거나 하는 것들입니다. 이건 컴퓨터를 바꿔도 나를 따라다니는 게 맞습니다.
저장소로 옮겨야 하는 것은 결과물에 대한 규칙입니다. em dash 를 쓰지 않는다는 것은 저에 대한 규칙이 아니라 이 블로그 글에 대한 규칙입니다. 글이 저장소에 있으니 규칙도 저장소에 있어야 합니다.
두 가지가 한 파일에 섞여 있으면 구분이 안 됩니다. 그래서 프로젝트 규칙이 개인 파일 쪽으로 흘러 들어가고, 그 순간부터 다른 사람과 다른 기기에서는 없는 규칙이 됩니다.
문서로 옮기는 것으로는 부족하다
옮기고 나서 한 가지를 더 했습니다.
em dash 규칙은 검사 스크립트에 넣었습니다.
const prose = body.replace(/```[\s\S]*?```/g, '');
const em = (prose.match(/ - /g) ?? []).length;
return em === 0 ? OK('em dash 없음') : NO('em dash 없음', `${em}개`);이유는 단순합니다. 문서는 사람이 안 읽습니다. 게이트는 안 읽어도 못 지나갑니다.
넣기 전에 기존 글 12편을 먼저 재봤습니다. 전부 이미 0개였습니다. 그래서 게이트를 걸어도 기존 글이 안 깨집니다. 그리고 일부러 하나 넣어서 실제로 걸리는지도 확인했습니다. 통과만 보면 검사가 도는지 알 수 없습니다.
반면 문장마다 줄바꿈은 게이트로 만들지 않았습니다. 영문 글을 재보니 한 줄에 여러 문장인 줄이 16개에서 25개씩 나왔는데, 영어 산문은 원래 그렇게 씁니다. 양쪽에 똑같이 걸었으면 영문 글이 전부 걸렸을 것입니다. 기계로 판정할 수 있느냐와 판정해야 하느냐는 다른 질문입니다.
여기서부터는 의견입니다
위까지는 잰 것이고, 아래는 제 생각입니다.
AI 코딩 도구의 기억 기능이 편한 방향으로 발전하고 있는데, 저는 그게 조금 불편합니다. 편하다는 것은 내 컴퓨터에 쌓인다는 뜻이고, 쌓인 것이 많을수록 그 컴퓨터가 아니면 결과가 달라집니다.
무서운 건 그 차이가 티가 안 난다는 점입니다. 빌드가 깨지면 고치면 됩니다. 글의 규칙 두 개가 조용히 빠진 상태는 몇 달을 갑니다.
그래서 저는 이 질문을 기준으로 삼기로 했습니다. 지금 이 저장소를 처음 보는 컴퓨터에 클론하면, 같은 결과가 나오는가. 아니라면 차이 나는 부분이 곧 이 컴퓨터에 갇혀 있는 지식입니다.
개인 설정 파일 자체가 나쁘다는 말은 아닙니다. 경계가 없다는 게 문제입니다. 도구가 규칙을 적으라고만 하고 이게 나에 대한 것인지 프로젝트에 대한 것인지 묻지 않으니, 섞이는 게 기본값이 됩니다.
공식 문서도 메모리 를 프로젝트용과 개인용으로 나눠 설명하고 있습니다. 구분하는 자리는 이미 있습니다. 다만 지키는 건 사람 몫이고, 안 지켜도 아무 일이 안 일어납니다.
2026년 8월 11일에 Claude Code 2.1.224, Node 24.2.0 에서 확인했습니다. 도구가 지시 파일을 어디서 읽는지는 버전에 따라 바뀔 수 있으니, 옮기기 전에 본인 환경에서 한 번 확인하시길 권합니다.