Claude Plan Md Best Practice

July 17, 2026

title: “[til/ai] Claude.md와 Plan.md를 어떻게 나눠야 Claude Code가 잘 일할까” date: 2026-07-17 excerpt: “Claude Code 프로젝트에서 CLAUDE.md와 PLAN.md를 역할별로 나누는 방법과 실제 운영 팁을 정리했다.” tags: [til, ai, claude-code, prompt-engineering] categories: [til/ai] ***

Claude.md와 Plan.md를 어떻게 나눠야 Claude Code가 잘 일할까

Claude Code를 오래 붙잡고 프로젝트를 진행하다 보면, 결국 프롬프트 한 줄보다 프로젝트 문서 구조가 더 중요하다는 걸 체감하게 된다. 특히 작업이 길어질수록 “이 프로젝트에서 절대 바뀌면 안 되는 규칙”과 “이번 세션에서만 중요한 컨텍스트”를 한 파일에 몰아넣으면 Claude가 자주 흔들린다.

이번에는 실제로 운영 중인 CLAUDE.md, PLAN.md를 기준으로, 어떤 식으로 나누면 Claude가 더 안정적으로 일하는지 정리해봤다.

왜 문서를 나눠야 하나

처음에는 보통 모든 내용을 CLAUDE.md 하나에 넣게 된다. 프로젝트 설명, 기술 스택, 현재 진행 상황, 열려 있는 이슈, 오늘 해야 할 일, 화면 규칙, 보안 주의사항까지 전부 한 파일에 넣는 식이다.

이 방식은 초반에는 편하다. 하지만 프로젝트가 조금만 커져도 문제가 생긴다.

항상 유효한 규칙과 일회성 메모가 섞인다.
Claude가 지금 꼭 봐야 할 내용과 나중에 봐도 되는 내용을 구분하지 못한다.
세션이 길어질수록 컨텍스트가 비대해진다.
진행 상황이 바뀔 때마다 CLAUDE.md를 계속 고쳐야 해서, 파일 자체의 역할이 흐려진다.

결국 CLAUDE.md는 헌법 같은 파일이어야 하고, 진행 상황이나 작업 계획은 별도 파일로 분리하는 편이 훨씬 낫다.

내가 추천하는 역할 분리

핵심은 다음처럼 나누는 것이다.

1. CLAUDE.md: 프로젝트 헌법

CLAUDE.md에는 아래처럼 항상 유효한 규칙만 남긴다.

서비스 포지셔닝
절대 하면 안 되는 기능/카피
기술 스택
도메인 모델
핵심 비즈니스 규칙
보안 규칙
화면별 고정 규칙
하이파이 와이어프레임 이후 구현 규칙
작업 단위 규칙
완료 기준

즉, 이 파일은 “Claude가 이 프로젝트에서 어떤 태도로 일해야 하는가”를 정의하는 문서다.

중요한 포인트는, CLAUDE.md에는 반복해서 틀리면 큰일 나는 것 위주로만 넣는다는 점이다. 예를 들면 이런 것들이다.

판정 로직은 클라이언트에서 재구현하지 않는다.
민감 정보는 기본 비노출이다.
하이파이 와이어프레임이 있으면 그것을 spec으로 취급한다.
사용자 승인 없이 핵심 CTA나 정보 구조를 바꾸지 않는다.

이런 규칙은 세션이 달라져도 거의 안 바뀐다.

2. PLAN.md: 현재 iteration의 실행 계획

반면 PLAN.md에는 지금 이 작업 사이클에서만 중요한 내용을 둔다.

현재 어디까지 끝났는지
다음 스텝이 무엇인지
각 단계별 실행 순서
어떤 모델을 어떤 구간에 쓸지
검증 방법
Follow-up backlog

이 파일은 Claude에게 “지금 무엇을 해야 하는가”를 알려주는 문서다.

정리하면 이렇게 볼 수 있다.

문서	역할	성격
`CLAUDE.md`	프로젝트 헌법	장기적으로 유지되는 규칙
`PLAN.md`	현재 실행 계획	iteration마다 바뀌는 컨텍스트
PRD / UserFlow	제품 요구사항 원문	사람이 읽는 원본 문서

이렇게 나누면 Claude도 훨씬 안정적으로 행동한다.

실제로 운영할 때 좋았던 패턴

CLAUDE.md는 짧게가 아니라, “역할이 명확하게”

종종 CLAUDE.md는 무조건 짧아야 한다는 얘기가 있는데, 실제로는 무조건 짧은 게 중요한 건 아니다. 더 중요한 건 불변 규칙만 담겨 있는가다.

예를 들어 다음 정보는 길어도 CLAUDE.md에 있는 게 좋다.

인증 모델 설명
왜 이 아키텍처를 선택했는지
화면별 핵심 제약
민감 정보 노출 정책
하이파이 이후 구현 우선순위

반대로 다음은 되도록 PLAN.md 쪽에 있는 게 낫다.

오늘 끝낸 작업 목록
다음으로 구현할 Step
이번 주에만 유효한 의사결정 메모
임시 기술 부채 목록

즉 길이보다 문서의 역할 보존이 더 중요하다.

PLAN.md는 plan과 log를 섞되, 섹션은 분리

