pland.md (ExecPlan)이란?

• 채팅에 흩어진 의도, 가정, 다음 단계를 파일 하나에 모아서 모델이 그것만 보고 이어서 구현하게 만드는 문서다.
• 진행, 발견, 결정이 바뀔 때마다 갱신하는 살아있는 문서라는 게 평범한 TODO 와 다르다.
• 좋은 계획은 파일 단위 지시가 아니라 제품 동작, 범위, 검증 방법을 함께 적는다.

plan 파일이 뭔가

코딩 에이전트에게 "무엇을 어떻게 끝까지 만들지" 를 한 장의 실행 명세서로 고정해 두는 문서다.

목적은 하나다. 몇 시간짜리 작업을 중간에 끊었다 다시 와도 그 파일만 읽고 이어서 구현할 수 있게 하는 것.

OpenAI Codex 쪽에서는 이런 문서를 ExecPlan(실행 계획)이라고 부른다. 저장소에 PLANS.md 로 작성 규칙을 두고, AGENTS.md 에서 "복잡한 기능이나 큰 리팩터링은 ExecPlan 부터 쓴다" 고 가리키는 식이다. 이 방식으로 프롬프트 하나에 7시간 넘게 작업을 이어갔다는 사례도 있다.

Cursor 도 Plan 모드가 비슷한 plan.md 를 만들고, "이 계획대로 구현해" 로 넘기는 쓰임이 같다. Codex 도 /plan 이나 Shift+Tab 으로 Plan 모드에 들어갈 수 있다.

왜 생겼나

에이전트나 세션은 기억이 짧게 끊긴다. 긴 작업에서는 이런 일이 자주 생긴다.

• 중간에 컨텍스트가 잘려서 왜 이렇게 했는지 잊는다.
• 다음에 뭘 할지 사용자에게 다시 묻는다.
• 코드는 바뀌었는데 목적과 수락 기준은 채팅에만 남아서 검증이 흐려진다.
• 다른 사람이나 다음 에이전트가 이어받기 어렵다.

그래서 상태를 기억 못 하는 에이전트도, 저장소를 처음 보는 사람도 그 문서만 읽고 눈에 보이는 결과까지 만들 수 있게, 설계와 진행과 결정과 검증을 한곳에 묶는다.

• 자기 완결: 이전 채팅이나 외부 글 없이도 완주할 수 있다.
• 살아있는 문서: 진행, 발견, 결정이 바뀔 때마다 갱신한다.
• 결과 중심: "파일 추가" 가 아니라 "사용자가 무엇을 할 수 있게 되는지" 를 적는다.
• 평이한 언어: 전문 용어는 그 자리에서 풀어 쓴다.

어떻게 쓰나

1) 사용자가 큰 의도를 던짐
   "지도 목록 시트에 무한 스크롤 넣어줘"

2) Plan 모드 / 에이전트가 plan(ExecPlan) 초안 작성
   · 목적, 범위, 건드리는 파일, 마일스톤, 검증 방법

3) 사람이 계획 검토, 수정
   · 범위 줄이기, 마커는 건드리지 않기 등 결정 반영

4) "이 계획대로 구현"
   · 에이전트는 plan 을 지도 삼아 마일스톤 진행
   · Progress 체크, Decision Log 갱신

5) 검증, 머지
   · Acceptance 에 적힌 동작으로 확인

Cursor 에서 흔히 쓰는 패턴은 이렇다. Plan 모드로 설계만 하고 .cursor/plans/*.plan.md 를 만든다. 승인한 뒤 Agent 모드에서 "plan 그대로 구현, plan 파일은 편집하지 마" 로 넘긴다.

복잡한 작업일수록 plan 을 리뷰 가능한 계약서처럼 쓴다.

좋은 plan 에 들어가는 것

요점은 구현 지시서가 아니라 이어받을 수 있는 운영 문서라는 점이다.

예시

나쁜 계획은 지시만 있다.

filter.list.bottom.sheet 에 infinite query 달아라.

좋은 계획은 범위와 끝난 모습이 같이 있다.

지도 목록 BottomSheet 만 20건씩 이어 불러오게 한다. 마커 쿼리는 그대로 둔다. 끝나면 결과 100건인 조건에서 시트를 스크롤하면 카드가 계속 붙고, 정렬을 바꾸면 1페이지부터 다시 쌓이며, 지도 핀 동작은 이전과 같다.

앞의 것은 파일 단위 할 일이고, 뒤의 것은 제품 동작과 범위와 검증이 한 문서에 있다. 다른 세션이 이어받기 쉬운 건 뒤쪽이다.

한 줄로

plan 파일은 AI 코딩 에이전트가 여러 시간, 여러 턴에 걸쳐 구현할 때 쓰는 살아있는 실행 명세서다. 채팅 대신 다시 읽을 수 있는 계약서로 복잡한 일을 돌리려고 생긴 장치다.