지난 글에서 부서별 Claude Code 세션이 지침을 잘 안 지키는 문제를, 작업 폴더에 직접 CLAUDE.md를 두는 식으로 해결한 사례를 적었다. 거기서 한 단계 더 가서 이번엔 “그럼 지침을 어떤 기준으로 나눠야 하는가” 에 대한 정리.
Table of contents
Open Table of contents
현재 운영 방식 — 부서 분리
내 바이브 코딩 프로젝트는 실제 회사 부서를 흉내내서 굴리고 있다.
- 프론트엔드 세션 — UI 작업
- 백엔드 세션 — 서버 함수, DB 작업
- QA 세션 — 테스트, 회귀 점검
- 코드 분석/관리 세션 — 리뷰, 리팩터링, git 명령
- (필요 시 기획·PM 세션 추가)
각 세션은 자기 업무만 하고, 다른 부서의 도움이 필요하면 “업무 요청 메시지” 를 적어두는 식으로 통신한다. 사실상 한 사람짜리 회사를 운영하는 셈.
처음 시도 — guidelines.md per 부서
각 부서 폴더 안에 guidelines.md 를 만들어 부서별 규칙을 적었다. 의도는 좋았지만 실제로는 잘 안 지켜졌다. 자주 사용하는 세션일수록 자기 guidelines를 빠뜨리고 일을 시작하는 일이 잦았다.
지난 글에서 해결한 핵심: guidelines.md 라는 파일은 사람용 문서에 가깝고, Claude Code가 자동 인식하는 건 CLAUDE.md. 부서의 실제 작업 폴더(예: flutter/lib/)에 CLAUDE.md를 두면 자동으로 적용되고 잘 지킨다.
이걸 적용하고 나니, 그 다음 질문이 자연스럽게 따라왔다.
공통적인 규칙은 어디에 두지? 부서마다 똑같은 규칙을 다 복붙해야 하나?
새 원칙 — 공통은 공통에, 특화는 특화에
며칠 운영하면서 가닥이 잡혔다.
공통 지침 — 루트 CLAUDE.md
모든 세션이 알아야 하는 규칙은 루트에 둔다. 대표적으로:
- 형상 관리 / git 사용 규칙 — 누가 commit/push 권한을 가지는가, 브랜치 네이밍, PR 흐름. 코드를 직접 안 쓰는 기획자·PM 세션도 알고 있어야 한다(작업 단위를 어떻게 자를지에 영향).
- 저장소 전체 규칙 — 파일 명명, 디렉토리 정책, 보안(시크릿 절대 커밋 금지) 같은 기본 위생.
- 세션 간 통신 프로토콜 — “업무 요청 메시지를 어디에 어떻게 적는가”, “다른 부서 코드는 직접 건드리지 않는다” 같은 부서 간 룰.
이런 건 부서마다 다를 이유가 없고, 모두에게 동일하게 적용되는 게 핵심이다.
특화 지침 — 부서 작업 폴더의 CLAUDE.md
부서별로 “그 작업 폴더에서만 의미 있는” 규칙은 작업 폴더 안 CLAUDE.md에 둔다.
- 프론트엔드 세션의 작업 폴더 (
flutter/lib/): 위젯 구조 컨벤션, 상태 관리 방식, 스크린 폴더 정책 - 백엔드 세션의 작업 폴더 (
supabase/functions/): Edge Function 패턴, 환경변수 사용 규칙, DB 접근 패턴 - QA 세션 작업 폴더: 테스트 케이스 작성 기준, 회귀 점검 체크리스트
다른 부서 입장에서는 알 필요도 없고 컨텍스트만 키우는 정보들. 자기 작업 폴더에서 세션이 켜질 때만 자동으로 로드되니, 세션별로 받는 컨텍스트가 정확히 그 부서에 필요한 만큼으로 좁혀진다.
정리 — 한 줄로
공통 규칙은 한 곳에 모으되, 특별한 업무를 수행하는 자리에는 그 자리에 맞는 특별한 지침이 따로 있어야 한다.
이게 이번에 정착시킨 원칙. 단순한 위치 선택의 문제로 보이지만, 세션이 받는 컨텍스트를 의도적으로 설계하는 일이라는 관점에서 보면 사실은 에이전트 설계의 한 축이다.
한계와 다음 의문
가닥은 잡혔지만 운영하면서 다시 생긴 질문들.
1. 공통 규칙이 부풀면?
루트 CLAUDE.md가 길어질수록 모든 세션이 그걸 매번 읽는다. 비용/지연/집중도 모두 영향받음. 얼마까지가 적정선인지, 길어지면 어떻게 분할해야 할지 (예: 카테고리별로 다시 쪼개기) 명확한 기준이 없다.
2. 부서를 가로지르는 규칙
예: “API 응답 스키마는 백엔드가 결정하지만 프론트엔드도 따른다” — 이건 공통도 아니고 한 부서 특화도 아니다. 양쪽 모두에 동시에 필요한 규칙은 어디에 두는 게 맞나? 양쪽에 중복으로 적어야 하나, 한쪽에만 적고 참조 링크를 다른 쪽에 두나?
3. 부서가 늘어나면
지금은 4~5개 부서로 충분하지만, 부서가 더 잘게 나뉘면 (예: 프론트엔드 안에 UI 부서 / 상태관리 부서) 작업 폴더가 중첩되고 CLAUDE.md도 중첩된다. Claude Code가 여러 단계의 CLAUDE.md를 어떻게 병합해서 적용하는지, 우선순위가 어떻게 되는지 정확히 모른다.
더 공부해볼 것
위 의문들을 풀기 위해 다음 토픽을 짚어야겠다.
1. Claude Code의 CLAUDE.md 사용법 (공식)
- 작업 디렉토리에서 어디까지 위로 올라가며
CLAUDE.md를 찾는가 - 여러
CLAUDE.md가 발견됐을 때 병합/우선순위 규칙 - 글로벌(
~/.claude/CLAUDE.md) vs 프로젝트 vs 서브폴더의 관계 - 참고: Claude Code Memory 문서
2. Agent Engineering / Prompt Engineering 전반
- 에이전트가 받아야 할 컨텍스트를 어떻게 의도적으로 설계하는가
- “한 번에 다 알려주기” vs “필요할 때 호출”의 트레이드오프
- Role-based prompting, instruction layering 같은 패턴
- 참고: Anthropic의 Building effective agents 글
3. 다중 에이전트(Multi-Agent) 시스템 디자인
- 부서 분리 운영 자체가 multi-agent 패턴의 한 형태 — 정식 문헌에서 어떻게 정리하고 있는지
- 에이전트 간 통신 프로토콜, 권한 격리, 충돌 해소 방법
- 단일 에이전트로 다 시키는 것과 비교했을 때 언제 multi-agent가 더 나은가
4. 직접 실험으로 측정해볼 것
- 같은 작업을 (a) 공통/특화 분리 없이 모두 루트 CLAUDE.md에 / (b) 분리 운영 으로 비교 — 토큰 사용량, 지침 위반 빈도, 작업 완료 시간
- 부서 수를 늘릴수록 (5→10→15) 효율이 어떻게 변하는가의 임계점
5. “guidelines.md” 같은 사람용 문서를 어떻게 유지할까
- 사람용 문서와 AI용
CLAUDE.md의 단일 출처(SoT) 유지 패턴 - 한 군데를 고치면 다른 쪽도 자동으로 따라가도록 만드는 방법
회고
처음엔 단순히 “AI가 말을 안 듣는다” 의 문제로 시작했는데, 풀어가다 보니 본질은 에이전트에게 컨텍스트를 어떻게 설계해서 전달하느냐 였다. 회사가 부서별로 매뉴얼을 두는 이유, 그리고 전사 공지는 따로 모두에게 보내는 이유 — 둘이 분리된 데에는 분명한 효율적 근거가 있고, 그 구조가 AI 세션 운영에도 자연스럽게 적용된다.
다음 단계는 위 “공부할 것” 중 1, 2번을 우선해서 짚어보는 것. CLAUDE.md 동작 원리를 정확히 알고, Anthropic이 권장하는 에이전트 설계 패턴이 뭔지 파악한 다음, 내 부서 운영 방식이 그 정설과 어디가 같고 어디가 다른지 한 번 정렬해보고 싶다.