CLAUDE.md

문제

CLAUDE.md에 무엇을 적어야 할지 몰라 “깨끗한 코드를 작성한다” 같은 일반론으로 칸을 채웁니다.

추천

조건 없는 원칙 대신 “언제 실행하고 언제 실행하지 않는지”까지 못박은 문구만 적습니다. 왜 그래야 하는지는 CLAUDE.md 실전 가이드에 있으므로 여기서는 그대로 붙여 쓸 수 있는 형태만 남깁니다.

예시

조건부 스킬 참조

스킬 이름과 조건만 자기 것으로 바꾸면 되는 형태입니다.

걸리지 않는다

낯선 라이브러리나 API를 만나면 내부 문서를 참고한다.

걸린다

아래 상황에서 `internal-docs-lookup` 스킬을 실행한다:
- 도구·빌드·테스트 오류가 발생했을 때
- 라이브러리·설정·API가 낯설거나 버전별 동작이 불확실할 때
- 사용자가 `/internal-docs-lookup`을 명시적으로 요청했을 때

에러도 낯선 기술도 없는 일반 작업에는 검색하지 않는다.

바뀐 것은 두 가지입니다. 조건을 목록으로 못박았고, “실행하지 않는 경우”를 명시했습니다. 실행하지 않는 경우를 적어 두면 매 프롬프트마다 검색을 시도하는 낭비를 막습니다.

도구 선택 규칙

기본 도구 하나를 정하고, 예외 조건을 나열하고, 애매하면 멈추게 하는 형태입니다.

브라우저 자동화 도구가 두 가지 등록되어 있다. 기본은 <도구 A>다.
사용자의 로그인 세션·쿠키·SaaS 계정을 그대로 쓰는 작업은 전부 <도구 A>로 한다.

아래에 해당할 때만 <도구 B>를 쓴다:
- 프롬프트에 `$도구B`가 있을 때
- 영상 녹화가 필요할 때 (<도구 A>에는 녹화 경로가 없다)
- trace·codegen·디바이스 에뮬레이션이 필요할 때
- 격리된 프로필이 필요할 때

어느 쪽인지 애매하면 임의로 고르지 말고 먼저 물어본다.

바꿀 것은 도구 이름 두 개와 예외 조건 목록입니다. “애매하면 먼저 물어본다” 줄은 지우지 않습니다. 이 줄이 없으면 경계 사례에서 조용히 기본값으로 진행합니다.

$도구B 같은 자연어 트리거는 제안이지 강제가 아닙니다. 산문으로 적어 둔 조건은 아무리 구체적이어도 잊히기 쉽습니다. 반드시 지켜야 하는 규칙이면 훅으로 옮깁니다.

이유

전역 CLAUDE.md에는 참조만 두고 본문은 스킬로 내리는 편이 낫습니다. 스킬은 description만 상시 노출되고 본문은 호출될 때만 로드됩니다. 그래서 일반 작업의 컨텍스트 비용이 작습니다. 조건 없는 원칙이 걸리지 않는 이유는 CLAUDE.md 실전 가이드에서 다룹니다.

하지 말 것

조건 없이 원칙만 나열하기. “코드는 깨끗하게, 테스트는 꼼꼼하게” 같은 문구는 모델이 이미 아는 말이라 아무것도 걸리지 않습니다.

특정 모델명을 못박기. “이 모델을 써라” 같은 문구는 모델이 바뀔 때마다 CLAUDE.md를 같이 고쳐야 합니다. 모델은 런타임에 바꾸는 값으로 다루는 편이 낫습니다.

“항상 검색해라”로 조건을 생략하기. 에러도 낯선 기술도 없는 일반 작업에서까지 검색을 시도하면 컨텍스트를 낭비합니다. 실행하지 않는 조건까지 같이 적습니다.