Claude Code의 사양 주도 개발(Specification-Driven Development)을 위한 docs 폴더 구성 베스트 프랙티스

서론

안녕하세요! 평소 개발에 Claude Code를 사용하고 있는 주식회사 무쿠이루(Mukuiru)의 Yusei입니다.

Claude Code를 사용해 나가면서 프로젝트 내의 docs/ 폴더 구성에 대해 고민하게 되었습니다. 처음에는 "규칙이나 사양서를 모아두면 Claude가 참조해 주니 편리하겠다" 정도의 가벼운 마음이었지만, 개발이 진행됨에 따라 파일이 늘어나면서 다음과 같은 고민에 부딪히게 되었습니다.

• 사전에 읽혀야 할 규칙이 많으면 그 자체로 컨텍스트(Context)를 압박한다.
• 파일이 점점 늘어나 정리와 관리가 힘들어졌다.

그러던 중 Claude Code의 공식 문서를 읽다가, .claude/rules/에 paths를 지정하면 "해당 파일을 건드렸을 때만 규칙이 읽힌다"는 메커니즘이 있다는 것을 알게 되었습니다.

지금까지 docs/에 전부 넣어두고 수동으로 읽게 해왔던 저에게는 상당한 전환점이 될 것 같습니다.

이 글에서는,

• 기존의 "docs/에서 전부 관리하기" 방식과 그 한계
• 메커니즘을 파악한 후, 향후 .claude/ 하위의 path-scoped 방식으로 전환해 나갈 이행 플랜

을 공유하고자 합니다. 아직 완전히 이행하지 못한, 탐색 중인 기록입니다. "이것이 정답이다"라는 이야기가 아니라, 저의 비망록으로서, 또한 비슷한 고민을 하는 분들에게 하나의 초안이 되기를 바라는 마음으로 작성했습니다.

Claude Code의 "컨텍스트 메커니즘" 이해하기

방침 전환의 계기가 된 것은, Claude Code가 애초에 "항상 읽히고 싶은 정보"와 "필요할 때만 읽히고 싶은 정보"를 메커니즘으로서 나누어 다룰 수 있다는 사실을 알게 된 것이었습니다. 요점만 정리하겠습니다.

• CLAUDE.md는 매 세션 시작 시 전체가 읽힌다. → 프로젝트 루트에 두면 자동으로 항상 적용되므로 강력하지만, 그만큼 계속 컨텍스트를 소비합니다. 기준은 "파일당 200행 이하"로 권장됩니다. 즉, 여기에 무엇이든 채워 넣으면 압박을 느끼는 것은 구조상 당연한 일이었습니다.

• .claude/rules/에 규칙을 분할하고 paths를 지정하면 조건부로 읽을 수 있다. → 매칭되는 파일을 Claude가 건드렸을 때만 읽히므로, 상시 로드를 피할 수 있습니다. 이것이 저에게 "컨텍스트 압박"을 해결할 희망이었습니다.

• @import (@path 표기법)는 컨텍스트 절약이 되지 않는다. → 파일을 분할하여 정리하는 데는 편리하지만, 기동 시에 전개되어 읽히기 때문에 토큰(Token) 소비는 줄어들지 않습니다.

• 무거운 조사는 서브 에이전트(Sub-agent)에게 넘길 수 있다. → 서브 에이전트는 별도의 컨텍스트를 가지므로, 조사 본문에서 메인 컨텍스트를 더럽히지 않고 끝낼 수 있습니다.

• 이 외에도 Claude 스스로 학습 내용을 기록하는 auto memory나, 필요할 때만 읽히는 skills와 같은 메커니즘도 있습니다.

여기서 가장 큰 배움은, "효과가 있는 것은 path-scoped 규칙이며, @import로 연결하는 것만으로는 컨텍스트가 줄어들지 않는다"는 점이었습니다.

docs/에서 전부 관리하던 방식

