본 글은 CLAUDE + GPT와 함께 작성한 글임을 밝힙니다.
CLAUDE-CODE에서 왜 자꾸 너는 CLAUDE.md에 있는 내용을 까먹는거야? 와 같은 내용으로 질문을 하였을때 알려준 내용을 토대로 나온 글입니다.
CLAUDE.md 문서 개편기 – 가볍게 풀어본 경험담
요즘 Claude Code 쓰면서 제일 많이 부딪힌 문제가 있다.
규칙은 잔뜩 있는데 정작 실행할 땐 기억이 안 난다고 한다
그 결과, PR은 머지했는데 문서 업데이트는 빼먹고, 다시 뒤늦게 프롬프트에 수동으로 챙기는 일들이 반복되었다.
왜 이런 일이 발생하였는가?
- 문서가 너무 길다 → 내가 이것 저것 자동화 시켜달라고, "해줘" 등을 하다 보니 CLAUDE.md가 거의 천 줄에 가까워 지기 시작
- 중요한 규칙이 묻혀 있다 → 진짜 급한 "PR 머지 후 자동 업데이트" 같은 규칙이 중간 어딘가에 숨어 있다.
- 실행할 내용이랑 참고용 설명이 뒤섞여 있다 → 순간에 필요한 걸 바로 찾기 어렵다.
결국 문서가 많을수록 CLAUDE CODE의 머릿속은 더 복잡해지는 상황이 벌어졌다.
어떻게 바꿨나?
“필요할 때 필요한 정보만 딱 보자!”라는 철학으로 3단계 구조를 만들었다.
1단계: CLAUDE.md (메인 허브)
- 사용자 요청별 즉시 실행 규칙 테이블
- 핵심 문서 바로 가기 링크
- 빠른 시작 가이드
→ 길이는 1/10 수준으로 줄여서, 이제 100줄 안쪽!
예:
| 요청 | 바로 실행할 것 | 참고 문서 |
|---|---|---|
| "PR 머지해" | 문서 4개 자동 업데이트 | @AUTO-DOC-UPDATE.md |
2단계: 실행 가이드 문서들
- AUTO-DOC-UPDATE.md → 머지 후 문서 자동화 절차
- GIT-WORKFLOW-RULES.md → Git 규칙 모음
- MAGIC-UI-GUIDE.md → UI 컴포넌트 작성법
3단계: 참고용 문서들
- 설계 원칙, 프로젝트 맥락, 전역 설정 같은 심화 자료들
👉 허브에서는 "뭘 해야 하지?"만 보고, 더 자세한 건 다른 문서에서 찾아보는 식이다.
다른 사례랑 비교해보니
이 구조, 사실 낯설지 않다.
- Stripe API 문서: Quick Start + API Reference
- VS Code 문서: 개요/가이드/레퍼런스
- AWS 문서: Getting Started + Deep Dive
결국 다들 "빠르게 시작할 것 vs 깊게 파고들 것"을 나눠 두기도 했고 나도 그 방식을 따라간 셈이다.
효과는?
- 문서 길이는 확 줄었고 🚀
- 규칙 누락 사례는 0건으로 감소 ✨
- 필요한 정보 찾는 시간은 5초 이내 ⏱️
마무리
이번 개편으로 느낀 건, 문서도 UX다라는 점이다.
물론 이게 절대적으로 완벽하다, 확실하게 고쳐준다는 아니다. 하지만 확실히 나에게 효과는 좋았다.
사용할 때 딱 필요한 게 보이도록 만드는 게 핵심이다.
tistory에 올라가는 글과는 아주 약간 차이가 있습니다.
https://developer-youn.tistory.com/195
