지시사항을 분할하여 Codex로 효율적인 작업하기

이슈

Codex와 같은 AI 기반 코드 에이전트는 출력 토큰의 수가 제한되어 있다.

그래서 다양한 작업을 하나의 프롬프트에 전부 몰아서 작성하면 원하는 결과가 나오지 않을 수 있다.

Codex와 같은 LLM 기반 서비스는 출력 토큰 수를 초과하게 되면 일부 단계가 누락되거나 특정 요소를 과하게 요약할 수 있고 이는 전체적인 답변 퀄리티를 낮출 수 있기 때문이다.

그래서 다양한 AI 공식문서는 특정 작업을 더 작은 단위로 분할하는 방식을 강조한다.

이전에 Codex를 사용할 때는 다음과 같은 지시사항을 AGENTS.md 파일의 작업 가이드 항목에 작성했다. AI가 더 나은 방법을 선택해서 알아서 잘 작업하도록 지시하기 위함이었다.

• A: 주어진 요구사항에 대해서 단계적으로 작업을 분할한다. 각 단계마다 해결하는 방법을 조사한다.

• B: 각 단계마다 5가지 답변 방법을 우선 제시하고 요구사항을 제대로 해결할 수 있는 방법 하나를 선택한다.

• C: 방법 2개를 더 조사하여 B 단계에서 선택한 방법과 비교한다. 그리고 B와 C 단계를 여러 번 반복한다.

• D: 최후에 선택한 방법으로 작업한다.

한번 프롬프트를 실행시킬 때 너무 많은 작업을 지시하면 토큰 사용량이 증가하게 된다. 그리고 사용 시간 및 토큰 사용량에 비해서작업 결과가 만족스럽지 않은 때도 자주 발생했다. 예상과 다른 결과가 발생하여 작업 사항을 되돌려야 했던 상황도 있었다.

이 때에는 ChatGPT Plus 요금제를 사용하고 있었지만 일주일에 2일만 Codex를 사용해도 할당량을 초과하여 더 이상 작업에 사용할 수 없는 상태는 비정상적이라고 생각했다.

작업을 분할하기

AI에게 작업을 더 정확하게 지시하는 방법을 구하기 위해 여러 개발자분들의 조언을 구했다. 핵심은 작업의 단위를 AI가 이해할 수 있을 정도로 분할하는 것이었다.

이전까지는 AI에게 모든 걸 맡기려고 했다면 지금은 주어진 요구사항을 AI를 통해 단계식으로 나누고 각 단계마다 직접 프롬프트로 입력시켜보면서 단계별 작업 상황을 파악하는 방법을 사용한다.

AGENTS.md

Codex가 기본적으로 어떻게 작업해야 하는지에 대해서 기본적인 가이드라인을 작성할 수 있다.

## 작업 가이드

- 작업을 수행하기 전 네트워크 연결을 반드시 확인해주세요.
- 네트워크 연결되어있지 않으면 작업을 종료해주세요.
- 작업을 시작하기 전에 요구사항에 대해서 작업을 단계적으로 분할해주세요.
- 답변을 작성하거나 작업을 진행하기 전에 인터넷 검색 및 자료 조사로 교차검증해주세요. 양산형 컨텐츠 및 큐레이션 위주 블로그 게시물 보다는 공식문서와 실제로 존재하는 코드를 최우선적으로 참조해주세요.
- 현재 기준 최신순으로 자료를 조사해주세요.
- 확실하지 않은 부분을 발견하시면 즉시 세부 질문을 전달하시고 대기해주세요.

우선 인터넷 검색을 용이하게 하기 위해 네트워크 연결을 확인할 것을 요청했다.

교차 검증의 경우 잘못되거나 양산형 자료를 참조하는 것을 방지하기 위해 공식문서 및 소스 코드를 참고하라는 지시를 명시적으로 작성했다.

