1인 앱 개발에 Claude Code를 여러 세션으로 나눠 쓰는 방식(편의상 “부서별 세션”)으로 운영하고 있다. 그 중에 잘 안 풀리던 한 가지 문제와, 단순한 위치 변경으로 풀린 과정을 적는다.
Table of contents
Open Table of contents
운영 방식 — 부서별 세션 분리
내 바이브코딩 셋업은 대략 이런 구조다.
- 프론트엔드 부서 세션: Flutter 코드 (UI / 로컬 상태) 작업 담당
- 백엔드 부서 세션: Supabase 함수, 스키마, 정책 작업 담당
- 코드 분석/관리 세션: 리뷰, 리팩터링, git 명령어 (commit/push/branch) 담당
세션마다 역할 경계가 있다. 그중에서 git 명령어는 “코드 분석/관리 세션만 사용 가능”으로 정해뒀다. 한 부서가 자기 작업물을 자기가 커밋해버리면 검토 단계가 무력화되니까.
문제 — 프론트엔드 세션이 또 git을 썼다
문제는 프론트엔드 부서 세션이 자꾸 git 명령을 실행한다는 것이었다. 한두 번이면 모르겠는데, 새 세션을 시작할 때마다 같은 일이 반복됐다.
원인을 찾기 위해 내가 만들어둔 지침 구조를 점검했다.
project-root/
├── CLAUDE.md ← 모든 부서 공통 / 전체 규칙
├── fe/
│ ├── GUIDELINES.md ← 프론트엔드 부서 전용 규칙
│ └── flutter/ ← 실제 Flutter 작업 폴더
│ └── lib/
└── be/
└── GUIDELINES.md ← 백엔드 부서 전용 규칙루트의 CLAUDE.md는 Claude Code가 자동으로 읽지만, 부서별 규칙은 GUIDELINES.md 라는 파일에 적어두고 “필요할 때 읽도록” 안내해뒀다. 의도는 좋았는데, 문제는 세션을 새로 시작할 때마다 그 GUIDELINES.md를 빠뜨리고 시작하는 일이 잦았다는 점.
새 세션은 이전 세션의 컨텍스트가 없다. “프론트엔드 부서 세션”이라고 내가 명명하긴 했지만, 실제로는 같은 Claude Code가 작업 폴더만 바뀌어 새로 켜진 것뿐. 자기 부서 GUIDELINES.md를 매번 능동적으로 찾아 읽으리라는 건 운에 맡기는 셈이었다.
가설과 시도
내가 떠올린 두 가지 방향.
방향 A — 모든 규칙을 루트 CLAUDE.md에 통합
부서별 규칙도 전부 루트 CLAUDE.md에 넣어버리는 방법. 확실히 모든 세션이 읽긴 하지만, 컨텍스트가 비대해지고, 프론트엔드 세션이 백엔드 세부 규칙까지 읽게 되어 토큰 낭비.
방향 B — CLAUDE.md를 “실제 작업 폴더”에 두기
Claude Code는 작업 디렉토리에 있는 CLAUDE.md를 자동으로 읽는다. 그렇다면 부서별 규칙도 GUIDELINES.md(이름)가 아니라 CLAUDE.md(이름) 로 바꾸고, 게다가 부서가 실제로 작업하는 폴더에 두면, 그 폴더에서 켜진 세션은 자동으로 그 규칙을 읽게 된다.
이 방향으로 갔다.
project-root/
├── CLAUDE.md
├── fe/
│ ├── GUIDELINES.md ← (그대로 둠 — 사람용 문서로 유지)
│ └── flutter/
│ ├── CLAUDE.md ← ★ 추가: 프론트엔드 작업 폴더에 직접
│ └── lib/
│ └── CLAUDE.md ← ★ 추가: 더 좁은 범위에도
└── be/
└── GUIDELINES.md핵심: 사람이 읽는 문서(GUIDELINES.md)는 그대로 두되, AI가 자동 인식해야 하는 규칙은 작업 폴더에 CLAUDE.md로 둔다. 두 종류의 문서를 분리한 셈.
결과
말을 잘 듣는다.
새 프론트엔드 세션을 띄우고 작업을 시킬 때, 작업 디렉토리 안에 있는 CLAUDE.md를 자연스럽게 인식하고 그 규칙을 따른다. 부서 경계(예: “git 명령은 쓰지 말 것”)를 매번 일러주지 않아도 잘 지킨다.
별 거 아닌 변경 같지만, “올바른 정보를 올바른 자리에 두는 것” 의 효과를 직접 본 사례였다.
정리
| 잘못된 가정 | 실제로 효과적인 방법 |
|---|---|
| ”각 부서 폴더에 GUIDELINES.md를 두면 알아서 읽겠지” | 능동적으로 읽으리라 기대 X. 자동 로드 메커니즘(작업 디렉토리의 CLAUDE.md)에 얹기 |
| ”규칙은 한 군데(루트)에 다 모으면 깔끔하다” | 모든 세션이 모든 규칙을 읽게 되어 비효율. 세션의 작업 범위에 맞춰 규칙도 스코프해야 함 |
더 공부해볼 것
1. Claude Code의 CLAUDE.md 로드 메커니즘
- 작업 디렉토리부터 위로 올라가며 어떤 파일들을 자동 인식하는지 (
CLAUDE.md, 사용자 홈 등) - 여러 CLAUDE.md가 발견됐을 때의 우선순위 / 병합 방식
- 서브디렉토리에 있는 CLAUDE.md는 그 디렉토리 안에서만 켰을 때 적용되는가, 부모에서 켜도 적용되는가
- 참고: Claude Code 공식 문서 — Memory
2. 멀티 세션 워크플로우의 안티패턴
- 부서 분리가 도움이 되는 케이스 vs 오히려 마찰만 키우는 케이스
- 같은 저장소에서 여러 세션이 동시에 작업할 때 머지 충돌 / 락 / 변경 가시성 문제
- “리뷰 세션”의 역할 — 부서가 자기 코드를 자기가 커밋 못 하게 하는 게 정말 가치가 있는가, 아니면 사람이 PR 단위로 보는 게 더 나은가
3. 지침 문서의 역할 분리
- AI가 자동 인식할 규칙(
CLAUDE.md) vs 사람이 읽는 가이드(GUIDELINES.md/README.md/CONTRIBUTING.md) — 두 종류의 문서를 어떻게 일관되게 운영할지 - 둘이 어긋나기 시작했을 때 단일 출처(SoT)를 유지하는 방법 (예:
CLAUDE.md가 GUIDELINES를 참조)
4. 직접 측정해볼 것
- 부서별 CLAUDE.md를 두기 전 vs 둔 후, 세션당 지침 위반 빈도를 한 주 정도 기록해서 정량 비교
- 같은 프롬프트로 여러 번 반복해서 위반 패턴이 재현되는 환경부터 만들면 비교가 깔끔할 듯
회고
지침을 어기는 AI를 보면 처음엔 “왜 말을 안 듣지” 라는 답답함부터 들지만, 결국 AI에게 정보를 어떻게 전달하고 있는가 의 문제로 돌아온다. 부서마다 자기 규칙이 있는데 그 규칙이 부서 사무실(작업 폴더)이 아니라 회의실 게시판(부서 외부 GUIDELINES.md)에 붙어 있으면, 매번 회의실까지 다녀와서 읽으라는 건 무리다. 사무실 책상 위에 그날 할 일이 적혀있는 게 자연스럽다.
다음 실험은 부서 CLAUDE.md를 더 잘게 쪼개봤을 때 (예: lib/screens/ 와 lib/services/ 에 따로) 효과가 어떻게 달라지는지 보는 것.