지금까지 저는 Claude Code에 전달하고 싶은 모든 정보를 docs/ 하위에 두고 관리해 왔습니다. 구성은 다음과 같습니다.

docs/
├── global_rule.md # 이 폴더 전체의 규칙. 반드시 참조하도록 함
├── rules/ # 코드를 작성할 때의 베스트 프랙티스·규약
...

생각하는 방식으로는, 조금 세세하지만 records/ → plans/ → tasks/ → done/이라는 **파일의 라이프사이클(Lifecycle)**을 만들어 두었습니다.

specs/는 "앱의 진실(Source of Truth)"로서 업데이트가 있으면 항상 최신 상태로 유지하는 운용 방식입니다. global_rule.md에는 "파일을 만들 때는 반드시 이 파일을 읽을 것", "포맷은 이렇게 할 것"과 같은 폴더 전체의 사용 규칙을 적어 두었습니다.

이 방식의 장점은 모든 것이 docs/ 한곳에 모여 있어 심플하다는 점입니다. 또한 Git으로 공유하는 것도 가능합니다.

반면, 운용하면서 다음과 같은 한계에 부딪혔습니다.

• global_rule.md는 "반드시 읽어"라고 매번 지시하지 않으면 확실하게 작동하지 않는다. 언급하지 않을 때는 규칙 준수가 일부 어긋난다.
• rules/

매번 한꺼번에 읽게 하면 그것만으로도 컨텍스트 (Context)를 압박한다. - 개발이 진행될수록 파일이 늘어나 비대해지며 관리가 어려워진다.

"더 정리 잘 된 방법이 있을 텐데"라고 생각하며 한동안 임시방편으로 사용해 왔던 것이 솔직한 심정입니다.

앞으로의 도전

여기서부터는 위에서 언급한 메커니즘을 바탕으로 「.claude/ 하위의 path-scoped (경로 범위 지정) 방식으로 구성하는 것」을 시도해 보려 합니다. 아직 본격적으로 도입한 것은 아니며, 앞으로 시도할 방침 및 가설로서 읽어주시면 감사하겠습니다.

global_rule.md → 루트의 CLAUDE.md (지도 역할)

global_rule.md가 수행하던 "폴더 사용법을 항상 의식하게 만드는" 역할은, 자동으로 풀 로드 (Full load) 되는 CLAUDE.md가 가장 적합합니다. 다만 내용을 너무 채워 넣으면 컨텍스트를 압박하므로, 내용은 얇게 유지하며 "어디에 무엇이 있는지"와 "언제 그것을 읽어야 하는지"만을 적은 지도라는 이미지로 구성합니다.

# 프로젝트 개요
(프로젝트의 목적, 기술 스택 등을 간결하게)
## 문서 위치 및 참조 규칙
...

rules/*.md → .claude/rules/*.md + paths로 조건부 로드

이것이 이번 도전의 핵심입니다. 지금까지 일괄적으로 읽게 했던 rules/를 .claude/rules/로 옮기고, paths 프론트매터 (Frontmatter)를 붙여 "해당 파일을 다룰 때만 읽히는" 상태로 만듭니다.

예를 들어 React의 규약은 다음과 같이 작성합니다.

---
paths:
- "**/*.{tsx,jsx}"
...

같은 방식으로,

• python.md → paths: ["**/*.py"]
• backend.md → paths: ["src/api/**"]
• frontend.md → paths: ["src/components/**"]

와 같이 언어나 레이어(Layer)별로 스코프 (Scope)를 나눌 수 있습니다. 이렇게 하면 .py 파일을 다루고 있을 때 React 규약은 읽히지 않고, 필요한 것만 컨텍스트에 올라갑니다. "react는 frontend에 포함되는 것 아닌가?"와 같은 분류의 모호함도 경로로 구분함으로써 자연스럽게 정리될 수 있을 것 같습니다.

