728x90
반응형
본 글은 CLAUDE + GPT와 함께 작성한 글임을 밝힙니다.
CLAUDE-CODE에서 왜 자꾸 너는 CLAUDE.md에 있는 내용을 까먹는거야? 와 같은 내용으로 질문을 하였을때 알려준 내용을 토대로 나온 글입니다.
CLAUDE.md의 내용을 자꾸 까먹는다니까요.
반복된 실패 사례
- 사용자 요청: "PR 머지해"
- 기대 동작: 문서 4개 자동 업데이트 (status.md, tasks.md, README.md, dev-notes/)
- 실제 동작: PR만 머지 → 문서 업데이트 누락
- 결과: 상태 불일치, 뒤늦게 수동 작업
비즈니스 임팩트
- 자동화 도입 효과 상실 → 수동 부담 증가
- 프로젝트 문서와 실제 상태 불일치
- 인지 부하 증가 → 개발자 경험(DevEx) 악화
- 규칙 준수율 저하 → 품질 저하
원인 분석
1. 과도한 정보량
- 기존 CLAUDE.md: 약 1,000줄, 6개 대섹션 + 수많은 규칙 혼재
- 정보 과잉으로 실시간 의사결정 불가
2. 우선순위 불명확
- 실행 규칙과 참고 정보가 동일한 위상으로 배치
- Critical 규칙(예: PR 머지)이 묻혀 있음
3. 인지 부하
- 매번 문서를 스캔해야 함
- 키워드 기반 빠른 접근 불가
4. 실행 vs 참조 혼재
- 명령어 키워드와 관련 액션 매핑 불투명
- 문서 업데이트 절차가 여러 군데에 흩어져 있음
해결책: 3-Tier 문서 아키텍처
철학
Just-In-Time Information Access
→ 필요한 순간, 필요한 정보만. 나머지는 계층적으로 뒤로 배치.
구조
- Tier 1: CLAUDE.md (허브)
- 사용자 요청별 즉시 실행 규칙 테이블
- 핵심 참조 문서 링크
- SuperClaude 프레임워크 요약
- 길이: 100줄 내외
- Tier 2: 실행 가이드 문서
- AUTO-DOC-UPDATE.md: PR 머지 후 자동화 절차 상세
- GIT-WORKFLOW-RULES.md: Git 전략 및 워크플로우 규칙
- MAGIC-UI-GUIDE.md: UI 컴포넌트 생성 규칙
- Tier 3: 참고 문서
- A4LAB-DESIGN-PRINCIPLES.md: 설계 철학과 아키텍처 패턴
- PROJECT-CONTEXT.md: 비즈니스 맥락, 기술 스택 설명
- SuperClaude 프레임워크 전역 설정 (~/.claude)
키워드 매핑 예시
| 키워드 | 즉시 액션 | 참조 |
|---|---|---|
| "PR 머지해" | 4개 문서 자동 업데이트 | AUTO-DOC-UPDATE.md |
| "UI 만들어" | 컴포넌트 생성 절차 실행 | MAGIC-UI-GUIDE.md |
벤치마킹: 외부 유사 사례
- Stripe API 문서
- Quick Start와 API Reference 분리
- 초심자와 숙련자를 동시에 만족시키는 구조
- VS Code 확장 문서
- 개요 → 가이드 → API로 계층화
- Progressive Disclosure 적용 사례
- AWS 문서
- Getting Started와 Deep Dive 이원화
- 온보딩과 심화 학습을 분리해 정보 과부하를 방지
기대 효과
즉시 효과 (도입 직후)
- 문서 길이 100줄 이하 달성
- 핵심 규칙 테이블화
- 참조 문서 4개 이상 분리 완료
결론
- CLAUDE.md 개편은 단순한 문서 구조 조정이 아님
- 개발자 경험(DevEx) 개선 프로젝트이며, 인지 부하를 줄이고 규칙 준수율을 높이는 전략적 투자
- Stripe, VS Code, AWS 사례와 같은 정보 설계(Information Architecture) 원칙을 실무에 적용한 사례
조금 가벼워진 글은 velog에 올라갑니다.
728x90
반응형
'바이브코딩일지' 카테고리의 다른 글
| CLAUDE-CODE의 토큰을 절약하기 - tasks.md의 문서 구조 개편 (0) | 2025.08.27 |
|---|
