워크플로

Codex는 명시적인 컨텍스트와 명확한 완료 기준이 있는 팀원처럼 다룰 때 가장 잘 작동합니다. 이 문서는 Codex IDE 확장, Codex CLI, Codex cloud를 위한 end-to-end 워크플로 예시를 제공합니다.

Codex가 처음이라면 먼저 프롬프트 작성을 읽고, 구체적인 recipe가 필요할 때 이 문서로 돌아오십시오.

예시 읽는 방법

각 워크플로는 다음을 포함합니다.

• 언제 사용할지와 어떤 Codex 표면이 가장 적합한지. IDE, CLI, cloud 중에서 선택합니다.
• 단계와 사용자 프롬프트 예시
• 컨텍스트 참고 사항: Codex가 자동으로 보는 것과 사용자가 첨부해야 하는 것
• 검증: 출력을 확인하는 방법

참고: IDE 확장은 열린 파일을 자동으로 컨텍스트에 포함합니다. CLI에서는 보통 경로를 명시적으로 언급하거나 /mention과 @ 경로 자동 완성으로 파일을 첨부해야 합니다.

코드베이스 설명

온보딩 중이거나, 서비스를 인수했거나, protocol, data model, request flow를 이해하려 할 때 사용합니다.

IDE 확장 워크플로

로컬 탐색에 가장 빠른 방법입니다.

1. 가장 관련 있는 파일을 엽니다.

2. 관심 있는 코드를 선택합니다. 선택 사항이지만 권장됩니다.

3. Codex에 프롬프트를 보냅니다.

   Explain how the request flows through the selected code.
   
   Include:
   - a short summary of the responsibilities of each module involved
   - what data is validated and where
   - one or two "gotchas" to watch for when changing this
   

검증:

• 빠르게 확인할 수 있는 diagram 또는 checklist를 요청합니다.

Summarize the request flow as a numbered list of steps. Then list the files involved.

CLI 워크플로

transcript와 셸 명령을 함께 남기고 싶을 때 좋습니다.

1. 대화형 세션을 시작합니다.

   codex
   

2. 파일을 첨부하고, 선택 사항입니다, 프롬프트를 보냅니다.

   I need to understand the protocol used by this service. Read @foo.ts @schema.ts and explain the schema and request/response flow. Focus on required vs optional fields and backward compatibility rules.
   

컨텍스트 참고:

• composer에서 @를 사용해 workspace의 파일 경로를 삽입하거나 /mention으로 특정 파일을 첨부할 수 있습니다.

버그 수정

로컬에서 재현할 수 있는 실패 동작이 있을 때 사용합니다.

CLI 워크플로

재현과 검증을 tight loop로 진행합니다.

1. 저장소 루트에서 Codex를 시작합니다.

   codex
   

2. 재현 절차와 의심되는 파일을 Codex에 제공합니다.

   Bug: Clicking "Save" on the settings screen sometimes shows "Saved" but doesn't persist the change.
   
   Repro:
   1) Start the app: npm run dev
   2) Go to /settings
   3) Toggle "Enable alerts"
   4) Click Save
   5) Refresh the page: the toggle resets
   
   Constraints:
   - Do not change the API shape.
   - Keep the fix minimal and add a regression test if feasible.
   
   Start by reproducing the bug locally, then propose a patch and run checks.
   

컨텍스트 참고:

• 사용자가 제공하는 것: 재현 단계와 제약. 고수준 설명보다 중요합니다.
• Codex가 제공하는 것: 명령 출력, 발견한 call site, 트리거한 stack trace.

검증:

• Codex는 수정 후 재현 단계를 다시 실행해야 합니다.
• 표준 check pipeline이 있다면 실행하도록 요청합니다.

After the fix, run lint + the smallest relevant test suite. Report the commands and results.

IDE 확장 워크플로

1. 버그가 있을 것 같은 파일과 가장 가까운 caller를 엽니다.

