CLAUDE.md에 이 한 문장을 안 넣으면 같은 실수를 계속 반복하게 된다

Claude Code 창시자가 공개한 CLAUDE.md 지속 투자법과 Skill 만들기

핵심 요약

• Claude Code 창시자 Boris Cherny는 매번 수정할 때마다 "CLAUDE.md를 업데이트해서 같은 실수를 반복하지 않도록 해라"라고 지시한다고 공개했다. (출처: Boris Cherny X, 2026.02)
• Claude는 스스로 지켜야 할 규칙을 매우 잘 문서화하는 특성이 있어, 이 한 문장만으로도 효과적인 자기 개선이 이뤄진다.
• 한 엔지니어는 모든 작업·프로젝트에 대해 notes 디렉토리를 유지하고 PR마다 업데이트하도록 지시한 뒤, CLAUDE.md가 이를 참조하도록 설정했다.
• 하루에 한 번 이상 반복하는 작업은 Skill 또는 Slash Command로 만들어 git에 커밋하는 것이 클로드 코드 팀의 표준 습관이다.

---

목차

1. 문제 제기 — Claude Code가 비슷한 실수를 반복한다면
2. 단 한 문장으로 시작하는 CLAUDE.md 업데이트
3. Claude가 스스로 규칙을 문서화하는 이유
4. notes 디렉토리와 CLAUDE.md 연동 구조
5. 반복 작업을 Skill로 git에 커밋하기
6. 마치며

---

1. 문제 제기 — Claude Code가 비슷한 실수를 반복한다면

Claude Code로 작업을 하다 보면 "이거 저번에도 똑같이 틀렸는데"라는 생각이 들 때가 있다.
같은 패턴의 실수가 반복되는 느낌이 든다면,
그 원인은 Claude의 능력 문제가 아니라 CLAUDE.md 관리 방식에 있을 가능성이 크다.

 

2026년 2월 Claude Code 창시자 Boris Cherny가 X에 공개한 실전 사용 팁에는
이 문제를 해결하는 구체적인 방법이 담겨 있다.

핵심은 단 하나의 지시문을 습관적으로 반복하는 것이다.

---

2. 단 한 문장으로 시작하는 CLAUDE.md 업데이트

Boris Cherny가 공개한 방법은 단순하다.
매번 수정할 때마다 다음과 같이 지시하는 것이다.

'CLAUDE.md를 업데이트해서 같은 실수를 반복하지 않도록 해라'

 

실제 사용 시나리오로 풀어보면 다음과 같다.

1. Claude가 코드를 작성하다 실수를 한다
   (예: 잘못된 import 경로 사용)
   
2. 실수를 수정한 직후, 이렇게 지시한다:
   "CLAUDE.md를 업데이트해서 같은 실수를 반복하지 않도록 해라"

3. Claude가 스스로 CLAUDE.md에 규칙을 추가한다:
   "이 프로젝트에서는 항상 절대 경로로 import할 것.
    상대 경로 사용 시 빌드 오류가 발생함."

4. 다음 세션부터 Claude가 이 규칙을 자동으로 참조한다

 

이 한 문장을 실수가 발생할 때마다 반복하는 것이 핵심이다.
한 번에 완벽한 CLAUDE.md를 만들려고 하지 않고,
실수가 생길 때마다 누적해서 보완하는 방식이다.

---

3. Claude가 스스로 규칙을 문서화하는 이유

이 방법이 효과적인 이유에 대해 Boris Cherny는 명확한 관찰을 공유했다.
"Claude는 스스로 지켜야 할 규칙을 매우 잘 문서화하는 특성이 있다"는 것이다.

 

이것이 의미하는 것은, 사람이 직접 CLAUDE.md에 규칙을 일일이 작성하는 것보다
Claude에게 "방금 한 실수를 문서화해라"라고 지시하는 것이 더 정확하고 효율적이라는 점이다.
Claude는 자신이 어떤 맥락에서 어떤 실수를 했는지 가장 잘 알고 있기 때문이다.

방식	효율성
사람이 직접 규칙 작성	실수 패턴을 사람이 먼저 파악해야 함
Claude에게 문서화 지시	Claude가 실수 맥락을 즉시 반영

 

이 과정을 반복하면 어떤 효과가 나타나는지도 공개됐다.
"시간이 지나며 CLAUDE.md를 지속적으로 수정하고, Claude의 실수율이 측정 가능하게 줄어들 때까지 반복한다"는 것이다.

즉 이것은 일회성 설정이 아니라 지속적인 투자가 필요한 습관이다.

 

실수 발생부터 CLAUDE.md 반영까지의 반복 사이클

---

4. notes 디렉토리와 CLAUDE.md 연동 구조

CLAUDE.md를 더 체계적으로 운영하는 고급 사례도 공개됐다.

한 엔지니어는 모든 작업·프로젝트에 대해

• notes 디렉토리를 유지하고
• PR마다 업데이트하도록 Claude에 지시하고,
• CLAUDE.md가 이를 참조하도록 설정했다.