기능 개발 과정에서 내가 놓치는 것이 있을 수 있다. Codex로 작업을 진행할 때 모호한 부분을 발견하면 개발자가 세부 사항을 작성하도록 추가 지시사항을 작성했다.

프롬프트 플로우

특정 기능을 개발할 때는 우선 기능 개발을 하는 방법에 대해서 구체적으로 조사하고 단계적으로 정리한다.

기능 A를 우리 프로젝트에서 개발하는 방법을 조사해서 temps/feature-A.md 파일에 해당 내용을 단계식으로 작성해주세요.

이 프롬프트를 Codex에서 실행하면 temps/feature-A.md 파일에서 작성된 내용을 확인할 수 있다. 단계식으로 작성해달라는 지시를 프롬프트에 추가한 이유는 Codex가 각 단계마다 어떻게 작업해야 하는지 더 깊이있게 조사하도록 지시하기 위함이었다.

각 단계마다 실제 작업 순서를 작성할 때 Codex가 최적의 작업물을 낼 수 있는 작업 단위로 단계를 분할하도록 했다.

조사한 방법에 대해서 어떻게 작업해야 하는지 조사해주세요. 그리고 Codex가 최적의 결과를 낼 수 있는 작업 단위로 분할해주세요. 분할된 작업은 temps/example.md 파일에 작성해주세요.

위 프롬프트를 실행하면 CLI 창에 작업 단위 목록을 확인할 수 있다.

그 다음 첫 단계를 진행하라고 지시함과 동시에 각 단계를 완료할 때마다 결과를 요약하고 대기시킨다.

변경 사항을 직접 확인하고 고쳐야 할 부분이 있으면 추가로 수정하고 다음 단계를 진행하면 된다.

모호한 상황이 발생할 때마다 추가 지시사항을 제공하여 작업을 더욱 정확하게 할 수 있도록 한다.

예시

PC에서 사용하던 그림판을 웹 사이트로 구현하고 싶다고 가정한다.

Codex에는 다음과 같이 입력할 수 있다.

React와 Konva 라이브러리 기반으로 웹 브라우저에서 작동하는 그림판 기능을 개발하려고 합니다. 마이크로소프트의 그림판과 같은 기능을 리액트 + 타입스크립트 프론트엔드에서 제공하려면 어떻게 구현해야 하는지 조사해주시고 temps/canvas.md 파일에 정리해주세요.

Codex는 웹 프론트엔드에서 그림판을 구현하는 가이드를 파일 temps/canvas.md에 작성한다.

Codex가 작성한 리액트 컴포넌트 예시 코드는 별도의 지시가 없으면 컴포넌트 상태 관리에 useState, useEffect 등을 사용한다.

만약 useState가 아닌 useForm 등으로 최적화된 상태 관리를 구현하고 싶다면 다음과 같은 프롬프트를 작성할 수 있다.

현재 가이드에서는 useState와 같은 방법으로 입력 상태를 관리하는데 useForm과 같은 방법으로 입력 상태 관리를 최적화할 수 있는 방법이 없는지에 대해서 추가적으로 조사해주시고 temps/canvas.md 파일에 적용해주세요.

추가적인 가이드라인이 temps/canvas.md 파일에 작성된 것을 확인할 수 있다.

이제 이를 기반으로 더 세부적인 작업 단계를 세팅할 수 있다.

그럼 이제 temps/canvas.md 파일을 가지고 실제 프론트엔드 그림판을 구현하는 방법을 더 깊이있게 조사해주세요. 그리고 Codex가 작업에 대해 최적의 결과를 제공할 수 있는 작업 단위로 분할하여 temps/canvas-steps.md 파일에 작성해주세요.

temps/canvas-steps.md 파일에 작업 단계가 작성되면 이제 프롬프트를 입력하여 작업을 시작할 수 있다.

1단계부터 단계별로 작업을 시작해주세요. 각 단계가 끝나면 결과를 요약해주시고 대기해주세요.