paths를 지정하지 않은 규칙은 루트의 CLAUDE.md와 마찬가지로 매번 로드됩니다. "언어와 상관없이 항상 지키게 하고 싶은 규약"은 의도적으로 paths 없이 남겨두는 것이 좋아 보입니다.

specs/ 등의 자료는 docs/에 남김

specs/, records/, plans/, tasks/, done/, ref/, image/, video/는 상시 로드할 필요가 없는 "필요할 때마다 참조하는 자료"이므로 docs/에 남깁니다. 이들은 CLAUDE.md라는 지도에서 참조 타이밍을 지시하기만 하고, 필요한 시점에만 읽도록 하는 것을 상정합니다.

조사는 서브 에이전트에게, 비대화는 운영 규칙으로

• **조사 (Investigation)**는 서브 에이전트 (Sub-agent)에게 맡겨 긴 조사 과정이 메인 컨텍스트를 오염시키지 않도록 하고, 결론만 남깁니다. (records/ 활용)
• 비대화 방지 대책은 꾸준히 실천합니다. 파일명에 날짜와 시간, 일련번호를 붙이거나 (예: 20260531_1200_feature-x.md), 각 폴더에 index를 두거나, 완료되면 done/으로 이동시키는 등의 규칙을 철저히 합니다.

예상되는 과제 및 아직 모르는 점

이전 계획은 세웠지만 아직 운영 전이기에 "이 부분은 시도해 보지 않으면 알 수 없다"는 점이 여러 가지 있습니다. 오히려 이 부분이 본론일지도 모릅니다.

• docs/와 .claude/의 경계 설정. → 자동 로드 (.claude/)와 수시 참조 (docs/)의 경계를 어디에 긋는 것이 운영하기 편할지는 아직 모릅니다. 앞으로의 과제입니다.
• 너무 과도한 path-scoped 설정의 위험성. → 스코프를 너무 좁게 설정하여 "읽어야 할 때 읽히지 않는" 상태가 되면 본말전도이므로, paths 없이 상시 로드하는 규약과의 균형을 맞추는 것이 과제입니다.
• specs/를 "정답"으로 유지하는 운영. → 구현 후에 확실히 업데이트하도록 만드는 메커니즘을 훅 (Hook)이나 슬래시 커맨드 (Slash command)로 만들 수 있을지 시도해 보고 싶습니다.

이 부분에 대해서는 실제로 이행해 보면서 알게 된 점이 있다면, 이 기사에 추가하거나 속편을 작성할 계획입니다.

요약

• 지금까지는 docs/에 전부 넣고, 수동으로 "(파일 경로)를 준수해서"라고 지시하며 관리해 왔다.
• CLAUDE.md는 매번 전체 로드(Full load)되는 반면, .claude/rules/는 paths를 통해 "필요할 때만" 읽게 할 수 있는 메커니즘을 알게 되었다.
• 앞으로의 도전 과제는 상시 필요한 지도는 CLAUDE.md, 언어·레이어별 규약은 .claude/rules/에 경로 범위 지정(Path-scoped) 방식으로, 자료는 docs/에 배치하는 형태로 구성해 나가는 것이다.

"@import로는 절약이 되지 않으며, 효과가 있는 것은 경로 범위 지정(Path-scoped)이다"라는 점 하나를 알게 된 것만으로도 저에게는 큰 수확이었습니다.

마지막으로, 여러분은 docs/나 .claude/를 어떻게 구성하고 관리하고 계신가요? "저는 이렇게 하고 있습니다", "경로 범위 지정(Path-scoped)을 사용하며 이런 점이 어려웠다/편리했다" 등 댓글로 공유해 주시면 감사하겠습니다. Claude Code가 아니더라도 다른 AI를 사용하며 겪은 노하우나 어려움 등을 공유해 주시면 새로운 발견을 할 수 있을지도 모르니 꼭 부탁드립니다.

끝까지 읽어주셔서 감사합니다!

즐거운 개발 생활 되시길!

Discussion