숏컷 코드

codex exec "summarize the repository structure"
codex exec --json "summarize the repository structure"
codex exec --ephemeral "triage this repository"
codex exec --output-schema ./schema.json -o ./result.json "Extract metadata"
codex exec resume --last "continue from the previous run"

실행 흐름

codex exec는 파이프라인에서 Codex를 도구로 연결하는 진입점이다

codex exec는 TUI를 열지 않고 Codex를 비대화형으로 실행하는 명령으로, CI와 스크립트 자동화의 기본 진입점입니다. 기본적으로 진행 로그는 stderr로 흐르고 최종 메시지만 stdout에 출력되므로, 파이프라인에서 마지막 결과를 다른 도구로 넘기기 좋습니다. 실패한 CI 원인을 요약해 PR 코멘트용 JSON 만들기, 저장소 구조 요약을 파일로 남기기, 정기 리포트 생성처럼 Codex를 파이프라인의 한 단계로 쓸 수 있습니다.

--json과 --output-schema가 기계 소비에 적합한 출력 구조를 만든다

--json을 켜면 최종 메시지 하나만이 아니라 실행 중 이벤트 전체를 JSONL로 받을 수 있어, 기계적으로 상태를 소비하는 작업에 적합합니다. --output-schema와 -o를 함께 쓰면 다운스트림에서 기대하는 JSON 구조를 강제하면서 마지막 산출물을 파일로 남길 수 있습니다. 이 두 옵션의 차이는 목적에 있습니다. --json은 실행 과정 전체를 추적할 때, --output-schema는 출력 형식 자체를 고정해야 할 때 씁니다.

최소 권한 원칙이 CI 자동화 설계의 출발점이다

권한은 최소 범위에서 시작하는 것이 좋습니다. 공식 문서는 기본 read-only, 수정이 필요하면 --full-auto나 샌드박스 옵션을 더해 점진적으로 넓히라고 안내합니다. 자동화에서는 danger-full-access보다 좁은 권한과 명확한 프롬프트가 훨씬 중요합니다. 권한을 넓게 열수록 프롬프트가 모호할 때 예상치 못한 수정이 발생할 위험이 커집니다. CI 로그와 산출물에 민감한 코드나 데이터가 섞일 수 있으므로 결과물을 어디에 남기는지도 함께 설계해야 합니다.

resume --last로 2단계 파이프라인과 세션 재개를 구성한다

codex exec resume --last는 가장 최근의 비대화형 세션을 이어서 실행합니다. 이 기능으로 1단계에서 분석을 실행하고, 2단계에서 그 결과를 이어받아 추가 작업을 수행하는 파이프라인을 만들 수 있습니다. --ephemeral 옵션은 세션 파일을 디스크에 남기지 않아 민감한 작업이나 임시 실행에 적합합니다. 반대로 재개가 필요한 작업에서는 --ephemeral을 쓰면 안 됩니다.

출력 옵션을 고르는 기준
- 마지막 텍스트 결과만 넘길 때: 기본 실행
- 이벤트 로그까지 수집할 때: --json
- 최종 JSON 모양을 강제할 때: --output-schema + -o
- 재개가 필요 없고 흔적을 남기지 않을 때: --ephemeral

어떤 옵션을 붙일까

주의할 점

실패 예시
- 1단계에서 codex exec --ephemeral 로 분석을 돌림
- 2단계에서 codex exec resume --last 로 이어서 처리하려고 함
- 결과: 재개할 세션이 남지 않아 파이프라인이 끊김
- 대응: resume 흐름이 필요하면 ephemeral을 빼고, 임시 실행이면 재개를 기대하지 않는다