2. Codex에 프롬프트를 보냅니다.

   Find the bug causing "Saved" to show without persisting changes. After proposing the fix, tell me how to verify it in the UI.
   

테스트 작성

테스트 범위를 매우 명확하게 지정하고 싶을 때 사용합니다.

IDE 확장 워크플로

선택 영역을 기반으로 작업합니다.

1. 함수가 있는 파일을 엽니다.

2. 함수 정의 줄을 선택합니다. 명령 팔레트에서 "Add to Codex Thread"를 선택해 해당 줄을 컨텍스트에 추가합니다.

3. Codex에 프롬프트를 보냅니다.

   Write a unit test for this function. Follow conventions used in other tests.
   

컨텍스트 참고:

• "Add to Codex Thread" 명령이 제공하는 것: 선택한 줄, 즉 line number scope, 과 열린 파일입니다.

CLI 워크플로

프롬프트에서 경로와 line range를 설명합니다.

1. Codex를 시작합니다.

   codex
   

2. 함수 이름으로 프롬프트를 보냅니다.

   Add a test for the invert_list function in @transform.ts. Cover the happy path plus edge cases.
   

스크린샷에서 프로토타입 만들기

디자인 mock, 스크린샷, UI reference가 있고 빠르게 동작하는 prototype이 필요할 때 사용합니다.

CLI 워크플로

이미지와 프롬프트를 함께 사용합니다.

1. 스크린샷을 로컬에 저장합니다. 예: ./specs/ui.png.

2. Codex를 실행합니다.

   codex
   

3. 이미지 파일을 터미널로 드래그해 프롬프트에 첨부합니다.

4. 제약과 구조를 포함해 후속 프롬프트를 보냅니다.

   Create a new dashboard based on this image.
   
   Constraints:
   - Use react, vite, and tailwind. Write the code in typescript.
   - Match spacing, typography, and layout as closely as possible.
   
   Deliverables:
   - A new route/page that renders the UI
   - Any small components needed
   - README.md with instructions to run it locally
   

컨텍스트 참고:

• 이미지는 시각 요구 사항을 제공하지만, framework, routing, component style 같은 구현 제약은 텍스트로 지정해야 합니다.
• hover state, validation rule, keyboard interaction 같은 명확하지 않은 동작은 텍스트로 포함할수록 좋습니다.

검증:

• Codex에게 개발 서버를 실행하고, 허용되는 경우, 어디에서 prototype을 봐야 하는지 정확히 알려 달라고 요청합니다.

Start the dev server and tell me the local URL/route to view the prototype.

IDE 확장 워크플로

이미지와 기존 파일을 함께 사용합니다.

1. Codex 채팅에 이미지를 첨부합니다. drag-and-drop 또는 paste를 사용합니다.

2. Codex에 프롬프트를 보냅니다.

   Create a new settings page. Use the attached screenshot as the target UI.
   Follow design and visual patterns from other files in this project.
   

live update로 UI 반복

Codex가 코드를 편집하는 동안 "design -> tweak -> refresh -> tweak"에 가까운 loop를 원할 때 사용합니다.

CLI 워크플로

Vite를 실행한 뒤 작은 프롬프트로 반복합니다.

1. Codex를 시작합니다.

   codex
   

2. 별도 터미널 창에서 개발 서버를 시작합니다.

   npm run dev
   

3. Codex에게 변경 제안을 요청합니다.

   Propose 2-3 styling improvements for the landing page.
   

4. 방향을 고르고 작고 구체적인 프롬프트로 반복합니다.

   Go with option 2.
   
   Change only the header:
   - make the typography more editorial
   - increase whitespace
   - ensure it still looks good on mobile
   

5. 집중된 요청으로 반복합니다.

   Next iteration: reduce visual noise.
   Keep the layout, but simplify colors and remove any redundant borders.
   

검증:

