CLAUDE.md를 쓰기 시작했을 무렵, 저는 떠오르는 것들을 닥치는 대로 추가하곤 했습니다. 규약도, 주의점도, 과거에 저질렀던 실수도 전부 다 말이죠. 내용이 길면 길수록 더 똑똑하게 움직여 줄 것이라고 생각했기 때문입니다.

결과는 정반대였습니다. 길어질수록 작성했던 규칙들이 제대로 작동하지 않게 되었습니다. 게다가 한 번 삭제했던 오래된 방침이 나중에 다시 살아나기도 했습니다. 이 두 가지 문제로 1년 동안 고생한 끝에 지금의 형태로 정착되었습니다.

깎아내고, 더하고, 다시 깎아내며 남은 것들을 그대로 템플릿으로 남겨둡니다. 복사해서 프로젝트에 맞게 내용을 교체하여 사용해 주세요.

# 프로젝트 개요
- 무엇을 만들고 있는가 (1~2줄)
- 기술 스택 (언어 / 프레임워크 / 버전)
...

이하, 각각의 섹션에 대해 왜 이런 형태가 되었는지 기술하겠습니다.

가장 효과적이었던 것이 이 섹션입니다. 다른 템플릿에서는 잘 보이지 않을 것이라 생각되어 가장 먼저 적습니다.

방침을 바꿀 때 보통은 오래된 기술을 삭제합니다. 저도 그렇게 해왔습니다. 하지만 삭제하면 수중에서는 사라지지만, 동작(Behavior) 측면에는 남아 있는 경우가 있습니다. 시간이 흐른 뒤, "전에는 이렇게 했었죠"라며 폐지했을 터인 방식이 되돌아오곤 합니다.

그래서 삭제하는 대신, 폐지했다는 사실을 기록하도록 했습니다. 취소선을 긋고 이유를 덧붙여, "이것이 나오면 오래된 지시입니다"라고 명시해 두는 것입니다. 이렇게 해두면 오래된 것이 다시 떠올랐을 때, 그것을 부정할 근거가 문서 쪽에 계속 남아 있게 됩니다.

새로운 방침을 추가할 때도 그냥 묵묵히 추가하지 않습니다.

❌ "이 처리는 B 방식으로 부탁드립니다"라고만 추가
✅ "이전에는 A 방식으로 했었으나, (이유) 때문에 폐지했습니다. 
앞으로는 B를 사용해 주세요. A가 나온다면 그것은 오래된 지시입니다."

덮어쓰려고 했는데 사실은 추가(Append)가 되어 있었다. 그렇게 인식하게 된 이후부터 이 방식으로 바꾸었습니다. 겉보기에는 작성 방식의 묘지 같아서 깔끔해 보이지는 않습니다. 하지만 되돌아가는 현상은 눈에 띄게 줄었습니다.

금지 사항은 이유를 적어야 더 잘 지켜집니다.

❌ - eval()을 사용하지 말 것
✅ - eval()을 사용하지 말 것 (외부 입력이 섞이면 임의 코드 실행(Arbitrary Code Execution)이 될 수 있기 때문)

이유가 없으면 상황이 조금 변했을 때 예외 처리로 인해 깨지는 경우가 있습니다. 이유가 있으면 그 이유에 해당하는지 여부로 판단해 줍니다. 금지 목록이라기보다 판단 기준을 전달한다는 느낌에 가깝습니다.

추상적인 지시는 추상적으로만 작동했습니다.

❌ - 읽기 좋은 코드를 작성해 주세요
✅ - 함수는 20행 이내, 중첩(Nest)은 2단계까지

"읽기 쉽게", "적절하게", "깔끔하게"는 우리가 생각하는 기준과 돌아오는 결과물이 좀처럼 일치하지 않습니다. 행 수, 단계 수, 명명 규칙(Naming Convention). 기계적으로 판정할 수 있는 형태로 만들면 편차가 줄어들었습니다.

마지막으로 가장 기본적인 것입니다.

저는 한때 CLAUDE.md를 비대하게 만들었다가 큰 코를 다친 적이 있습니다. 이것저것 다 적은 결과, 가장 지켜주길 바랐던 규칙이 수많은 다른 내용 속에 파묻혀 버렸습니다. 긴 문서 안에서는 하나하나의 기술이 가진 존재감이 옅어집니다.

지금은 쓸 때마다 "이것이 정말 매번 필요한가"를 생각하도록 하고 있습니다. 특정 작업에서만 필요한 지시는 CLAUDE.md에 상주시키지 않고, 그때그때의 요청문(Prompt)으로 전달합니다. 상주시키는 것은 프로젝트 내내 변하지 않는 것뿐입니다. 이 선을 긋고 나서 작성한 규칙이 먹히는 확률이 높아졌습니다.

• 「폐지된 방침」을 섹션으로 남긴다. 삭제하지 않고 취소선 + 이유 + "오래된 지시입니다"를 명기
• 신규 방침은 오래된 방침을 직접 지목하여 부정하며 전달한다. 그냥 추가하면 오래된 쪽이 이길 때가 있다
• 금지 사항에는 이유를 한 줄 적는다. 판단 기준으로 전달하면 더 잘 지켜진다
• "읽기 좋게"보다 "20행 이내". 기계적으로 판정할 수 있는 형태로 만든다
• 상주시키는 것은 프로젝트 내내 변하지 않는 것뿐. 그때그때의 지시는 요청문으로
• 길어질수록 개별 기술의 존재감은 옅어진다

이 템플릿은 1년에 걸쳐 더하고 깎아낸 결과물인 지금의 형태입니다. 프로젝트에 따라 필요한 것은 다르므로, 그대로 사용하기보다는 깎아내기 위한 출발점으로 사용하시는 것이 좋다고 생각합니다. 도움이 되었다면 저장해 두었다가 새로운 프로젝트를 시작할 때 다시 확인해 보세요.

평소에는 raplsworks.com에서 WordPress 플러그인 개발이나 Claude Code 관련 내용을 쓰고 있습니다.