ask-codex은(는) 무엇을 하나요?

OpenAI의 코딩 에이전트 Codex를 codex exec(비대화형 모드)로 호출하여 설계/구현 상담, 심층 조사, 코드 리뷰를 요청하는 스킬입니다.

Codex는 끈기 있게 조사하여 정확도를 높이는 경향이 있으므로, 두 번째 의견이나 정확성이 중요한 심층 조사에 적합합니다.

Codex는 매번 콜드 스타트하며, 현재 대화/계획/이전 조사 결과를 전혀 알지 못합니다. 전제/의도/제약/관련 파일은 매번 프롬프트에 명시하세요 (아래 "작업문 작성법"과 예시 참조).

전제 조건

codex CLI가 설치 및 인증되어 있어야 합니다 (codex --version으로 확인 가능).
인증이 만료된 경우 Codex 측 설정이 필요하므로, 이 사실을 사용자에게 알립니다.

실행 전

Codex를 호출하기 전에 무엇을 상담할 것인지 한 줄로 사용자에게 알립니다. 승인을 기다릴 필요는 없으며, 전달한 후 바로 실행해도 됩니다.

기본 호출 패턴

Codex는 읽기 전용 상위 리뷰어이므로 -s read-only를 기본값으로 설정합니다. 프롬프트는 셸 이스케이프를 피하기 위해 stdin 경유(codex exec -)로 전달합니다.

핵심 방식은 두 가지입니다.

답변 추출(cat)을 Codex 호출과 같은 명령어 내에서 완결합니다. OUT=$(mktemp ...)의 $OUT은 다음 셸 호출(다른 셸)에서 사라지므로, 후속 Read로 읽으려고 하면 경로를 잃습니다. 같은 명령어 내에서 cat하면 동작을 전혀 가정하지 않고 확실하게 답변을 얻을 수 있습니다.
Codex 본체의 stdout/stderr를 컨텍스트에 흘리지 않습니다. Codex는 진행 로그/헤더/경고/hook/마지막 에코/tokens used를 stderr로, 최종 메시지만 stdout과 -o 파일로 출력합니다 ("무엇을 했는지 / 생각했는지"는 모두 stderr 쪽). 결론만 필요하므로, stdout은 버리고 stderr는 임시 파일로 보내 실패 시에만 출력합니다. 이렇게 하면 tool result에는 cat "$OUT"의 최종 메시지만 들어가고, 인증 만료/무효 플래그 등의 오류 원인은 실패 시에 확인할 수 있습니다.

용도에 따라 두 가지 정규 레시피로 나눕니다.

A. 짧은 상담/작은 리뷰 (포그라운드)

답변(최종 메시지만)이 셸 실행의 tool result로 반환됩니다. 추가 Read는 필요하지 않습니다.

OUT=$(mktemp /tmp/codex_answer.XXXXXX.txt)
ERR=$(mktemp /tmp/codex_err.XXXXXX.txt)
printf '%s' "$PROMPT" | codex exec - -s read-only -C <DIR> -o "$OUT" >/dev/null 2>"$ERR" \
  || { echo "codex failed:"; cat "$ERR"; exit 1; }
cat "$OUT"

B. 시간이 오래 걸리는 호출 (백그라운드)

codex exec은 몇 분이 걸릴 수 있으며, 포그라운드 실행은 환경에 따라 중단될 수 있습니다. 심층 조사나 codex exec review를 통한 코드 리뷰 등 오래 걸릴 작업은 자신의 하네스 백그라운드 실행 메커니즘으로 보냅니다 (지정 방법은 하네스 측에 위임). 명령어 본체는 용도에 따라 codex exec - (상담/조사) 또는 codex exec review (diff 리뷰, 후술)를 사용합니다.

OUT=$(mktemp /tmp/codex_answer.XXXXXX.txt)
ERR=$(mktemp /tmp/codex_err.XXXXXX.txt)
printf '%s' "$PROMPT" | codex exec - -s read-only -C <DIR> -o "$OUT" >/dev/null 2>"$ERR" \
  || { echo "codex failed:"; cat "$ERR"; exit 1; }
echo "=== ANSWER ==="; cat "$OUT"

완료되면 하네스가 완료 알림을 보내고, 해당 백그라운드 출력에 === ANSWER === 이후의 답변이 포함됩니다. 그 출력을 Read합니다 (긴 경우 === ANSWER === 이후를 Grep해도 됩니다). sleep/pgrep으로 폴링하는 루프를 직접 만들지 마십시오 (하네스가 완료를 알립니다).

