10 Essential Claude Code Best Practices You Need to Know
https://discuss.huggingface.co/t/10-essential-claude-code-best-practices-you-need-to-know/174731/1
꼭 알아야 할 Claude Code 베스트 프랙티스 10가지
GitHub Trending 2만 스타 레포 claude-code-best-practice 84개 팁 중 실제 검증된 10개 추림
1. CLAUDE.md 60줄 이하로 유지
처음에 500줄 넣었다가 Claude가 뒷부분 규칙을 무시하는 걸 경험함. Boris Cherny에 따르면 LLM이 신뢰할 수 있게 따르는 지시는 150~200개인데, 시스템 프롬프트가 이미 50개 씀. HumanLayer 팀 기준은 60줄, 하드 리밋은 300줄. Claude가 코드 읽으면 유추할 수 있는 건 넣지 말 것. 규칙이 많으면 .claude/rules/로 분산.
2. 복잡한 작업엔 Plan Mode
Shift+Tab 두 번으로 진입. 이 모드에서 Claude는 계획만 세우고 코드 안 씀. 계획 확인 후 Normal Mode로 전환해서 실행. Anthropic 공식 권장 워크플로: Explore → Plan → Implement → Commit.
3. Claude에게 먼저 인터뷰 받기
간단한 요구사항만 주고 Claude가 AskUserQuestion 툴로 세부사항을 캐묻게 할 것. API 만들 때 "동시 요청 처리는?", "타임아웃 전략은?" 같은 질문이 나와서 스스로 놓쳤던 엣지 케이스를 발견함. 인터뷰 후엔 반드시 새 세션으로 실행 — 길어진 인터뷰 컨텍스트가 실행 품질을 떨어뜨림.
4. 어중간한 솔루션엔 재작성 요구
Boris 팀 최애 팁. 작동은 하지만 우아하지 않은 코드가 나왔을 때 패치하지 말고: "knowing everything you know now, scrap this and implement the elegant solution" 이라고 할 것. 패치한 버전보다 재작성 버전이 항상 더 나음. 검증하고 싶으면 "prove to me this works"라고 하면 Claude가 main 브랜치와 diff해서 확인해줌.
5. 버그는 그냥 붙여넣고 "Fix"
에러 메시지 붙여넣고 "fix" 한 마디. 원인 추측, 해결 방법 지시 금지. 마이크로매니징할수록 오히려 방향을 잘못 잡게 됨. 직접 고치게 두면 성공률 80%+. 두 번 시도해서 안 되면 /clear 하고 다른 각도로 접근. Anthropic도 공식적으로 수정 시도 2번 초과 시 재시작 권장.
6. 프롬프트에 "Use subagents" 추가
이 말만 넣으면 Claude가 작업을 여러 서브에이전트로 분산 병렬 처리함. 코드 리뷰에 9개 서브에이전트를 품질 차원별로 나눠 쓴 사례도 있음. 파일 전체 rename 작업에 3개 병렬 실행으로 속도 대폭 향상 + 메인 컨텍스트 오염 없음. 팁: 서브에이전트는 "QA 에이전트"처럼 범용으로 만들지 말고 "프론트엔드 컴포넌트 에이전트"처럼 기능 특화로 만들 것.
7. Skills는 폴더 구조 + Gotchas 섹션으로
SKILL.md 파일 하나로 끝내지 말고 폴더 구조로:
skill-name/
SKILL.md ← 핵심 규칙 + 인덱스
references/ ← 상세 자료
scripts/
examples/Claude가 필요할 때만 서브디렉토리 읽음 — 한 파일에 다 때려넣는 것보다 훨씬 효율적.
Gotchas 섹션 필수: Claude가 실수할 때마다 실패 패턴 기록. 시간이 지날수록 가장 신호 대 잡음비 높은 콘텐츠가 됨. 저자는 "AI 냄새 나는" 표현 패턴 12개 이상 문서화했더니 초안 품질이 크게 향상됨.
8. 컨텍스트 50%에서 수동 /compact
컨텍스트 60~70% 초과 시 "에이전트 멍청해지는 구간" 진입 — 지시 무시, 기본 코딩 오류 발생. 자동 컴팩션 기다리지 말고 50%에서 수동으로 /compact. /statusline으로 실시간 모니터링. Boris 팀 스크립트는 초록/노랑/빨강으로 색상 코딩.
9. 방향 이탈 시 Esc+Esc로 롤백
같은 컨텍스트 안에서 수정 시도하면 잘못된 추론이 그대로 남아있어서 더 나빠짐. 이탈하면 즉시 Esc+Esc로 이전 체크포인트 롤백. 같은 문제에서 두 번 이탈하면 /clear 하고 재시작.
10. 작은 작업엔 복잡한 워크플로 쓰지 말 것
변수 이름 하나 바꾸는데 Plan → Execute → Review 다 돌리는 건 낭비. Superpowers, Spec Kit, BMAD-METHOD 같은 복잡한 워크플로는 다파일·다단계 대형 작업용. 3~5분짜리 작업은 그냥 한 문장으로 말하는 게 가장 빠름.
원본 레포에 84개 전체 + 주요 워크플로 8종 비교 + Boris Cherny 인터뷰 링크 모음도 있다고 함.