• 코드가 업데이트되는 동안 브라우저에서 live로 변경 사항을 검토합니다.
• 마음에 드는 변경은 commit하고, 마음에 들지 않는 변경은 revert합니다.
• 변경을 revert하거나 수정했다면 Codex가 다음 프롬프트에서 그 변경을 덮어쓰지 않도록 알려 줍니다.

refactor를 cloud에 위임

먼저 신중하게 설계하고, 로컬 컨텍스트와 빠른 inspection을 사용한 뒤, 오래 걸리는 구현을 병렬 실행 가능한 cloud task로 맡기고 싶을 때 사용합니다.

로컬 계획(IDE)

1. 변경 사항을 깨끗하게 비교할 수 있도록 현재 작업을 commit하거나 최소한 stash합니다.

2. Codex에게 refactor 계획을 만들라고 요청합니다. $plan 스킬을 사용할 수 있으면 명시적으로 호출합니다.

   $plan
   
   We need to refactor the auth subsystem to:
   - split responsibilities (token parsing vs session loading vs permissions)
   - reduce circular imports
   - improve testability
   
   Constraints:
   - No user-visible behavior changes
   - Keep public APIs stable
   - Include a step-by-step migration plan
   

3. 계획을 검토하고 변경을 협의합니다.

   Revise the plan to:
   - specify exactly which files move in each milestone
   - include a rollback strategy
   

컨텍스트 참고:

• Codex가 현재 코드를 로컬에서 스캔할 수 있을 때 계획이 가장 잘 작동합니다. entrypoint, module boundary, dependency graph hint를 볼 수 있기 때문입니다.

cloud 위임

1. 아직 하지 않았다면 Codex cloud 환경을 설정합니다.

2. prompt composer 아래의 cloud 아이콘을 클릭하고 cloud 환경을 선택합니다.

3. 다음 프롬프트를 입력하면 Codex가 기존 스레드 컨텍스트, 계획과 로컬 소스 변경 포함, 를 이어받은 새 cloud 스레드를 만듭니다.

   Implement Milestone 1 from the plan.
   

4. cloud diff를 검토하고 필요하면 반복합니다.

5. cloud에서 직접 PR을 만들거나 변경 사항을 로컬로 받아 테스트하고 마무리합니다.

6. 계획의 추가 milestone을 반복합니다.

로컬 코드 리뷰

commit하거나 PR을 만들기 전에 추가 검토가 필요할 때 사용합니다.

CLI 워크플로

1. Codex를 시작합니다.

   codex
   

2. review 명령을 실행합니다.

   /review
   

3. 선택적으로 custom focus 지침을 제공합니다.

   /review Focus on edge cases and security issues
   

검증:

• 리뷰 피드백에 따라 수정한 뒤 /review를 다시 실행해 문제가 해결되었는지 확인합니다.

GitHub pull request 리뷰

브랜치를 로컬로 pull하지 않고 리뷰 피드백을 받고 싶을 때 사용합니다.

이 기능을 사용하려면 저장소에서 Codex Code review 를 활성화해야 합니다. Code review를 참고하십시오.

GitHub 워크플로

댓글로 구동합니다.

1. GitHub에서 pull request를 엽니다.

2. 명시적인 focus area와 함께 Codex를 태그하는 댓글을 남깁니다.

   @codex review
   

3. 선택적으로 더 명시적인 지침을 제공합니다.

   @codex review for security vulnerabilities and security concerns
   

문서 업데이트

정확하고 명확한 문서 변경이 필요할 때 사용합니다.

IDE 또는 CLI 워크플로

로컬 편집과 로컬 검증을 사용합니다.

1. 변경할 문서 파일을 식별하고 IDE에서 열거나 IDE/CLI에서 @로 멘션합니다.

2. 범위와 검증 요구 사항을 포함해 Codex에 프롬프트를 보냅니다.

   Update the "advanced features" documentation to provide authentication troubleshooting guidance. Verify that all links are valid.
   

3. Codex가 변경을 초안으로 만든 뒤 문서를 검토하고 필요에 따라 반복합니다.

검증:

• 렌더링된 페이지를 읽습니다.