[AI] PLAN.md 몇 시간이 걸리는 복잡한 계획을 수행하는 프롬프트 (번역)

Codex 실행 계획(ExecPlans) 가이드라인

이 문서는 코딩 에이전트가 작동 가능한 기능이나 시스템 변경 사항을 전달하기 위해 따를 수 있는 설계 문서인 실행 계획(ExecPlan)의 요구 사항을 설명합니다. 독자를 이 저장소에 대한 완전한 초보자로 취급하십시오. 독자에게는 현재의 작업 트리(working tree)와 귀하가 제공하는 단일 ExecPlan 파일만 주어집니다. 이전 계획에 대한 기억이나 외부 컨텍스트는 존재하지 않는다고 가정합니다.

ExecPlan 및 PLANS.md 사용법

실행 가능한 명세서(ExecPlan)를 작성할 때는 PLANS.md의 내용을 문자 그대로 엄격히 준수하십시오. 만약 컨텍스트에 해당 파일이 없다면, PLANS.md 파일 전체를 읽어 기억을 되살리십시오. 정확한 명세를 작성하기 위해 소스 자료를 철저하게 읽고 또 읽으십시오. 명세를 만들 때는 골격(Skeleton)에서 시작하여 조사를 진행함에 따라 내용을 채워 넣으십시오.

 

실행 가능한 명세(ExecPlan)를 구현할 때, 사용자에게 "다음 단계"를 묻지 말고 즉시 다음 마일스톤으로 진행하십시오. 모든 섹션을 최신 상태로 유지하고, 중단 지점마다 목록에 항목을 추가하거나 분할하여 진행 상황과 다음 단계를 명확히 밝히십시오. 모호함은 자율적으로 해결하고, 빈번하게 커밋하십시오.

 

ExecPlan에 대해 논의할 때, 후세를 위해 결정 사항을 명세 내의 로그에 기록하십시오. 명세가 변경된 이유는 모호함 없이 명확해야 합니다. ExecPlan은 살아있는 문서(living document)이며, 오직 ExecPlan 하나만 가지고 다른 작업 없이도 언제든 다시 시작할 수 있어야 합니다.

 

까다로운 요구 사항이나 불확실성이 큰 설계를 조사할 때는 마일스톤을 사용해 개념 증명(PoC)이나 "토이 구현(toy implementations)" 등을 수행하여 사용자의 제안이 실현 가능한지 검증하십시오. 라이브러리를 찾아 소스 코드를 읽고 깊이 있게 연구하며, 완전한 구현을 가이드할 수 있는 프로토타입을 포함하십시오.

요구 사항

타협 불가능한 요구 사항:

• 모든 ExecPlan은 완전히 자기 완결적(self-contained)이어야 합니다. 자기 완결적이란 현재 형태 그대로 초보자가 성공하는 데 필요한 모든 지식과 지침을 포함하고 있음을 의미합니다.
• 모든 ExecPlan은 살아있는 문서입니다. 기여자는 진행 상황, 발견 사항 및 확정된 설계 결정에 따라 이를 수정해야 합니다. 각 수정본은 여전히 완전히 자기 완결적이어야 합니다.
• 모든 ExecPlan은 초보자가 이 저장소에 대한 사전 지식 없이도 기능을 처음부터 끝까지 구현할 수 있게 해야 합니다.
• 모든 ExecPlan은 단순히 "정의를 충족하는" 코드 변경이 아니라, 입증 가능하게 작동하는 동작을 생성해야 합니다.
• 모든 ExecPlan은 전문 용어를 사용할 경우 쉬운 언어로 정의하거나, 아예 사용하지 말아야 합니다.

목적과 의도가 최우선입니다. 먼저 이 작업이 사용자 관점에서 왜 중요한지 몇 문장으로 설명하십시오. 이 변경 후에 사용자가 이전에는 할 수 없었던 무엇을 할 수 있는지, 그리고 그것이 작동하는 것을 어떻게 확인할 수 있는지 설명하십시오. 그런 다음 수정할 내용, 실행할 내용, 관찰해야 할 내용을 포함하여 해당 결과를 달성하기 위한 정확한 단계를 안내하십시오.

 

