claude.md 작성법

핵심 내용

너무 많은 내용이 있기 때문이다. 실수할 때마다 규칙을 추가하게 되면 내용이 늘어나고, 이게 오히려 성능을 떨어뜨리게 된다.

입력이 길어질수록 모델 정확도가 떨어지는 현상이다. NoLiMa 연구에서 18개 최신 모델 전부 예외 없이 이 경향을 보였습니다.

Lost-in-the-middle 친구 20명 이름을 한번에 들려주고 나중에 물어보면, 대부분 처음 과 마지막 몇명만 기억한다. 중간에 있던 이름들은 잘 기억하지 못한다. 사람도 그렇지만 AI도 마찬가지다. CLAUDE.md가 500줄이라면, 맨 위 규칙과 맨 아래 규칙은 잘 지켜지는데 250번째 줄에 적어둔 “IMPORTANT: 절대 이렇게 하지 마”는 조용히 무시된다.
Attention 분산 AI가 다음 단어를 만들 때, 앞의 모든 내용에 중요도 점수를 나눠준다. 이 점수의 총합이 정해져 있어서, 나눠 줄 대상이 많아질수록 하나하나가 받는 몫이 작아진다.

형광펜으로 비유하자면, 한 페이지에 세문장만 칠하면 그 세 문장이 확 눈에 띈다. 그런데 페이지 전체를 다 칠해버리면 정작 중요한 문장도 배경에 묻혀버린다.

위치 인코딩 한계 AI에게 글은 사실 단어 덩어리일 뿐 아니라, “몇 번째 단어인가” 를 따로 표시해서 알려줘야한다. 이 표시 방식을 위치 인코딩이라 한다.

문제는 이 표시를 배울 때 주로 짧은 글로 연습했다는 것이다. 30cm 자로만 재는 연습만 하다가 갑자기 100m로 재라고 하면, 앞쪾은 정확한데 뒤로 갈수록 눈금이 뭉개져서 “대충 저 근처” 수준이 된다. 긴 문맥에서 엉뚱한 곳을 가리키게 된다.

컨텍스트 창에 치우대, 파일에 기록해두는 방식 나중에 필요하면 다시 꺼내오면 된다. ex) decisions.md에 “왜 이 방식을 택했는지” 기록 progress.md에 진행 상황 남기기

지금 쓸 것만 가져오는 방식 RAG가 대표적인 예이다. 문서 전체를 넣는 대신 질문과 관련된 조각만 검색해서 넣는다.

Claude Code ex)

내용을 줄여서 그대로 컨텍스트창에 두는 방식 /compact가 이것에 해당 압축 반복하면 요약의 요약이 쌓이면서 원본과 점점 멀어진다. 글이 압축보다 새 세션을 권한 이유다.

한 작업대에 다 올리는 대신, 다른 사람에게 별도 작업대를 주고 결과만 받는 방식입니다. 서브에이전트가 여기 해당합니다.

서브에이전트가 자기만의 컨텍스트에서 파일 수십 개를 뒤져도, 메인에는 정제된 1,000~2,000 토큰 요약본만 올라옵니다. 메인 컨텍스트는 계속 깨끗하게 유지되죠.

대가는 총 토큰 비용입니다. 에이전트마다 시스템 프롬프트가 따로 들어가므로, 역할이 겹치는 에이전트를 잔뜩 만들면 오히려 낭비가 됩니다.

안드레 카파시가 AI 코딩에 대해 관찰한 내용 “AI가 만드는 오류는 구문 오류가 아니라 개념적 오류이고, 성급하고 부주의한 주니어 개발자가 저지르는 종류의 실수다.”

이걸 누군가가 Claude Code가 실제로 읽을 수 있는 형태의 지침으로 옮긴 것에 불과하다.