플래그의 의미

codex exec -: stdin에서 프롬프트를 읽습니다. 긴 문장/코드 블록/특수 문자를 안전하게 전달할 수 있습니다.
-s read-only: 읽기만 허용합니다. 이 스킬에서는 기본적으로 이 플래그를 붙입니다 (조언/리뷰 역할이므로 쓰기는 불필요). CLI/config 자체의 기본값이 아닙니다. codex exec 전용이며, codex exec review에는 없습니다 (붙이면 에러).
-C <DIR>: codex exec의 작업 루트 디렉터리입니다. 조사/리뷰 대상 리포지토리를 가리킵니다. 생략 시 현재 디렉터리입니다. codex exec review에는 -C가 없으므로, review는 동일 명령어 내에서 cd <DIR>한 후 호출합니다 (후술).
-o <FILE>: Codex의 최종 메시지만 이 파일에 씁니다. 완료 시에만 작성되므로 (실행 중에는 비어 있음), 완료 전에 읽지 마십시오. 정규 레시피에서는 이 파일을 답변의 소스로 사용합니다.
stdout: Codex는 최종 메시지를 stdout에도 출력하지만, 정규 레시피에서는 -o에서 가져오므로 >/dev/null로 버립니다 (중복 게재 방지 및 컨텍스트 절약).
stderr: 진행 로그/헤더/경고/hook/마지막 에코/tokens used, 그리고 에러(인증 만료/무효 플래그/repo check 실패 등)가 출력됩니다. 2>/dev/null로 단순히 버리면 cat "$OUT"이 비어 있을 때 원인을 알 수 없으므로, 임시 파일($ERR)로 보내고 실패 시에만 cat "$ERR"합니다. 성공 시에는 컨텍스트에 들어가지 않고, 실패 시에만 원인을 확인할 수 있습니다.
mktemp /tmp/codex_answer.XXXXXX.txt: 끝의 XXXXXX가 랜덤으로 치환되어 충돌하지 않는 고유 경로를 생성합니다. 병렬로 여러 개를 보내는 경우에도 호출마다 별도의 mktemp가 생성됩니다.

일반적으로 필요하지 않은 옵션

--skip-git-repo-check: git 리포지토리 외부에서 실행할 때만 필요합니다. 리포지토리 내라면 붙이지 않습니다.
-s workspace-write: Codex가 편집하도록 할 때만 사용합니다. 이 스킬의 가정(read-only reviewer)에서 벗어나므로, 원칙적으로 사용하지 않습니다.

모델 지정

특정 모델을 사용하려면 -m <MODEL> (예: -m gpt-5.5)을 추가합니다. 지정이 없으면 Codex의 설정 기본값을 따릅니다. 무분별하게 지정하지 말고, 사용자의 요청이 있을 때만 붙입니다.

웹 검색

~/.codex/config.toml에 web_search = "live"가 설정되어 있으면, Codex는 웹 검색을 사용할 수 있습니다. 웹 검색은 Responses의 네이티브 도구이므로 -s read-only (셸 실행만 제한)로도 막히지 않습니다. 라이브러리/API/CLI의 구체적인 사양을 확인하게 하려면 프롬프트에 "공식 문서를 웹 검색으로 확인해"라고 명시합니다. codex exec 자체에 --search 플래그는 없으며, config의 web_search로 제어합니다.

도움말 표시

codex exec -h로 도움말을 표시할 수 있습니다.

작업문 작성법

LLM은 예제를 따르는 데 능숙하므로, 아래 각 예시에서 printf에 전달하는 프롬프트 본문을 그대로 좋은 작업문의 견본으로 사용합니다. 한 번의 상담을 하나의 판단/리뷰/계획/조사로 좁히고, 다음을 하나의 프롬프트에 포함시킵니다.

의도/배경/제약: Codex는 콜드 스타트이므로, 무엇을 하고 싶은지/이유/전제를 반드시 작성합니다.
관련 파일: @path/to/file로 인라인으로 표시합니다. 현재 변경 사항을 보고 싶다면 "git diff로 차이점을 확인해"라고 명시합니다.
착안점/비교할 대안/찾아야 할 리스크를 구체적으로 작성합니다.
출력 형태를 지정합니다 (순위가 매겨진 리스크 / 트레이드오프 테이블 / 권장 계획 변경 등).
무시할 사항 (네이밍/포맷팅 등)을 작성하여 scope creep을 방지합니다.
외부 사양 확인이 필요하면 "공식 문서를 웹 검색으로 확인해"라고 명시합니다.
리뷰는 의도 → 구현 순서로 진행하도록 합니다 (먼저 의도에 비추어 타당한지, 그다음 구현).

