Claude Code 사용 시 같은 주의사항을 반복하지 않기 위해 설정을 6가지 스코프로 분리했습니다

Claude Code에 같은 주의사항을 세 번이나 반복한 적이 없으신가요?

"커밋은 아직 하지 마세요", "그 명령어는 PowerShell에서는 작동 안 해요", "테스트를 고치는 게 아니라 구현을 고치세요".

개인 개발용 일본 주식 검증 시스템을 Claude Code와 함께 만들어 오면서, 처음 몇 주는 정말 이 상태였습니다.

지금은 같은 주의사항을 반복하는 일이 거의 없어졌습니다. 모델이 똑똑해져서가 아니라, 주의사항을 '어디에 적을지'를 결정하고 재배치했기 때문입니다.

※본 기사는 note의 유료 아티클 "Claude Code를 '동반자(相棒)'로 만드는 하네스 설계도"의 사고방식 부분을 엔지니어용으로 정리한 것입니다. 각 스코프에 대한 자세한 작성 방법과 배포 템플릿은 note 버전에서 다루고 있습니다.

6가지 스코프 요약표

Claude Code의 설정은 배치하는 위치에 따라 효력 범위가 달라집니다. 저는 다음 6가지로 분리했습니다.

| 스코프 | 배치 위치 | 작성 내용 | git 관리 | :--- |
| 사용자 (User) | ~/.claude/CLAUDE.md | 언어, 자율성의 경계, Git의 관례 | 안 함 |
| 분야별 규칙 (Domain Rule) | ~/.claude/rules/common/*.md 등 | 코딩, 테스트, 보안, Git의 작법 | 안 함 | :--- |
| 프로젝트 (Project) | <repo>/CLAUDE.md （+ AGENTS.md ） | 아키텍처, 도메인의 규칙, 시작 및 검증 절차 | 함 | :--- |
| 스킬/서브 에이전트 (Skill/Sub-agent) | .claude/skills/ .claude/agents/ | 반복 작업의 절차서, 독립적인 리뷰 역할 | 함 | :--- |
| 로컬 메모리 (Local Memory) | CLAUDE.local.md, 오토 메모리 | 자신의 환경만의 사정, 지적 사항의 기억 | 안 함 | :--- |
| 훅/플러그인 (Hook/Plugin) | settings.json의 hooks | 깨지면 곤란한 규칙의 강제성 | 위치에 따라 다름 |

왼쪽이 모든 프로젝트 공통, 오른쪽이 이 리포지토리만 해당합니다. 구체적인 것이 우선됩니다.

분리하는 요령은 단 하나입니다. 같은 것을 두 곳에 쓰지 않는 것입니다.

"어떤 리포지토리에서도 변하지 않는 것"은 사용자 스코프로, "이 리포지토리만의 사정"은 프로젝트 스코프로 합니다. 이것만 지켜도 CLAUDE.md의 비대화는 상당히 막을 수 있었습니다.

가장 효과적이었던 항목: 자율성의 경계 설정

사용자 스코프의 CLAUDE.md에서 가장 효과가 좋았던 것은, "조심하세요"가 아니라 동작명으로 경계를 그은 것입니다. 실제로 사용하고 있는 기술을 개인적인 부분을 제외하고 발췌했습니다.

## 자율 작동 방침
- **되돌릴 수 있는 리포지토리 내 작업은 확인 없이 진행해도 좋습니다**:
코드 편집, 테스트 작성 및 실행, 린터/타입 체크, 로컬 검증, 조사 등.
...

되돌릴 수 있는 작업은 AI에게 맡기고, 되돌릴 수 없는 조작은 인간이 결정합니다.

마지막 한 줄이 은근히 효과가 좋습니다. 이것이 없으면 "아까 커밋해도 된다고 했으니까 push도 했습니다" 같은 상황이 발생할 수 있습니다.

'부탁' → '절차' → '시스템' 순으로 격상시키기

CLAUDE.md에 적은 규칙은 '부탁'입니다. 대부분 지켜지지만, 긴 작업 도중에 빠질 때가 있습니다. 저는 다음 순서로 격상시키고 있습니다.

• 먼저 CLAUDE.md에 한 줄 작성 (날짜와 이유를 첨부)
• 그래도 두 번 위반되면, 스킬의 '엄수'란에 넣기
• 그래도 위반되면, 훅(Hook)으로 막기

처음부터 훅으로 고정하면, 정당한 예외까지 막아버립니다. 부탁으로 충분한 것은 부탁으로 남겨둡니다.

--no-verify를 막는 훅 (Hook)

예: 훅은 settings.json에 적는 "도구 실행 전후에 반드시 돌아가는 처리"입니다. PreToolUse의 훅이 종료 코드 2로 끝나면, 도구 실행은 멈추고 표준 에러 메시지가 Claude에게 전달됩니다.

// git의 --no-verify를 막는다. 훅이 실패하면 건너뛰지 않고 원인을 고치게 하기 위해서.
let raw = '';
process.stdin.on('data', (c) => (raw += c));
...

{
"hooks": {
"PreToolUse": [
...

종료 코드 0이면 통과, 2면 멈추고 이유를 Claude에게 반환합니다.

에러 메시지에 '대신 어떻게 해줬으면 좋겠다'까지 적어두면, Claude는 그것을 읽고 방법을 바꿔줍니다.

note 버전에서 다루는 내용

여기까지가 사고방식의 뼈대입니다. note 유료 기사에서는 다음 내용을 스코프별로 설명하고 있습니다.

• 6가지 스코프 각각에 대한 '쓸 것/쓰지 않을 것'과 실제와 유사한 작성 예시
• CLAUDE.md를 키워나가는 운영 규칙(사고 1건당 1줄, 날짜 포함)
• 스킬을 '단일 정보원 표 + 엄수 + 절차 + 실패 기록'으로 쓰는 형식
• 작성자 본인과는 다른 시각으로 검토하게 하는 서브 에이전트 설정
• 메모리에 '이유'를 적게 하여, 오래된 기억을 올바르게 버리게 하는 방법
• 바로 사용할 수 있는 3가지 후크(
  --no-verify
  의 금지, .env
  의 보호, 편집 시 자동 정형) - 제로에서 1주일 만에 적용하는 순서와 동작 확인
• 배포 템플릿 일체(일본어 Markdown 13개 파일, 위치 목록 포함)

하네스는 처음부터 설계해서 만든 것이 아니었습니다. 같은 주의사항을 반복할 때마다, 그것을 어느 스코프에 두어야 할지 생각하며 한 줄씩 추가한 결과입니다.

'우리 회사에서는 이렇게 배치하고 있다'는 노하우가 있다면 댓글로 알려주세요.

Discussion