OpenAI Cookbook: 코딩 에이전트가 몇 시간짜리 작업을 끝까지 하게 만드는 PLANS.md(ExecPlan) 작성법
리퀘오 운영팀
OpenAI Cookbook의 「PLANS.md로 몇 시간짜리 문제 풀기」 글을 한국어로 옮기고 핵심을 정리했습니다. 원문은 Codex 기준이지만, AGENTS.md나 지침 파일을 읽는 다른 코딩 에이전트에도 그대로 응용할 수 있는 방법입니다.
1. 무엇인가요
조사·설계·구현에 오래 걸리는 복잡한 작업을 코딩 에이전트에게 맡길 때, 먼저 '실행 계획서(ExecPlan)'를 쓰게 하고 그 계획서를 따라 구현하게 하는 방식입니다. 계획서는 꼼꼼한 설계 문서이자 작업하며 계속 고쳐 쓰는 '살아 있는 문서'입니다. 사용자는 긴 구현이 시작되기 전에 에이전트가 어떤 방식으로 갈지 계획서로 확인할 수 있습니다. 원문에 따르면 여기 소개하는 PLANS.md와 매우 비슷한 문서로 Codex가 프롬프트 하나로 7시간 넘게 작업했다고 합니다.
2. 준비: AGENTS.md에 규칙 한 줄
AGENTS.md는 코딩 에이전트에게 지침을 주는 간단한 형식입니다. 여기에 '언제 계획서를 쓰는지'를 적습니다.
예시)
# ExecPlans
복잡한 기능이나 큰 리팩터링을 할 때는 설계부터 구현까지 ExecPlan(.agent/PLANS.md에 정의)을 사용한다.
ExecPlan이라는 말은 임의로 붙인 이름이고 모델이 따로 학습한 용어가 아닙니다. 프롬프트에서 이 이름을 부르면 PLANS.md에 정의한 계획서 형식을 가리키게 하는 약속일 뿐입니다.
3. PLANS.md의 핵심 원칙
반드시 지킬 것
- 계획서는 완전히 자기 완결적이어야 합니다. 이 저장소를 처음 보는 초보자가 작업 폴더와 계획서 하나만 보고 끝까지 구현할 수 있어야 합니다. 이전 대화나 외부 문서를 기억한다고 가정하지 않습니다.
- 살아 있는 문서입니다. 진행하면서, 새로 알게 될 때마다, 설계를 정할 때마다 고치고, 고친 뒤에도 자기 완결적이어야 합니다.
- '정의를 맞춘 코드 변경'이 아니라 실제로 동작하는 결과를 내야 합니다.
- 전문 용어는 쉬운 말로 정의하거나 쓰지 않습니다.
쓰는 법
- 목적부터: 이 변경 뒤에 사용자가 무엇을 할 수 있게 되는지, 어떻게 확인하는지를 몇 문장으로 먼저 씁니다.
- 관찰 가능한 결과로 완료를 정의합니다. 'HealthCheck 구조체 추가'가 아니라 '서버를 띄우고 /health에 접속하면 HTTP 200과 OK가 나온다'처럼 사람이 확인할 수 있는 동작으로 씁니다.
- 파일은 저장소 기준 전체 경로로, 함수·모듈은 정확한 이름으로 적고, 명령은 실행 폴더와 정확한 명령줄을 함께 씁니다.
- 여러 번 실행해도 안전하게 씁니다. 중간에 실패할 수 있는 단계는 재시도 방법을, 파괴적인 작업은 백업·되돌리기 방법을 적습니다.
- 검증은 선택이 아닙니다. 시험 명령과 기대 결과(통과 개수, 오류 메시지)를 적어 초보자도 성공과 실패를 구분하게 합니다.
- 모호한 점은 독자에게 미루지 말고 계획서 안에서 정하고 이유를 적습니다.
- 목록보다 문장 위주로 씁니다. 체크리스트는 '진행 상황' 절에서만 씁니다.
구현할 때
- 에이전트는 '다음에 뭘 할까요?'라고 묻지 않고 다음 이정표로 넘어갑니다. 멈출 때마다 진행 상황을 갱신하고, 모호한 점은 스스로 정하고, 자주 커밋합니다.
- 어렵거나 불확실한 요구가 있으면 작은 시제품 이정표로 먼저 가능성을 확인합니다. 시제품은 범위를 밝히고, 채택·폐기 기준을 적습니다.
4. 계획서에 꼭 있어야 할 절
원문이 제시하는 계획서 뼈대는 이렇습니다.
- 목적 / 큰 그림: 무엇이 가능해지고 어떻게 확인하는지
- 진행 상황: 시각을 적은 체크박스 목록, 항상 실제 상태와 일치
- 뜻밖의 발견: 예상 못 한 동작·버그·성능 특성과 짧은 증거
- 결정 기록: 결정, 이유, 날짜·작성자
- 결과와 회고: 이룬 것, 남은 것, 배운 것
- 맥락과 위치: 처음 보는 사람 기준의 현재 상태, 핵심 파일 전체 경로
- 작업 계획: 어느 파일 어디를 어떻게 고칠지 문장으로
- 구체적 단계: 실행할 명령과 기대 출력
- 검증과 완료 기준: 입력과 출력으로 표현한 동작
- 반복 실행과 복구: 안전한 재시도·되돌리기
- 산출물과 메모: 성공을 증명하는 짧은 출력·변경 조각
- 인터페이스와 의존성: 쓸 라이브러리·모듈과 이유, 마지막에 있어야 할 함수 서명
원문이 정리한 기준은 이 한 줄입니다. 기억이 없는 에이전트 하나, 또는 사람 초보자가 계획서를 위에서 아래로 읽고 실제로 동작하는 결과를 낼 수 있어야 합니다. 계획을 고칠 때는 모든 절에 반영하고, 맨 아래에 무엇을 왜 바꿨는지 적습니다.
PLANS.md 전문은 아래 원문 링크에서 볼 수 있습니다. 자기 프로젝트에 맞게 절을 더하거나 빼서 쓰라고 원문도 권합니다. 여러분은 긴 작업을 에이전트에게 맡길 때 계획서를 따로 쓰나요? 쓰는 방식이 있다면 댓글로 나눠 주세요.
---
출처: OpenAI Cookbook 「PLANS.md로 몇 시간짜리 문제 풀기」
https://developers.openai.com/cookbook/articles/codex_exec_plans
저작권 고지(MIT 라이선스가 요구하는 원문 표기): Copyright (c) 2025 OpenAI · MIT 라이선스 https://github.com/openai/openai-cookbook/blob/main/LICENSE
변경 사항: 리퀘오 운영팀이 한국어로 번역하고 PLANS.md 본문은 핵심 원칙 위주로 요약·재구성했습니다. OpenAI가 이 번역을 보증하지 않습니다.
도움돼요 0 로그인하면 누를 수 있습니다. 로그인하면 저장하고 새 답글 알림을 받을 수 있습니다.