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

## 이슈

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

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

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

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

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

* A: 주어진 요구사항에 대해서 단계적으로 작업을 분할한다. 각 단계마다 해결하는 방법을 조사한다.
    
* B: 각 단계마다 5가지 답변 방법을 우선 제시하고 요구사항을 제대로 해결할 수 있는 방법 하나를 선택한다.
    
* C: 방법 2개를 더 조사하여 B 단계에서 선택한 방법과 비교한다. 그리고 B와 C 단계를 여러 번 반복한다.
    
* D: 최후에 선택한 방법으로 작업한다.
    

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

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

## 작업을 분할하기

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

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

## [AGENTS.md](http://AGENTS.md)

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

```md
## 작업 가이드

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

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

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

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

## 프롬프트 플로우

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

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

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

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

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

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

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

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

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

## 예시

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

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

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

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

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

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

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

추가적인 가이드라인이 `temps/`[`canvas.md`](http://canvas.md) 파일에 작성된 것을 확인할 수 있다.

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

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

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

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

## 반복 작업 방지

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

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

* registry
    
    * [react-good-pattern.md](http://react-good-pattern.md) 리액트 베스트 패턴 및 프랙티스
        
    * [react-hook-form-best-pattern.md](http://react-hook-form-best-pattern.md) React Hook Form 관련 베스트 패턴 및 프랙티스
        
    * [tanstack-query-best-pattern.md](http://tanstack-query-best-pattern.md) Tanstack Query 관련 베스트 패턴 및 프랙티스
        
    * [typescript-best-case.md](http://typescript-best-case.md) 타입스크립트 관련 베스트 패턴 및 프랙티스
        
    * [ui-ux-guide.md](http://ui-ux-guide.md) UI UX 관련 베스트 패턴 및 프랙티스
        
    * [use-form-with-query-client-guide.md](http://use-form-with-query-client-guide.md) 쿼리 클라이언트를 useForm과 함께 사용하여 API 데이터를 기본 값으로 제공하는 방법에 대한 참고자료
        

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

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

```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 폴더 내 세부 지시사항 파일을 전부 조사하는데 사용할 수 있다.

```bash
/prompts:load-instructions registry
```