계획을 실행하는 에이전트는 파일 목록 확인, 파일 읽기, 검색, 프로젝트 실행 및 테스트 실행을 할 수 있습니다. 에이전트는 이전 컨텍스트를 전혀 모르며 이전 마일스톤에서 당신이 의미한 바를 추론할 수 없습니다. 의존하는 모든 가정은 반복해서 명시하십시오. 외부 블로그나 문서로 링크를 걸지 마십시오. 지식이 필요하다면 계획 자체에 본인의 언어로 포함시키십시오. ExecPlan이 이전 ExecPlan을 기반으로 하고 해당 파일이 체크인되어 있다면 참조로 포함하십시오. 그렇지 않다면 해당 계획의 모든 관련 컨텍스트를 포함해야 합니다.

형식 (Formatting)

형식과 봉투(envelope)는 단순하고 엄격합니다. 각 ExecPlan은 md로 표시된 단일 코드 블록이어야 하며, 세 개의 백틱(```)으로 시작하고 끝나야 합니다. 내부에 추가적인 백틱 코드 펜스를 중첩하지 마십시오. 명령어, 기록(transcripts), diff 또는 코드를 보여줘야 할 때는 단일 펜스 내에서 들여쓰기 된 블록으로 제시하십시오.

 

ExecPlan의 코드 펜스가 조기에 닫히는 것을 방지하기 위해 코드 펜스 대신 들여쓰기를 사용하십시오. 모든 헤딩 뒤에는 두 개의 줄 바꿈을 사용하고, # 및 ## 등을 사용하며, 번호 매기기 및 글머리 기호 목록의 구문을 정확히 맞추십시오.

파일 내용이 오직 단일 ExecPlan인 Markdown(.md) 파일에 작성할 때는 세 개의 백틱을 생략해야 합니다.

 

평이한 산문체로 작성하십시오. 목록보다는 문장을 선호하십시오. 간결함이 의미를 가릴 정도가 아니라면 체크리스트, 표, 긴 나열은 피하십시오. 체크리스트는 필수 사항인 Progress(진행 상황) 섹션에서만 허용됩니다. 서사적인 섹션은 산문 중심이어야 합니다.

가이드라인

자기 완결성과 평이한 언어가 가장 중요합니다. 일반적인 영어가 아닌 문구("daemon", "middleware", "RPC gateway", "filter graph" 등)를 도입한다면 즉시 정의하고, 이 저장소에서 어떻게 나타나는지(예: 관련 파일 이름이나 명령어 제시) 독자에게 상기시키십시오. "이전에 정의된 바와 같이" 또는 "아키텍처 문서에 따라"라고 말하지 마십시오. 반복되더라도 필요한 설명을 여기에 포함하십시오.

 

흔한 실패 사례를 피하십시오. 정의되지 않은 전문 용어에 의존하지 마십시오. 기능의 "문구"에만 너무 좁게 집중하여 코드는 컴파일되지만 의미 있는 동작은 하지 않는 결과를 초래하지 마십시오. 핵심 결정을 독자에게 떠넘기지 마십시오. 모호함이 존재할 때는 계획 자체에서 해결하고 왜 그 경로를 선택했는지 설명하십시오. 사용자에게 보이는 효과는 과할 정도로 설명하고, 부수적인 구현 세부 사항은 가볍게 명시하십시오.

 

관찰 가능한 결과에 계획의 중심을 두십시오. 구현 후 사용자가 할 수 있는 일, 실행할 명령어, 예상되는 출력을 기술하십시오. 수락 기준은 내부 속성("HealthCheck 구조체 추가")이 아니라 인간이 검증할 수 있는 동작("서버 시작 후 http://localhost:8080/health 접속 시 HTTP 200과 바디 OK 반환")으로 표현되어야 합니다. 변경 사항이 내부적인 것이라면, 그 영향이 어떻게 입증될 수 있는지 설명하십시오 (예: 변경 전에는 실패하고 변경 후에는 통과하는 테스트 실행, 새로운 동작을 사용하는 시나리오 제시 등).

 

저장소 컨텍스트를 명시적으로 지정하십시오. 파일 이름은 저장소 루트 기준의 전체 경로로 기재하고, 함수와 모듈의 이름을 정확히 명명하며, 새 파일이 생성될 위치를 설명하십시오. 여러 영역을 다루는 경우 초보자가 확신을 가지고 탐색할 수 있도록 각 부분이 어떻게 결합되는지 설명하는 짧은 오리엔테이션 단락을 포함하십시오. 명령어를 실행할 때는 작업 디렉토리와 정확한 명령줄을 보여주십시오. 결과가 환경에 의존하는 경우 가정을 명시하고 합리적인 대안을 제공하십시오.

 

멱등성(Idempotent)과 안전성을 유지하십시오. 단계를 여러 번 실행해도 손상이나 드리프트(drift)가 발생하지 않도록 작성하십시오. 단계가 중간에 실패할 수 있는 경우 재시도 또는 적응 방법을 포함하십시오. 마이그레이션이나 파괴적인 작업이 필요한 경우 백업이나 안전한 폴백(fallback)을 상세히 설명하십시오. 진행하면서 검증할 수 있는 추가적이고 테스트 가능한 변경 사항을 선호하십시오.

 

검증은 선택 사항이 아닙니다. 테스트를 실행하고, 해당하는 경우 시스템을 시작하며, 시스템이 유용한 작업을 수행하는지 관찰하기 위한 지침을 포함하십시오. 새로운 기능이나 역량에 대한 포괄적인 테스트를 기술하십시오. 초보자가 성공과 실패를 구분할 수 있도록 예상 출력과 오류 메시지를 포함하십시오. 가능하면 컴파일 이상의 효과를 증명하는 방법(예: 소규모 엔드 투 엔드 시나리오, CLI 호출, HTTP 요청/응답 기록 등)을 보여주십시오. 프로젝트의 툴체인에 적합한 정확한 테스트 명령어와 결과를 해석하는 방법을 명시하십시오.

 

증거를 기록하십시오. 단계에서 터미널 출력, 짧은 diff 또는 로그가 생성되면 단일 펜스 블록 내에 들여쓰기 된 예시로 포함하십시오. 간결함을 유지하고 성공을 증명하는 내용에 집중하십시오. 패치를 포함해야 할 경우, 거대한 덩어리를 붙여넣기보다 독자가 지침을 따라 재현할 수 있는 파일 단위의 diff나 짧은 발췌본을 선호하십시오.

마일스톤 (Milestones)

마일스톤은 관료적인 절차가 아니라 서사입니다. 작업을 마일스톤으로 나누는 경우, 각 마일스톤의 범위, 마일스톤이 끝났을 때 이전에는 없었던 무엇이 존재하게 되는지, 실행할 명령어, 예상되는 수락 기준을 설명하는 짧은 단락으로 시작하십시오. 목표, 작업, 결과, 증명이라는 하나의 이야기처럼 읽힐 수 있게 하십시오. 진행 상황(Progress)과 마일스톤은 별개입니다. 마일스톤은 이야기를 들려주고, 진행 상황은 세부 작업을 추적합니다. 둘 다 존재해야 합니다. 단순히 간결함을 위해 마일스톤을 축약하지 마십시오. 향후 구현에 중요할 수 있는 세부 사항을 누락하지 마십시오.

각 마일스톤은 독립적으로 검증 가능해야 하며 실행 계획의 전체 목표를 점진적으로 구현해야 합니다.

살아있는 계획 및 설계 결정

• ExecPlan은 살아있는 문서입니다. 주요 설계 결정을 내릴 때, 결정 내용과 그 뒤에 숨겨진 사고 과정을 모두 기록하도록 계획을 업데이트하십시오. 모든 결정은 Decision Log(결정 로그) 섹션에 기록하십시오.
• ExecPlan은 Progress(진행 상황), Surprises & Discoveries(놀라운 점 및 발견 사항), Decision Log(결정 로그), Outcomes & Retrospective(결과 및 회고) 섹션을 반드시 포함하고 유지해야 합니다. 이는 선택 사항이 아닙니다.
• 최적화 도구의 동작, 성능 트레이드오프, 예기치 않은 버그 또는 접근 방식에 영향을 준 반대/취소 의미론(semantics)을 발견하면, 해당 관찰 내용을 Surprises & Discoveries 섹션에 짧은 증거 스니펫(테스트 출력이 이상적임)과 함께 기록하십시오.
• 구현 도중 방향을 바꾸는 경우 Decision Log에 이유를 문서화하고 Progress에 그 영향을 반영하십시오. 계획은 당신을 위한 체크리스트인 동시에 다음 기여자를 위한 가이드입니다.
• 주요 작업이나 전체 계획이 완료되면 달성된 사항, 남은 과제, 배운 교훈을 요약한 Outcomes & Retrospective 항목을 작성하십시오.

프로토타이핑 마일스톤 및 병렬 구현

대규모 변경의 리스크를 줄이기 위해 명시적인 프로토타이핑 마일스톤을 포함하는 것은 허용되며 종종 권장됩니다. 예: 실현 가능성 검증을 위해 종속성에 저수준 연산자 추가, 또는 최적화 효과를 측정하면서 두 가지 구성 순서 탐색 등. 프로토타입은 추가적이고 테스트 가능하게 유지하십시오. 범위를 "프로토타이핑"으로 명확히 표시하고, 실행 및 결과 관찰 방법을 설명하며, 프로토타입을 채택하거나 폐기하기 위한 기준을 명시하십시오.

 

테스트가 계속 통과되도록 하는 추가적인 코드 변경을 먼저 하고 나중에 삭제하는 방식을 선호하십시오. 마이그레이션 중에 이전 경로와 함께 어댑터를 유지하는 것과 같은 병렬 구현은 리스크를 줄이거나 대규모 마이그레이션 중에도 테스트가 계속 통과될 수 있게 한다면 괜찮습니다. 두 경로를 모두 검증하는 방법과 테스트를 통해 한 경로를 안전하게 제거하는 방법을 설명하십시오. 여러 개의 새로운 라이브러리나 기능 영역을 다룰 때는, 이러한 기능들의 실현 가능성을 서로 독립적으로 평가하는 '스파이크(spikes)'를 만드는 것을 고려하십시오. 이를 통해 외부 라이브러리가 예상대로 작동하고 우리가 필요한 기능을 격리된 상태에서 구현하는지 증명하십시오.

좋은 ExecPlan의 골격

# <짧고 행동 중심적인 설명>

이 ExecPlan은 살아있는 문서입니다. `Progress`, `Surprises & Discoveries`, `Decision Log`, `Outcomes & Retrospective` 섹션은 작업이 진행됨에 따라 최신 상태로 유지되어야 합니다.

PLANS.md 파일이 저장소에 체크인되어 있다면, 저장소 루트로부터의 해당 파일 경로를 여기에 참조하고 이 문서가 PLANS.md에 따라 유지되어야 함을 명시하십시오.

## 목적 / 큰 그림 (Purpose / Big Picture)

이 변경 후에 무엇을 얻게 되는지, 그리고 그것이 작동하는 것을 어떻게 볼 수 있는지 몇 문장으로 설명하십시오. 활성화할 사용자 가시적 동작을 명시하십시오.

## 진행 상황 (Progress)

체크박스가 있는 목록을 사용하여 세부 단계를 요약하십시오. 중단 지점은 모두 여기에 기록되어야 하며, 필요하다면 부분적으로 완료된 작업을 두 개로 분할하십시오("완료" vs "남음"). 이 섹션은 항상 실제 현재 작업 상태를 반영해야 합니다.

- [x] (2025-10-01 13:00Z) 완료된 단계 예시.
- [ ] 미완료 단계 예시.
- [ ] 부분 완료된 단계 예시 (완료: X, 남음: Y).

진행 속도를 측정하기 위해 타임스탬프를 사용하십시오.

## 놀라운 점 및 발견 사항 (Surprises & Discoveries)

구현 중 발견된 예기치 않은 동작, 버그, 최적화 또는 통찰력을 문서화하십시오. 간결한 증거를 제시하십시오.

- 관찰: …
증거: …

## 결정 로그 (Decision Log)

계획 작업 중 내린 모든 결정을 다음 형식으로 기록하십시오:

- 결정: …
근거: …
날짜/작성자: …

## 결과 및 회고 (Outcomes & Retrospective)

주요 마일스톤이나 완료 시점에 결과, 공백, 배운 교훈을 요약하십시오. 결과를 원래 목적과 비교하십시오.

## 컨텍스트 및 오리엔테이션 (Context and Orientation)

독자가 아무것도 모른다고 가정하고 이 작업과 관련된 현재 상태를 설명하십시오. 주요 파일과 모듈을 전체 경로로 명명하십시오. 사용할 명확하지 않은 용어를 정의하십시오. 이전 계획을 참조하지 마십시오.

## 작업 계획 (Plan of Work)

수정 및 추가 순서를 산문체로 설명하십시오. 각 수정에 대해 파일 이름과 위치(함수, 모듈) 및 삽입하거나 변경할 내용을 명시하십시오. 구체적이고 최소한으로 유지하십시오.

## 구체적 단계 (Concrete Steps)

실행할 정확한 명령어와 실행 위치(작업 디렉토리)를 명시하십시오. 명령어가 출력을 생성하는 경우 독자가 비교할 수 있도록 짧은 예상 기록을 보여주십시오. 이 섹션은 작업이 진행됨에 따라 업데이트되어야 합니다.

## 검증 및 수락 (Validation and Acceptance)

시스템을 시작하거나 실행하는 방법과 관찰할 내용을 설명하십시오. 수락 기준을 구체적인 입력과 출력이 있는 동작으로 표현하십시오. 테스트가 포함된 경우 "<프로젝트 테스트 명령어>를 실행하고 <N>개 통과를 예상함; 새로운 테스트 <이름>은 변경 전에는 실패하고 변경 후에는 통과함"이라고 명시하십시오.

## 멱등성 및 복구 (Idempotence and Recovery)

단계를 안전하게 반복할 수 있다면 그렇게 명시하십시오. 단계가 위험하다면 안전한 재시도 또는 롤백 경로를 제공하십시오. 완료 후 환경을 깨끗하게 유지하십시오.

## 산출물 및 참고 사항 (Artifacts and Notes)

가장 중요한 기록, diff 또는 스니펫을 들여쓰기 된 예시로 포함하십시오. 간결함을 유지하고 성공을 증명하는 내용에 집중하십시오.

## 인터페이스 및 종속성 (Interfaces and Dependencies)

규정적으로 작성하십시오. 사용할 라이브러리, 모듈, 서비스를 이름 짓고 그 이유를 밝히십시오. 마일스톤이 끝날 때 존재해야 하는 유형(types), 트레이트/인터페이스, 함수 시그니처를 지정하십시오. `crate::module::function` 또는 `package.submodule.Interface`와 같은 안정적인 이름과 경로를 선호하십시오. 예:

crates/foo/planner.rs에서 다음을 정의함:

pub trait Planner {
fn plan(&self, observed: &Observed) -> Vec<Action>;
}

 

위의 지침을 따르면 단일한 상태 비보존형(stateless) 에이전트나 초보자도 귀하의 ExecPlan을 위에서 아래로 읽고 작동하며 관찰 가능한 결과를 만들어낼 수 있습니다. 그것이 기준입니다: 자기 완결적, 자기 충분적, 초보자 가이드형, 결과 중심적.

 

계획을 수정할 때는 살아있는 문서 섹션을 포함한 모든 섹션에 변경 사항이 종합적으로 반영되었는지 확인해야 하며, 계획 하단에 변경 내용과 이유를 설명하는 노트를 작성해야 합니다. ExecPlan은 거의 모든 항목에 대해 '무엇'뿐만 아니라 '왜'를 설명해야 합니다.

 

 

openai-cookbook/articles/codex_exec_plans.md at main · openai/openai-cookbook