PLAN.md에서 자주 생기는 문제는 실행 계획과 진행 로그가 뒤섞여서 읽기 어려워진다는 점이다. 그래서 아래 정도로 섹션을 고정해두는 걸 추천한다.

# PLAN.md

## 0. Context
- 범위
- 현재 상태
- 참조 문서

## 1. Execution Plan
- Step 0
- Step 1
- Step 2

## 2. Progress
- [x] 완료한 것
- [ ] 다음 작업

## 3. Validation
- 각 Step 완료 후 검증 방법

## 4. Follow-Up
- 지금 안 하지만 잊으면 안 되는 것

이렇게 해두면 사람도 읽기 쉽고, Claude에게도 “1번만 보고 계획 세워”, “2번 기준으로 다음 작업만 진행해” 같은 식으로 정확하게 지시하기 좋다.

Claude가 잘 일하게 만드는 운영 루틴

문서를 잘 나누는 것만으로는 충분하지 않다. 실제 세션 운영도 같이 맞춰야 한다.

내가 추천하는 루틴은 다음과 같다.

1. 새 작업 시작 전

Claude에게 바로 코드를 쓰게 하지 않는다. 먼저 PLAN.md를 읽고, 현재 남은 작업을 짧게 정리하게 한다.

예를 들면 이런 식이다.

PLAN.md를 기준으로 현재 남은 작업을 요약하고, 이번 세션에서는 무엇만 구현할지 먼저 제안해줘. 승인 전까지는 코드 수정하지 마.

이렇게 하면 Claude가 곧바로 구현으로 뛰어드는 걸 막을 수 있다.

2. 구현은 한 화면 또는 한 컴포넌트 단위로

작업 단위를 작게 자르는 것도 중요하다.

한 번에 한 화면
또는 한 번에 한 컴포넌트
작업 전에 참조 문서 / 수정 파일 / 변경 범위 / 불명확점을 먼저 출력

이 규칙은 CLAUDE.md에 넣어두면 효과가 좋다. 실제로 Claude는 작업 범위를 안 정해주면 자꾸 판을 키우는 경향이 있다.

3. 완료 기준을 문서에 적어둔다

“끝났다”의 정의도 미리 적어두는 게 좋다.

예를 들면:

와이어프레임의 정보 구조와 CTA가 유지되었는가
서버 판정 로직을 재구현하지 않았는가
민감 정보가 기본 비노출인가
loading / empty / error / disabled 상태가 필요한 만큼 반영됐는가
구현 결과와 시안 차이가 보고되었는가

이런 완료 기준이 있으면 Claude가 보기엔 그럴듯하지만 실제로는 빠진 상태를 완료로 착각하는 일이 줄어든다.

Hifi 와이어프레임이 나온 뒤 특히 중요한 점

하이파이 시안이 나온 뒤에도 Claude가 종종 자기 식으로 레이아웃을 다시 해석하려고 할 때가 있다. 그래서 이 시점부터는 CLAUDE.md에 아래 규칙을 넣어두는 걸 강하게 추천한다.

Hifi 와이어프레임은 참고 자료가 아니라 구현 기준(spec)이다.
사용자 승인 없이 정보 구조, 핵심 CTA, 토큰 체계를 바꾸지 않는다.
디자인 의도가 불명확하면 추측하지 말고 질문하거나 TODO로 남긴다.
우선순위는 정보 구조 → 플로우 → 시각 계층 → 상태 화면 → 토큰 → 구현 최적화 순서로 따른다.

이걸 적어두면 “예쁘게 다시 해석하는 Claude”보다 “정확하게 구현하는 Claude” 쪽으로 행동이 많이 바뀐다.

지금 구조에서 한 단계 더 가고 싶다면

문서가 더 많아지면 다음처럼 확장할 수도 있다.

CLAUDE.md: 프로젝트 헌법
PLAN.md: 현재 iteration plan
BACKLOG.md: 장기 follow-up 항목
HANDOFF.md: 세션 종료 시 다음 세션을 위한 요약

다만 처음부터 파일을 너무 많이 나누면 관리 비용이 커진다. 보통은 CLAUDE.md + PLAN.md만으로도 충분하고, backlog가 커질 때만 분리하는 편이 낫다.

마무리

정리하면 CLAUDE.md와 PLAN.md를 분리하는 건 꽤 좋은 패턴이고, 실제로 Claude Code를 오래 운영할수록 이 분리의 효과가 커진다.

중요한 건 단순히 파일을 둘로 나누는 게 아니라:

CLAUDE.md는 불변 규칙만 담고
PLAN.md는 현재 실행 계획과 진행 상황을 관리하고
Claude에게는 항상 plan-first로 일하게 만들고
구현 단위와 완료 기준을 문서로 명확히 박아두는 것

이렇게 해두면 세션이 길어져도 훨씬 덜 흔들리고, 나중에 다시 프로젝트를 열었을 때도 컨텍스트를 빠르게 복구할 수 있다.

업무 중 AI 코딩 에이전트를 계속 쓰다 보면 결국 중요한 건 프롬프트 한 줄이 아니라 문서 구조와 작업 운영 방식이라는 걸 자주 느끼게 된다.

혹시 실제로 운영 중인 CLAUDE.md / PLAN.md가 있다면, 회사 관련 민감한 정보가 포함되지 않았는지 한 번 더 확인한 뒤 공개하는 것을 추천한다.

Jeong Sun Min