CLAUDE.md 40줄 설계 — 클로드 코드 제작자의 기준을 코드로 옮긴 과정

설정 파일은 길수록 좋다고 생각했던 시절이 있었습니다. 세 화면 분량까지 갔다가 오히려 규칙이 안 먹히는 걸 보고 방향을 뒤집었는데, 이 글은 그 뒤집힌 설계의 근거를 남기는 기록입니다. AI 도구의 지시 파일을 어떤 기준으로 채울지 결정해야 하는 분을 위한 글입니다.

문제 정의 — 왜 지시가 증발하는가

에이전트는 대화가 시작될 때 컨텍스트 윈도우에 지시 파일을 올립니다. 여기서 두 가지 실패 모드가 갈립니다. 첫째, 파일이 없으면 도구는 사용자의 관례를 추측하거나 질문으로 때웁니다. 둘째, 파일이 비대하면 정작 중요한 지시가 나머지에 희석됩니다. 공식 문서도 파일이 부풀 때 실제 지시를 무시하는 현상을 경고합니다. 그러니까 이 파일의 설계 목표는 정보량 최대화가 아니라 지시 밀도 최대화입니다.

설계 원칙 — 추측 불가능성 테스트

제작자 보리스 셔니가 공개한 운용 팁을 제 상황에 맞게 번역하면, 줄 하나가 파일에 들어올 자격은 하나뿐입니다. 모델이 코드베이스나 상식에서 유추할 수 없는 정보인가. 저장 경로 관례, 명명 규칙, 반복적으로 걸리는 함정이 여기 해당합니다. 반대로 코드만 읽으면 아는 사실, 일반적인 품질 요구는 자격 미달입니다.

심문 루프 — 세 화면이 절반이 되기까지

기존 파일의 각 줄에 같은 질문을 걸었습니다. "이 줄을 삭제하면 실제로 오답이 나오는가." 확신이 없으면 지우고 하루 돌려봤습니다. 오답이 재현되면 복원, 아니면 영구 삭제. 이 루프를 돌리고 나니 분량이 절반 아래로 내려왔고, 남은 줄은 전부 삭제 시 실제 오류가 재현됐던 것들입니다.

흥미로운 건 제작자 본인의 운용입니다. 새 모델이 나올 때마다 프롬프트를 통째로 비우고, 한 줄씩 복원하며 실효를 재확인한다고 합니다. 최근 회차에선 80%가 복귀하지 못했다고 밝혔습니다. 모델이 좋아질수록 지시 파일은 짧아지는 방향이 맞다는 방증입니다.

모호성 제거 — 형용사를 수치로

줄이는 것만으로 해결 안 되는 유형이 하나 남습니다. 존재하는데 안 지켜지는 줄. 진단 기준은 두 갈래입니다. 파일이 길어 묻혔거나, 문구가 모호하거나. 후자의 전형이 형용사 지시입니다.

모호한 지시	판정 가능한 지시	효과
보기 좋게 작성	제목 15자 이내	즉시 준수
깔끔하게 정리	결과는 지정 폴더, 파일명에 날짜	즉시 준수
간결하게	섹션당 3문장 상한	즉시 준수

모델 입장에서 형용사는 판정 함수가 없는 조건문입니다. 수치와 경로로 바꾸는 순간 준수율이 달라지는 게 재현됩니다.

검증 가능성 — 완료 신호를 파일에 심기

에이전트는 그럴듯해 보이는 지점에서 멈추는 경향이 있습니다. 그래서 각 작업 유형에 완료 판정 방법을 지시로 심었습니다. 예를 들어 글 작성 작업엔 분량 집계 보고를, 파일 조작엔 결과 재확인 절차를 요구합니다. 판정 신호가 파일에 있으면 확인 노동이 사용자에게서 에이전트로 이동합니다.

재실행 검증 — 같은 조건, 파일 유무만 다르게

설계가 실제로 작동하는지 통제 실험으로 확인했습니다. 동일 모델, 동일 프로젝트 폴더, 동일 프롬프트, 유일한 변수는 파일 유무.

관측 항목	파일 없음	파일 있음
경로 규칙 준수	위반 (루트 저장)	준수
명명 규칙	위반	준수
완료 검증	생략	수행 + 보고
소요 시간	36.4초	52.2초

시간 증가는 검증 단계의 비용입니다. 설계 의도대로면 이 비용은 사람이 하던 검사의 이전이므로 순손실이 아닙니다.

안전장치 — settings.json의 역할 분리

지시 파일과 별개로 권한 설정을 분리한 이유도 설계 판단입니다. 폴더 삭제류 파괴적 명령은 지시로 금지하는 게 아니라 권한에서 차단해야 합니다. 지시는 확률적으로 지켜지지만 권한은 결정적으로 막히기 때문입니다. 확률적 방어와 결정적 방어를 같은 파일에 섞지 않는 것, 이게 두 파일 체제의 이유입니다.

유지보수 — 파일을 키우는 훅

운영하면서 파일을 직접 편집하는 빈도를 줄이려고 두 개의 트리거 단어를 만들어뒀습니다. 오류를 목격한 순간 채팅에 트리거를 치면 해당 실수의 방지 규칙이 한 줄로 축적되는 방식입니다. 편집 비용이 0에 가까워지니 규칙 축적이 실제로 일어납니다. 다만 축적만 있고 삭제가 없으면 다시 비대해지므로, 심문 루프를 주기적으로 돌리는 걸 전제로 한 설계입니다.

실패담 — 처음 버전이 안 됐던 이유

솔직하게 남기면, 첫 버전은 위 원칙을 하나도 안 지켰습니다. 말투 지침만 열두 줄이었고, 그중 실제로 출력에 영향을 준 건 두 줄이었습니다. 나머지 열 줄은 지면만 차지하며 중요한 지시의 희석재 노릇을 했습니다. 열두 줄을 쓴 시간보다 열 줄을 지울 용기를 내는 데 걸린 시간이 더 길었다는 게 이 작업의 요약입니다.

판단이 필요한 분께

이 설계를 그대로 쓸 필요는 없습니다. 다만 줄 하나를 두고 고민될 때 "삭제하면 오답이 재현되는가"라는 질문 하나는 어디서든 통합니다. 여러분 파일에서 그 질문을 통과 못 할 것 같은 줄, 몇 개나 됩니까?

실측 장면 전체는 영상으로 남겨뒀고, 완성 파일은 방구석모각코 오픈톡에서 배포 중입니다.