이 구조를 정리하면 다음과 같다.

project/
├── CLAUDE.md              ← 핵심 규칙, notes 참조 지시 포함
└── notes/
    ├── 2026-06-15-feature-x.md   ← PR별 작업 기록
    ├── 2026-06-18-bugfix-y.md
    └── 2026-06-20-refactor-z.md

 

CLAUDE.md에는 이런 식의 참조 지시가 포함된다.

# CLAUDE.md 예시 일부

작업을 시작하기 전 notes/ 디렉토리의 최근 항목들을 확인하라.
과거에 비슷한 작업에서 발생한 이슈와 해결 방법이 기록되어 있다.

각 PR을 완료한 후에는 notes/ 디렉토리에 
날짜-작업명.md 형식으로 요약을 남겨라.

 

이 구조의 장점은 CLAUDE.md 자체가 무한히 길어지지 않으면서도,
과거 작업의 세부 맥락을 보존할 수 있다는 것이다.
핵심 규칙은 CLAUDE.md에, 상세 기록은 notes에 분리하는 방식이다.

---

5. 반복 작업을 Skill로 git에 커밋하기

CLAUDE.md 투자와 함께 공개된 또 다른 핵심 습관은 Skill 만들기다.

클로드 코드 팀의 원칙은 명확하다.
"하루에 한 번 이상 반복하는 작업은 Skill 또는 Slash Command로 만든다."

실제 사례로 공개된 것들이다.

Skill/Command	역할
/techdebt	세션 종료 시 중복 코드를 찾아 제거
컨텍스트 동기화 커맨드	7일치 Slack, GDrive, Asana, GitHub를 하나의 컨텍스트 덤프로 동기화
analytics-engineer 스타일 에이전트	dbt 모델 작성, 코드 리뷰, dev 환경 테스트 수행

 

이렇게 만들어진 Skill은 git에 커밋해서 팀 전체가 공유한다.
CLAUDE.md가 "실수를 막는 규칙"을 누적하는 장치라면,
Skill은 "반복 작업을 자동화"하는 장치라는 점에서 역할이 다르다.

 

두 가지를 함께 운영하는 것이 클로드 코드 팀의 표준 워크플로다.

 

실무 시작 가이드:
오늘부터 적용한다면 가장 쉬운 시작은 이것이다.
Claude Code가 실수를 할 때마다
"CLAUDE.md를 업데이트해서 같은 실수를 반복하지 않도록 해라"라는 문장을 그대로 입력해본다.
일주일만 반복해도 CLAUDE.md가 눈에 띄게 두꺼워지는 것을 확인할 수 있다.

---

FAQ

Q: CLAUDE.md를 업데이트할 때 정확히 어떤 문장을 쓰면 되는가?
A: Boris Cherny가 공개한 문장은 "CLAUDE.md를 업데이트해서 같은 실수를 반복하지 않도록 해라"이다.
이 문장을 실수가 발생한 직후 매번 입력하는 것이 핵심이다.

 

Q: Claude가 스스로 규칙을 문서화하는 것이 왜 더 효과적인가?
A: Claude가 방금 한 실수의 맥락을 가장 정확히 알고 있기 때문이다.
사람이 나중에 규칙을 정리하는 것보다 실수 직후 Claude에게 직접 문서화를 지시하는 것이 더 정확하다.

 

Q: notes 디렉토리와 CLAUDE.md는 어떻게 다르게 운영해야 하는가?
A: CLAUDE.md에는 핵심 규칙만 남기고, PR별 상세 작업 기록은 notes 디렉토리에 분리해서 쌓는다.
CLAUDE.md가 notes 디렉토리를 참조하도록 설정하면 두 가지가 함께 작동한다.

 

Q: CLAUDE.md와 Skill의 차이는 무엇인가?
A: CLAUDE.md는 실수를 막는 규칙을 누적하는 장치이고, Skill은 하루에 한 번 이상 반복하는 작업을 자동화하는 장치다.
클로드 코드 팀은 두 가지를 모두 git에 커밋해 팀 전체와 공유한다.

---

마치며

Claude Code의 실수율을 낮추는 방법은 복잡한 설정이 아니다.
실수가 생길 때마다 "CLAUDE.md를 업데이트해서 같은 실수를 반복하지 않도록 해라"는 한 문장을 반복하는 것이다.

이 습관을 시간을 두고 쌓으면 Claude의 실수율이 측정 가능하게 줄어든다.
여기에 notes 디렉토리 연동과 Skill 만들기까지 더하면,
CLAUDE.md는 단순한 설정 파일이 아니라 팀의 노하우가 누적되는 자산이 된다.

---

참고자료

• Boris Cherny X 원문: https://x.com/bcherny/status/2017742741636321619
• GeekNews: https://news.hada.io/topic?id=26330
• Claude Code 공식 문서(Skills): https://code.claude.com/docs/en/skills#extend-claude-with-skills