검증 가능한 Claude Code용 CLAUDE.md 규칙

긴 희망 목록이 agent를 예측 가능하게 하지는 않습니다. rule은 허용, 금지, 검증 가능한 결과를 말해야 합니다. workflow가 API를 쓴다면 BetterToken Claude Code 최신 가이드를 열어 자신의 API Key를 설정하고 짧은 test를 실행하세요. Dashboard에 예상 model, status, token usage가 나타나는지 확인하고 Key는 CLAUDE.md가 아닌 환경에 둡니다.

작은 계약부터 시작

## Goal
- Keep changes limited to the requested feature.
## Checks
- Run `npm test` after code changes.
## Forbidden
- Do not read, print, or commit `.env`.

“quality code”는 검증할 수 없지만 command와 exit code는 가능합니다.

scope와 계층

현재 Claude Code Memory 문서는 서로 다른 scope의 instructions를 찾는 방식을 설명합니다. 이 예시의 “local package rule은 일반 root rule을 덮을 수 있지만 root security는 무효화하지 않는다”는 project가 작성한 계약이며 Claude Code의 보편적인 내장 예외가 아닙니다. 보이는 rule을 확인하고 duplicate를 제거하세요.

rule 유형 분리

유형	예	증거
goal	profile 읽기	대상 module만 변경
boundary	migration 금지	diff에 없음
check	npm test	exit 0
style	기존 이름	불필요 refactor 없음

긴 설명은 link와 함께 docs/로 옮깁니다.

conflict와 구체 예

편집 전 package.json, task files, local instructions를 읽습니다. 없는 command를 만들지 마세요. 두 rule이 다른 check를 요구하면 검증 가능한 local rule 하나만 남깁니다.

reversible test

test file의 local variable을 rename한 뒤 실행합니다.

git diff --check
git diff --stat
npm test

다른 file이 바뀌거나 check가 빠지면 reject합니다.

secret과 maintenance

API Key, CI token, 개인 data, .env는 CLAUDE.md에 넣지 않습니다. API_KEY=your_api_key_here를 쓰고 실제 값은 environment나 secret store로 전달합니다. test, package, directory 변경 시 계약을 검토하세요.

Sources

• Claude Code memory
• BetterToken Claude Code documentation