[Codex] Codex 프롬프트 공식

Step 1. Codex 프롬프트 공식 (GCCD)

Codex에 이렇게 물어보는 것은 초보적인 사용이다.

이 코드 고쳐줘.

 

조금 더 나은 방식이라고 하면

로그인 버그 고쳐줘.

정도이다.

 

하지만 앞으로 목표로 할 방식은 다음과 같다.

목표:
로그인 실패 시 사용자가 원인을 알 수 있도록 에러 처리를 개선해줘.

컨텍스트:
src/auth/login.ts
src/auth/authService.ts
tests/auth/

제약:
- 기존 public API는 변경하지 마.
- 새로운 dependency를 추가하지 마.
- 현재 프로젝트의 에러 처리 패턴을 먼저 확인하고 따라가.
- 불필요한 리팩터링은 하지 마.

완료 조건:
- 원인을 재현해.
- 수정해.
- 관련 테스트를 추가하거나 수정해.
- 테스트와 lint를 실행해.
- 마지막에 변경 파일과 변경 이유를 요약해.

 

이 구조가 중요하다.

• 목표(Goal) → 컨텍스트(Context) → 제약(Constraints) → 완료 조건(Done when)

공식 Codex 가이드에서 이 네 요소를 기본 프롬프트 구조로 권장하고 있다.

 

이것이 GCCD 공식이다.

[Goal / 목표]
무엇을 달성할 것인가?

[Context / 컨텍스트]
어떤 파일, 코드, 오류, 문서를 참고해야 하는가?

[Constraints / 제약]
무엇을 변경하면 안 되는가?
어떤 규칙을 따라야 하는가?

[Done / 완료 조건]
어떤 상태가 되면 작업 완료인가?
어떤 테스트/검증을 해야 하는가?

 

매번 네 항목을 전부 길게 작성할 필요는 없다.

예를 들어 아주 작은 수정은:

@src/utils/date.ts

formatDate()가 UTC가 아니라 local timezone을 사용하고 있어.

UTC 기준으로 수정해줘.
public API는 변경하지 말고 기존 테스트를 유지해.
관련 테스트를 실행해서 검증해.

정도로도 충분하다.

 

Step 2. 첫 번째 실습 — "바로 코드를 작성시키지 말고 읽게 하기"

처음 보는 프로젝트에서 곧바로 "코드 만들어"라고 하지 말고 먼저 Codex에게 코드를 읽게 한다.

 

VS Code에서 본인이 작업하는 Git 프로젝트 하나를 열고 Codex에 아래처럼 입력해본다.

이 코드베이스를 먼저 분석해줘. 아직 코드는 수정하지 마.

다음을 파악해줘.

1. 프로젝트의 목적
2. 주요 디렉터리 구조
3. 애플리케이션 시작 지점
4. 핵심 모듈과 각각의 역할
5. 데이터 흐름
6. 테스트 구조와 테스트 실행 방법
7. build / lint / test 명령
8. 내가 이 프로젝트에서 기능을 추가할 때 먼저 알아야 할 부분

추측하지 말고 실제 코드와 설정 파일을 확인해서 설명해줘.

마지막에는 이 프로젝트를 이해하기 위해 다음으로 읽어야 할 파일 5개를 중요도 순으로 제안해줘.

 

여기서 중요한 포인트는

아직 코드는 수정하지 마.

이다.

 

Codex를 사용할 때 "읽기 / 분석과 수정 / 실행"을 구분해서 사용하는 것이 좋다.

 

한 단계 더 강력하게 사용해보자.

Codex가 프로젝트 설명을 끝냈다면 바로 다음 프롬프트를 이어서 보내보자.

좋아.

이제 이 프로젝트의 개발자가 새로운 기능을 구현한다고 가정하자.

코드를 수정하지 말고 다음을 분석해줘.

- 이 프로젝트에서 반드시 지켜야 할 아키텍처 패턴
- 기존 코드에서 반복적으로 사용되는 구현 패턴
- 테스트 작성 패턴
- 에러 처리 패턴
- naming convention
- 내가 실수하기 쉬운 부분

각 항목마다 실제 파일을 근거로 설명해줘.

여기서부터 Codex가 단순한 코드 설명 AI에서 repository-aware 개발 에이전트로 바뀌기 시작한다.

Repository-Aware(저장소 인지형) 개발 에이전트란 저장소에 있는 프로젝트 전체를 파악한 상태에서 코드를 작성하고 수정하는 AI 에이전트를 의미한다.

 

Step 3. 이번 단계에서 반드시 익힐 3가지

1. Codex에게 파일을 보게 하라

VS Code에서 관련 파일을 열거나 코드를 선택하고 질문한다. VS Code에서 Codex 확장 프로그램은 열린 파일과 선택 코드를 컨텍스트로 사용할 수 있다.

 

2. 구현하기 전에 먼저 탐색시켜라

복잡한 작업이라면:

바로 수정하지 말고 먼저 관련 코드를 조사해줘.

를 적극 활용하자.

더 복잡해지면 Plan mode를 쓰게 된다. 공식 가이드 역시 복잡하거나 애매한 작업에서는 먼저 Plan mode를 통해 계획하도록 권장한다.

 

3. "코드 작성"에서 끝내지 말고 "검증까지" 시켜라

앞으로 프롬프트 끝에는 다음과 같은 문장을 붙이는 습관을 들이자.

구현 후 관련 테스트와 lint/typecheck를 실행해서 검증해.
실패하면 원인을 분석하고 수정해.
마지막에 변경 내용과 검증 결과를 요약해.

Codex 공식 가이드를 보면 코드 변경에서 끝내지 말고 테스트, lint/format/type check, 동작 확인, diff 리뷰까지 수행하도록 권장한다.

 

Step 4. 앞으로 목표로 하는 Codex 최종 사용 패턴

문제 전달
    ↓
Codex가 repo 탐색
    ↓
관련 코드/규칙 파악
    ↓
Plan 작성
    ↓
내가 방향 확인
    ↓
Codex가 구현
    ↓
test / lint / typecheck
    ↓
diff 자체 리뷰
    ↓
문제 발견 시 수정
    ↓
최종 변경 요약

나중에는 프로젝트 루트의 AGENTS.md에 개발 규칙, 테스트 명령, 금지 사항, 완료 조건 등을 넣어서 매번 긴 프롬프트를 작성하지 않아도 Codex가 자동으로 프로젝트 규칙을 따르게 만들 것이다.