본 글은 Claude Code 사용 시, 여러 사내 툴의 규칙을 효율적으로 관리하는 방법을 제시합니다. 모든 리포지토리에 공통적인 작업 규칙은 '사용자 공통'에 작성하고, 해당 툴에서만 의미를 가지는 명령어나 금지 사항은 '리포지토리별'로 분리해야 합니다.
AI 자동 생성 콘텐츠
본 콘텐츠는 Zenn AI의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기이 글을 읽고 얻을 수 있는 것
중소 건설업체에서 사내 DX를 담당하다 보면, 작은 사내 툴들이 조금씩 늘어납니다. 저의 손에도 용도가 다른 리포지토리가 여러 개 있습니다.
리포지토리를 만들 때마다 CLAUDE.md를 처음부터 작성하면 '커밋은 자신이 수정한 파일만 add 한다', '판단 근거는 별도의 장소에 기록한다'와 같은 규칙을 매번 복사하게 됩니다. 이렇게 되면, 한쪽만 수정하고 다른 쪽이 오래된 상태로 남아있는 경우가 발생하기 쉽습니다.
반대로, 모든 것을 사용자 공통 CLAUDE.md로 모아버리면, 특정 툴에서만 사용하는 빌드 명령어까지도 다른 리포지토리 작업 중에 매번 읽히게 됩니다.
여러분 환경에서는 CLAUDE.md의 내용이 리포지토리 간에 얼마나 중복되고 있을까요?
Claude Code 공식 문서를 기준으로, 작성 시점에서 CLAUDE.md를 배치할 수 있는 곳은 주로 다음 두 가지입니다.
| 종류 | 배치 예시 | 적용 범위 |
|---|---|---|
| 사용자 공통 | ~/.claude/CLAUDE.md | 내 PC상의 모든 프로젝트 |
| 프로젝트 | 리포지토리 직하단의 CLAUDE.md (또는 .claude/CLAUDE.md) | 해당 리포지토리(팀 공유 가능) |
이 외에도 조직 전체에 배포하는 관리용 CLAUDE.md, 자신만 사용하는 프로젝트 전용의 CLAUDE.local.md와 같은 배치 위치나, @경로를 이용해 다른 파일을 가져오는 작성 방식도 설명되어 있습니다. 로드 순서나 세부 동작은 변경될 수 있으므로 최신 내용은 공식 문서를 확인해 주세요.
이 글에서는 위의 표에서 두 가지 경우만을 사용한 분리 방법을 소개합니다.
제가 사용하는 기준은 단 하나입니다.
'다른 리포지토리에서 이 한 줄을 읽었을 때, Claude Code가 혼란스러워하거나 잘못할까?'
혼란스럽지 않으면 사용자 공통으로 옮기고, 혼란스러우면 리포지토리별로 분리합니다. 이 기준으로 CLAUDE.md의 내용을 분류하자 다음과 같았습니다.
docs/, 판단 근거는 메모용 폴더 등)경계에서 고민했던 부분은 '운영 환경 반영 방법'이었습니다. 모든 툴에서 방법이 같다면 공통으로 작성하고, 툴마다 다르면 리포지토리에 작성합니다.
여기서는 기사 작성을 위해 준비한 가상의 리포지토리 2개(비품 대여 관리와 일일 보고서 집계)를 사용하여 분리 방법을 시도했습니다.
~/.claude/CLAUDE.md에 어떤 리포지토리에서든 지켜주었으면 하는 내용만 작성합니다.
비품 대여 툴(Asset Lending Tool)의 리포지토리 직하단에 위치하는 CLAUDE.md입니다.
# 비품 대여 관리 툴
## 목적
총무팀에서 비품(PC, 프로젝터 등)의 대여와 반납을 기록한다.
...
일보 집계 툴 측에도 동일한 형태로, 목적・구성・명령어・지켜야 할 것만 작성합니다.
# 일보 집계 툴
## 목적
현장별 일보(CSV)를 주 단위로 집계하여 작업 시간 목록을 만든다.
...
공통 규칙은 어느 쪽에도 작성하지 않습니다. 참고로, 명령어는 가상의 리포지토리를 위한 예시입니다. 본인의 툴에서는 실제로 사용하고 있는 명령어로 대체해 주세요.
/memory
명령어에서도 CLAUDE.md 목록을 열 수는 있지만, 공식 문서에 따르면 이 목록에는 아직 존재하지 않는 파일 항목도 표시됩니다. 실제로 로드되었는지 여부는 /context
의 'Memory Files'에서 확인하는 것이 가장 확실합니다.
claude -p
(대화 화면을 열지 않고 한 번만 지시를 실행하는 모드)에서도 /context all는 작동했기 때문에, 비품 대여 툴 폴더에서 실행했습니다. 출력 중 해당 부분만 발췌했습니다(경로는 일부 가렸습니다).
### Memory Files
| Type | Path | Tokens |
|------|------|--------|
...
사용자 공통(User)과 리포지토리(Project) 두 가지가 로드되었음을 알 수 있습니다.
더불어, 각각의 폴더에서 다음과 같이 질문합니다.
이 리포지토리에서 지켜야 할 규칙을 어떤 파일에 작성되어 있는지와 함께 목록으로 만들어 주세요.
2026년 11월 6일에 Windows 11・Claude Code 2.1.318로, 두 폴더를 각각 한 번씩 시도했습니다. 사용자 공통의 CLAUDE.md는 Step 1과 같은 종류의 규칙(add 방법・미커밋 변경에 관여하지 않기・기록 분류 등)에 제 업무용 항목이 추가되어 평소 사용하는 것을 그대로 사용하고 있습니다.
비품 대여 툴 측 답변 중, 리포지토리 부분은 다음과 같았습니다(발췌).
## 1. 이 리포지토리의 규칙
**`bihin-kashidashi opruleCLAUDE.md`**(리포지토리 내에 있음)
- 대여 기한 계산은 `app/rules.py`에 정리한다. 화면에는 작성하지 않는다.
...
알게 된 점은 다음 3가지입니다.
두 폴더 모두에서 공통 규칙과 고유 내용이 파일명과 함께 제시되었다. 일보 집계 툴 측에서는 python -m unittest discover tests와 python -m app.weekly data가 언급되었고, 비품 대여 툴의 명령어는 나오지 않았습니다(역도 마찬가지) -
공유되지 않는 것을 Claude Code 자체가 지적했다. 비품 대여 툴 답변 마지막에 “사용자 공통 규칙은 다른 사람이 리포지토리를 clone 해도 보이지 않는다. 팀에서 공유하려면 리포지토리 측에도 작성하는 것이 추천된다”는 취지의 주의사항이 붙어 있었습니다 -
답변 언어는 어딘가에 적어두는 것이 좋다. 제 사용자 공통 CLAUDE.md에는 답변 언어를 적지 않았기 때문에, 일보 집계 툴 측 답변은 질문이 일본어임에도 영어로 돌아왔습니다. Step 1의 예시에 “일본어로 답변한다”를 넣은 이유가 이것입니다.
분리하는 가장 큰 장점은 공통 규칙을 한 곳만 수정하면 어떤 리포지토리에도 반영된다는 점입니다.
사용자 공통은 짧게 유지한다. 모든 프로젝트에서 매번 읽히기 때문에, 길어질수록 관계가 희박한 지시사항이 늘어납니다 -
사용자 공통의 CLAUDE.md는 팀과 공유되지 않는다. 팀에서 지켜주었으면 하는 규칙은 리포지토리 쪽에 작성해야 합니다 -
모순을 만들지 않는다. 공통에 “docs/에 작성한다”, 리포지토리에 “wiki에 작성한다”라고 적혀 있으면, 어느 것을 따를지는 상황에 따라 달라집니다. 예외는 리포지토리 측에서 “이 리포지토리에서는 ~”라고 명확히 기재하는 것이 좋습니다.
/context내일 할 수 있는 첫 번째 단계는 현재 가지고 있는 리포지토리의 CLAUDE.md 두 개를 나란히 놓고, 같은 줄에 표시(마크)를 해보는 것입니다. 표시된 줄이 사용자 공용으로 옮길 후보 내용입니다.
아직 CLAUDE.md를 작성하지 않은 분들을 위해, 처음 3줄부터 시작하는 작성 방법은 note에 정리해 두었습니다.
정보 시스템 담당자가 Claude Code를 업무에 도입하는 전체 과정은 Zenn의 본에 정리해 두었습니다.
사내에 배포할 CLAUDE.md의 템플릿과 권한 설정을 배포 가능한 형태로 정리한 것은 유료 note 기사(1,480엔)로 만들었습니다.