반복 작업 방지

특정 언어에 대한 코드 컨벤션, 자기만의 코드 패턴, 안티 패턴을 방지할 수 있는 방법 등등 작업 관련 세부 사항은 별도의 파일로 분할하여 필요할 때에만 사용하도록 할 수 있다.

예를 들어 프론트엔드 프로젝트에 참여했을 때는 다음과 같은 지시사항 파일을 작성할 수 있다.

• registry

  • react-good-pattern.md 리액트 베스트 패턴 및 프랙티스

  • react-hook-form-best-pattern.md React Hook Form 관련 베스트 패턴 및 프랙티스

  • tanstack-query-best-pattern.md Tanstack Query 관련 베스트 패턴 및 프랙티스

  • typescript-best-case.md 타입스크립트 관련 베스트 패턴 및 프랙티스

  • ui-ux-guide.md UI UX 관련 베스트 패턴 및 프랙티스

  • use-form-with-query-client-guide.md 쿼리 클라이언트를 useForm과 함께 사용하여 API 데이터를 기본 값으로 제공하는 방법에 대한 참고자료

그리고 Codex를 시작할 때마다 참조 파일을 파악하도록 ~/.codex/prompts 폴더 내 따로 명령어를 작성할 수 있다.

예를 들어 ~/.codex/prompts/load_instructions.md 파일을 생성하고 다음과 같은 내용을 작성할 수 있다.

---

title: Load & Introspect AGENTS.md + Instruction Files
description: 프로젝트 루트의 AGENTS.md와 지시사항 md를 자동 탐색하고 파일 내 지시사항을 정확하게 파악합니다.
usage: |
/prompts:load-instructions registry
notes: |

- $1 인자가 있으면 프로젝트 내 $1 폴더를 스캔합니다.
- $1 인자가 있어도 폴더를 발견하는데 실패하면 에러를 반환합니다.

args:

- name: REGISTRY(Numeric Placeholder)
  label: The directory with instructions
  required: false
  default: registry
  description: 지시사항 파일들이 저장된 폴더

---

## 1) 스캔 대상 규칙

- **최우선**: 작업 중이신 프로젝트 폴더 최상단의 `AGENTS.md`를 찾고 읽으세요.
- 인자 해석:
  - $1가 비어있으면 AGENTS.md 파일만 파악합니다.
  - $1가 명시되고 해당 폴더가 프로젝트에 있으면 AGENTs.md 파일 및 폴더 내 모든 마크다운 파일(`$1/**/*.md`)를 스캔합니다.
  - $1가 명시되어도 해당 폴더가 프로젝트에 없으면 에러 메시지를 제공합니다.
- 포함: 지시사항 마크다운(`*.md`) — 예: `INSTRUCTIONS.md`, `*.rules.md`, `*.guide.md`
- 제외: 이 프롬프트 파일 자체, `LICENSE*`, `CHANGELOG*`, 일반 `README.md`(순수 안내)
- `AGENTS.md` 내 로컬 경로/링크가 지시파일을 가리키면 존재 시 추적 열람

## 2) 상호작용/오류 처리

- $1 인자가 있어도 해당 이름의 폴더가 존재하지 않으면 에러를 반환합니다.
- 폴더 내 파일이 하나도 존재하지 않으면 AGENTS.md 파일만 스캔합니다.
- 인코딩 또는 권한 관련 에러가 발생하면 에러가 발생한 파일 이름을 출력합니다.

## 3) 안전장치

- 어떤 코드/설정을 수정하거나 실행하지 않습니다. **읽기+지시사항 숙지** 전용.

파일을 저장하고 Codex를 다시 실행하여 다음과 같은 명령어가 작동하는지 확인할 수 있다.

아래 명령어는 우리 프로젝트의 registry 폴더 내 세부 지시사항 파일을 전부 조사하는데 사용할 수 있다.

/prompts:load-instructions registry