프롬프트 본문은 printf '%s' '…'와 같이 작은따옴표로 감싸면 본문의 $나 백틱이 셸에 해석되지 않아 안전합니다 (본문에 ASCII '가 포함된 경우에만 다른 감싸기 방식을 사용합니다).

용도별 사용 예시

1. 두 번째 의견/복수 안 비교 (레시피 A)

설계/구현 결정에 대한 두 번째 의견입니다. 비교할 안/제약/출력 형태를 구체적으로 작성할수록 품질이 높아집니다.

OUT=$(mktemp /tmp/codex_answer.XXXXXX.txt)
ERR=$(mktemp /tmp/codex_err.XXXXXX.txt)
printf '%s' '의도: 인증 토큰의 갱신 방식을 결정하고 싶습니다. 현재는 API 호출 시마다
만료 시간을 확인하여 동기적으로 갱신하고 있으며 (@src/auth/client.ts), 빈번한 병렬
요청 시 이중 갱신이 발생합니다.

비교해 주었으면 하는 안:
(1) 갱신 중인 Promise를 공유하여 단일화
(2) 만료 전에 백그라운드에서 프로액티브하게 업데이트
(3) 401을 수신한 후 한 번만 갱신하고 재시도

제약: SSR과 CSR 모두에서 동작해야 합니다. 새 라이브러리는 추가하고 싶지 않습니다.
출력: correctness / complexity / failure mode 를 열로 하는 tradeoff table, 권장하는
기본 안과 fallback 안, 어떤 조건에서 다른 안으로 전환해야 하는지. 네이밍/포맷팅은 무시. ' \
  | codex exec - -s read-only -C /path/to/repo -o "$OUT" >/dev/null 2>"$ERR" \
  || { echo "codex failed:"; cat "$ERR"; exit 1; }
cat "$OUT"

2. 코드 리뷰

중요한 제약: codex exec review의 대상 범위 플래그 (--uncommitted / --base / --commit)는 사용자 지정 지시 PROMPT (-의 stdin / 위치 인수 모두)와 병용할 수 없습니다 (codex 0.142.4에서 확인. 병용 시 error: the argument '--uncommitted' cannot be used with '[PROMPT]'로 즉시 실패). 따라서 용도에 따라 두 가지로 나눕니다.

2a. 관점/의도를 전달하는 리뷰 (이 스킬의 주용도/권장): 범위 플래그와 관점 지시를 양립할 수 없으므로 codex exec review 대신 codex exec - (레시피 A/B)를 사용하고, 프롬프트 내에서 git diff 등을 확인하게 하여 범위를 지정합니다. -s read-only / -C / stdin을 그대로 사용할 수 있고 이스케이프도 피할 수 있습니다.

OUT=$(mktemp /tmp/codex_answer.XXXXXX.txt)
ERR=$(mktemp /tmp/codex_err.XXXXXX.txt)
printf '%s' '의도: 이 변경은 idle 알림음 억제 시에만 동작을 바꾸어야 하며, 사용자 입력
요청음 재생에는 영향을 주지 않아야 합니다. 커밋되지 않은 변경을 git diff (필요하면
git diff --cached나 untracked도)로 확인해 주세요. 먼저 의도에 비추어 타당한지,
그다음 구현을 봐 주세요.
착안점: 조건의 반전, 기본값의 변화, client/server 간 의미의 차이.
출력: 권장 → evidence가 있는 findings → 검증되지 않은 가정, 순서로. 네이밍/포맷팅은 무시. ' \
  | codex exec - -s read-only -C /path/to/repo -o "$OUT" >/dev/null 2>"$ERR" \
  || { echo "codex failed:"; cat "$ERR"; exit 1; }
echo "=== ANSWER ==="; cat "$OUT"

2b. 관점 지정 없는 원시 diff 리뷰: 사용자 지정 지시가 필요 없다면 codex exec review의 범위 플래그를 그대로 사용할 수 있습니다 (PROMPT를 붙이지 않으므로 위 제약에 걸리지 않음). codex exec과 달리 -C도 -s도 없으므로 대상 리포지토리 내에서 cd한 후 호출합니다.

OUT=$(mktemp /tmp/codex_review.XXXXXX.txt)
ERR=$(mktemp /tmp/codex_err.XXXXXX.txt)
cd /path/to/repo || exit 1
codex exec review --uncommitted -o "$OUT" >/dev/null 2>"$ERR" \
  || { echo "codex failed:"; cat "$ERR"; exit 1; }
echo "=== ANSWER ==="; cat "$OUT"

범위 플래그 교체 (위 codex exec review … 행을 대체. 모두 PROMPT는 붙이지 않음):

codex exec review --uncommitted -o "$OUT" >/dev/null 2>"$ERR"   # 커밋되지 않은 것 (staged + unstaged + untracked)
codex exec review --base main   -o "$OUT" >/dev/null 2>"$ERR"   # 베이스 브랜치와의 차이
codex exec review --commit <SHA> -o "$OUT" >/dev/null 2>"$ERR"  # 특정 커밋

관점을 전달하고 싶은 리뷰는 2a (codex exec - + git diff)를 사용합니다. 범위 플래그 + 사용자 지정 지시는 병용 불가.
review는 대상 리포지토리 내에서 실행합니다 (-C가 없으므로 cd한 후 호출). 리포지토리 외부라면 --skip-git-repo-check를 사용할 수 있지만, 리뷰 대상의 diff가 없으면 의미가 없습니다.

3. 계획/마이그레이션 타당성 검증 (레시피 B)

구현 전 계획/이전 절차를 stress-test하여 착수 전에 해결해야 할 격차를 식별합니다. read-only 상태로 현재 코드의 계약을 확인하게 합니다.

OUT=$(mktemp /tmp/codex_answer.XXXXXX.txt)
ERR=$(mktemp /tmp/codex_err.XXXXXX.txt)
printf '%s' '구현 전 계획을 리뷰하여, 코딩 전에 해결해야 할 격차만 나열해 주세요.
계획: 이벤트 동기화가 서버에서 거부되면 repair_required 플래그를 세우고, 컴팩트한
snapshot을 보내고, 서버가 정합 시퀀스를 ack한 후에만 증분 이벤트를 재개합니다.
관련: @src/sync/event-syncer.ts @src/db/sync-state.ts @api/types.ts.
현재 계약은 현재 코드를 읽어서 확인한 후 평가해 주세요.
착안점: 스키마 호환성, snapshot의 크기 제한, 재개 시퀀스의 경계 조건,
backfill/migration 영향, 테스트 부족.
출력: 착수 전에 필요한 계획 변경만 + "이대로 구현해도 안전한지"에 대한 한 줄 판정. ' \
  | codex exec - -s read-only -C /path/to/repo -o "$OUT" >/dev/null 2>"$ERR" \
  || { echo "codex failed:"; cat "$ERR"; exit 1; }
echo "=== ANSWER ==="; cat "$OUT"

4. 심층 조사 (레시피 B)

버그/테스트 실패의 근본 원인, race condition, 오래된 캐시 등의 끈기 있는 조사. 검증 가능한 성공 조건을 첨부하면 Codex의 심층 조사 특성이 살아납니다. 시간이 걸리므로 백그라운드 실행.

OUT=$(mktemp /tmp/codex_answer.XXXXXX.txt)
ERR=$(mktemp /tmp/codex_err.XXXXXX.txt)
printf '%s' '테스트 foo_test.go의 TestBar가 CI에서 드물게 실패합니다. 근본 원인을 조사해 주세요.
성공 조건: 재현 조건과 원인 위치를 파일:줄 단위로 특정하고, 최소 수정안을 제시할 것.
외부 라이브러리 기인으로 의심되면, 해당 라이브러리의 공식 문서를 웹 검색으로 확인해 주세요.' \
  | codex exec - -s read-only -C /path/to/repo -o "$OUT" >/dev/null 2>"$ERR" \
  || { echo "codex failed:"; cat "$ERR"; exit 1; }
echo "=== ANSWER ==="; cat "$OUT"

결과 처리

답변 (레시피 A는 tool result, 레시피 B는 완료 알림 후 백그라운드 출력)에서 요점을 사용자에게 전달합니다. 긴 경우 요약하면서 중요한 지적은 원문을 인용합니다.
Codex는 지나치게 방어적인 제안 (과도한 하위 호환성 고려 등)을 할 수 있습니다. 채택할 지적과 기각할 지적은 스스로 판단합니다. 맹신하지 말고, make sense하는 것만 수용합니다.

ask-codex

ask-codex란 무엇인가요?

즐겨 사용하는 AI에게 물어보기

문서