Codex 활용 모범 사례

Codex나 코딩 에이전트를 처음 사용한다면 이 가이드를 참고해 더 빠르게 좋은 결과를 얻으세요. 프롬프트 작성과 계획 수립부터 검증, MCP, 스킬, 예약 작업까지, CLI, IDE 확장 프로그램, ChatGPT 데스크톱 앱에서 Codex를 효과적으로 활용하는 방법을 다룹니다.

Codex는 한 번 일을 맡기고 끝내는 도우미로 쓸 때보다, 팀원과 일하듯 작업 방식을 정하고 함께 일하면서 개선해 나갈 때 가장 효과적입니다.

먼저 작업에 맞는 컨텍스트를 제공하세요. 계속 적용할 지침은 AGENTS.md에 작성하고, 워크플로우에 맞게 Codex를 설정하세요. 외부 시스템은 MCP로 연결하고, 반복하는 작업은 스킬로 만들고, 안정적으로 작동하는 워크플로우는 자동화하세요.

첫 작업에 필요한 컨텍스트와 프롬프트

프롬프트가 완벽하지 않아도 Codex는 유용합니다. 별다른 준비 없이 어려운 문제를 맡겨도 좋은 결과를 얻는 경우가 많습니다. 처음부터 프롬프트를 명확하게 작성해야만 Codex를 활용할 수 있는 것은 아닙니다. 다만 코드베이스가 크거나 실수의 영향이 큰 작업일수록 명확한 프롬프트가 결과의 신뢰도를 높여 줍니다.

규모가 크거나 구조가 복잡한 리포지터리에서는 작업에 필요한 컨텍스트를 제공하고, 원하는 작업을 항목별로 명확하게 설명하는 것이 가장 효과적입니다.

프롬프트에는 다음 네 가지를 포함하는 것이 좋습니다.

• 목표: 무엇을 변경하거나 만들려고 하나요?
• 컨텍스트: 이 작업과 관련된 파일, 폴더, 문서, 예시 또는 오류는 무엇인가요? @로 특정 파일을 멘션해 컨텍스트로 제공할 수 있습니다.
• 제약 조건: Codex가 따라야 할 표준, 아키텍처, 안전 요구 사항 또는 규칙은 무엇인가요?
• 완료 기준: 어떤 조건을 충족해야 작업이 끝났다고 볼 수 있나요? 예를 들어 테스트가 통과하거나, 동작이 바뀌거나, 버그가 더 이상 재현되지 않아야 할 수 있습니다.

이 네 가지를 알려 주면 Codex가 요청한 범위 안에서 작업하고 임의로 가정하는 부분도 줄어들어 결과를 더 쉽게 리뷰할 수 있습니다.

계정과 클라이언트에서 GPT-6.1 Sol을 사용할 수 있다면 이 모델을 선택하고 클라이언트의 기본 추론 수준으로 시작하세요. GPT-6 Luna에서는 High, GPT-6 Astra에서는 Light(설정값 low)로 시작하세요. 작업과 결과를 보고 추론 수준을 조정하세요. 사용 가능한 추론 수준은 모델 문서에서 확인할 수 있습니다.

• Low는 범위가 명확하고 빠르게 처리할 작업에 적합합니다.
• Medium 또는 High는 더 복잡한 변경이나 디버깅에 적합합니다.
• Extra High는 에이전트가 장시간 자율적으로 진행하며 많은 추론을 해야 하는 작업에 적합합니다.

어려운 작업은 계획부터 세우기

작업이 복잡하거나 모호하거나 말로 설명하기 어렵다면, 코딩을 시작하기 전에 Codex에 계획부터 세워 달라고 요청하세요.

다음과 같은 방법을 활용할 수 있습니다.

계획 수립 모드 사용: 대부분의 사용자에게 가장 쉽고 효과적인 방법입니다. 계획 수립 모드에서는 Codex가 구현 전에 컨텍스트를 수집하고 불분명한 점을 질문해 더 구체적인 계획을 세웁니다. /plan 또는 Shift+Tab으로 모드를 전환하세요.

Codex에 먼저 질문해 달라고 요청: 원하는 것이 대략적으로 떠오르지만 설명하기 어렵다면 Codex에 먼저 질문해 달라고 하세요. 코드를 작성하기 전에 당연하다고 여긴 전제를 짚어 보고 막연한 아이디어를 구체화해 달라고 요청하세요.

PLANS.md 템플릿 사용: 더 고도화된 워크플로우에서는 시간이 오래 걸리거나 여러 단계로 진행되는 작업에 PLANS.md 또는 실행 계획 템플릿을 따르도록 Codex를 설정할 수 있습니다. 자세한 내용은 실행 계획 가이드를 참고하세요.

AGENTS.md로 지침 재사용하기

효과가 좋은 프롬프트 작성 방식을 찾았다면 매번 같은 지침을 직접 입력할 필요가 없습니다. 이때 AGENTS.md를 활용하세요.

AGENTS.md는 에이전트를 위한 개방형 형식의 README입니다. 자동으로 컨텍스트에 포함되므로, 팀에서 Codex가 리포지터리 작업을 어떤 방식으로 수행하기를 원하는지 기록하기에 가장 적합합니다.

AGENTS.md에는 다음 내용을 포함하는 것이 좋습니다.

• 리포지터리 구조와 주요 디렉터리
• 프로젝트 실행 방법
• 빌드, 테스트, 린트 명령어
• 개발 규칙과 PR에서 기대하는 사항
• 제약 조건과 금지 사항
• 작업 완료 기준과 검증 방법

CLI에서 /init 슬래시 명령어를 실행하면 현재 디렉터리에 기본 AGENTS.md를 빠르게 생성할 수 있습니다. 이 파일을 바탕으로 팀에서 실제로 코드를 빌드하고 테스트하고 리뷰하고 배포하는 방식에 맞게 내용을 수정하세요.

AGENTS.md 파일은 여러 수준에 둘 수 있습니다. 개인 기본값을 담은 전역 AGENTS.md는 ~/.codex에, 공통 표준을 담은 파일은 리포지터리 수준에 두세요. 특정 디렉터리에만 적용할 규칙은 해당 하위 디렉터리에 별도 파일로 작성하세요. 현재 디렉터리와 더 가까운 곳에 구체적인 지침 파일이 있으면 그 지침이 우선합니다.

실제 작업에 필요한 내용을 담으세요. 모호한 규칙을 길게 나열한 파일보다 짧고 정확한 AGENTS.md가 더 유용합니다. 기본 사항부터 작성하고 같은 실수가 반복될 때만 새 규칙을 추가하세요.

AGENTS.md가 너무 길어지면 기본 파일은 간결하게 유지하고, 계획 수립, 코드 리뷰, 아키텍처 등 작업별 세부 사항은 별도의 마크다운 파일에 작성해 참조하세요.

Codex가 일관되게 동작하도록 설정하기

세션이 바뀌거나 다른 인터페이스를 사용해도 Codex가 일관되게 동작하도록 하는 주요 방법은 기본 설정을 정해 두는 것입니다. 예를 들어 모델, 추론 수준, 샌드박스 모드, 승인 정책, 프로필, MCP 설정의 기본값을 지정할 수 있습니다.

처음에는 다음과 같이 설정하세요.

• 개인 기본값은 ~/.codex/config.toml에 저장하세요(ChatGPT 데스크톱 앱에서 설정 > 구성 > config.toml 열기 선택).
• 리포지터리에만 적용할 설정은 .codex/config.toml에 저장하세요.
• CLI를 사용한다면 일회성 작업에서만 명령줄로 기본값을 재정의하세요.

config.toml에는 MCP 서버, 다중 에이전트 구성, 기능 플래그 등 계속 사용할 설정을 정의합니다. 프로필별로 재정의할 값은 별도의 $CODEX_HOME/profile-name.config.toml 파일에 저장합니다.

Codex는 운영체제 수준의 샌드박스를 제공하며, 두 가지 주요 설정을 조정할 수 있습니다. 승인 모드는 Codex가 명령어 실행 전에 언제 승인을 요청할지 결정합니다. 샌드박스 모드는 Codex가 디렉터리에서 읽거나 쓸 수 있는지, 에이전트가 어떤 파일에 접근할 수 있는지 결정합니다.

코딩 에이전트가 처음이라면 기본 권한으로 시작하세요. 기본적으로 승인 조건과 샌드박스 제한을 엄격하게 유지하고, 필요성이 분명해졌을 때 신뢰할 수 있는 리포지터리나 특정 워크플로우에 한해 권한을 확대하세요.

CLI, IDE 확장 프로그램, ChatGPT 데스크톱 앱은 모두 같은 설정 계층을 사용합니다. 자세한 내용은 설정 예시를 참고하세요.

테스트와 리뷰로 신뢰도 높이기

Codex에 변경을 요청한 뒤에는 필요에 따라 테스트를 작성하고, 관련 검사를 실행하고, 결과를 확인해 달라고 하세요. 변경 사항을 받아들이기 전에 작업 내용도 리뷰해 달라고 요청하세요.

Codex가 이 과정을 대신 수행하려면 어떤 결과가 기준을 충족하는지 알아야 합니다. 해당 기준은 프롬프트나 AGENTS.md에 명시할 수 있습니다.

예를 들어 다음과 같은 지침을 포함할 수 있습니다.

• 변경 사항에 맞게 테스트 작성 또는 업데이트
• 작업에 맞는 테스트 모음 실행
• 린트, 서식 또는 타입 검사 결과 확인
• 최종 동작이 요청과 일치하는지 확인
• 변경 내역에 버그, 회귀 또는 위험한 패턴이 있는지 리뷰

/review 슬래시 명령어를 사용하면 다음과 같은 방식으로 코드를 리뷰할 수 있습니다.

• 기준 브랜치와 비교해 PR 방식으로 리뷰
• 커밋하지 않은 변경 사항 리뷰
• 특정 커밋 리뷰
• 사용자 지정 리뷰 지침 적용

팀에서 code_review.md 파일을 사용하고 AGENTS.md에서 이 파일을 참조하면 Codex가 리뷰할 때도 해당 지침을 따를 수 있습니다. 여러 리포지터리에서 여러 기여자가 일관된 방식으로 리뷰하려는 팀에 효과적입니다.

코드 생성에서 끝내지 마세요. 적절한 지침을 제공하면 Codex는 코드를 테스트하고 점검하고 리뷰하는 일도 도울 수 있습니다.

GitHub Cloud를 사용한다면 Codex가 PR 코드 리뷰를 수행하도록 설정할 수 있습니다. OpenAI에서는 PR의 100%를 Codex가 리뷰합니다. 자동 리뷰를 활성화하거나 @Codex를 멘션할 때 리뷰하도록 설정할 수 있습니다.

MCP로 외부 컨텍스트 활용하기

Codex에 필요한 컨텍스트가 리포지터리 외부에 있다면 MCP를 사용하세요. Codex가 기존 도구와 시스템에 연결할 수 있으므로 최신 정보를 매번 복사해 프롬프트에 붙여 넣을 필요가 없습니다.

Model Context Protocol의 약자인 MCP는 Codex를 외부 도구 및 시스템에 연결하기 위한 개방형 표준입니다.

다음과 같은 경우에 MCP를 사용하세요.

• 필요한 컨텍스트가 리포지터리 외부에 있는 경우
• 데이터가 자주 바뀌는 경우
• 붙여 넣은 지침에 의존하는 대신 Codex가 도구를 직접 사용하도록 하려는 경우
• 여러 사용자나 프로젝트에서 같은 연동 방식을 재사용해야 하는 경우

Codex는 STDIO 서버와 OAuth를 사용하는 Streamable HTTP 서버를 모두 지원합니다.

ChatGPT 데스크톱 앱의 설정 > MCP 서버 메뉴에서 사용자 지정 서버와 추천 서버를 확인하세요. 필요한 서버를 설치할 때도 Codex에 요청하면 도움을 받을 수 있는 경우가 많습니다. CLI에서는 codex mcp add 명령어에 이름, URL 등의 정보를 지정해 사용자 지정 서버를 추가할 수 있습니다.

반복 가능한 작업을 스킬로 만들기

같은 방식으로 워크플로우를 반복할 수 있게 되면 긴 프롬프트를 입력하거나 여러 번 대화를 주고받을 필요가 없습니다. 스킬을 사용해 SKILL.md 파일에 작성한 지침, 컨텍스트, Codex가 일관되게 적용할 보조 로직을 하나로 묶으세요. 스킬은 CLI, IDE 확장 프로그램, ChatGPT 데스크톱 앱에서 모두 사용할 수 있습니다.

스킬 하나는 한 가지 일을 맡도록 범위를 정하세요. 구체적인 사용 사례 두세 가지로 시작하고 입력과 출력을 명확히 정의하세요. 설명에는 스킬이 하는 일과 언제 사용해야 하는지 적고, 사용자가 스킬을 호출할 때 실제로 쓸 법한 표현을 포함하세요.

처음부터 모든 예외 상황을 다루려고 하지 마세요. 대표적인 작업 하나를 먼저 잘 수행할 수 있게 한 뒤, 해당 워크플로우를 스킬로 만들어 개선해 나가세요. 스크립트나 추가 리소스는 신뢰도를 높이는 경우에만 포함하세요.

같은 프롬프트를 계속 재사용하거나 같은 워크플로우를 반복해서 바로잡고 있다면 스킬로 만드는 것이 좋습니다.

스킬은 특히 다음과 같은 반복 작업에 유용합니다.

• 로그를 분석해 문제 분류
• 릴리스 노트 초안 작성
• 체크리스트에 따른 PR 리뷰
• 마이그레이션 계획 수립
• 텔레메트리 데이터 또는 인시던트 요약
• 표준 디버깅 플로우 수행

스킬의 첫 버전을 만들 때는 $skill-creator 스킬로 기본 구조를 잡는 것이 가장 좋습니다. 첫 버전은 로컬에서 사용하며 다듬으세요. 널리 공유할 준비가 되면 플러그인으로 패키징하세요. 스킬에서 가장 중요한 부분 중 하나는 설명입니다. 스킬이 어떤 일을 하며 언제 사용해야 하는지 명시하세요.

반복 작업에 예약 작업 활용하기

워크플로우가 안정되면 Codex가 백그라운드에서 실행하도록 예약할 수 있습니다. ChatGPT 데스크톱 앱의 예약 작업에서는 반복할 작업의 프로젝트, 프롬프트, 실행 주기, 실행 환경을 선택할 수 있습니다.

예약 페이지에서 예약 작업을 만드세요. 프로젝트, 프롬프트, 실행 주기를 선택하고, 작업을 전용 Git 작업 트리에서 실행할지 로컬 환경에서 실행할지 정하세요. 프롬프트에서 스킬을 호출할 수도 있습니다. 자세한 내용은 Git 작업 트리를 참고하세요.

다음과 같은 작업을 예약하기 좋습니다.

• 최근 커밋 요약
• 버그가 있을 만한 코드 탐색
• 릴리스 노트 초안 작성
• CI 실패 확인
• 스탠드업 미팅용 요약 작성
• 반복 가능한 분석 워크플로우를 정해진 일정에 따라 실행

스킬은 작업 방법을 정하고 예약 작업은 실행 일정을 정합니다. 아직 자주 개입해 방향을 잡아 줘야 하는 워크플로우라면 먼저 스킬로 만드세요. 결과를 예측할 수 있게 되면 실행을 예약해 시간을 절약할 수 있습니다.

오래 이어지는 채팅 관리하기

채팅에는 시간이 지날수록 컨텍스트, 결정 사항, 작업 내역이 쌓입니다. 따라서 채팅을 어떻게 관리하는지가 결과의 품질에 큰 영향을 줍니다.

ChatGPT 데스크톱 앱에서는 채팅을 고정하고 작업 트리를 만들 수 있습니다. CLI에서는 다음 슬래시 명령어가 특히 유용합니다.

• /experimental로 실험적 기능을 켜거나 끄고 config.toml에 설정을 추가합니다.
• /resume으로 저장된 채팅을 재개합니다.
• /fork로 원래 대화 기록을 보존하면서 새 채팅을 만듭니다.
• /compact로 채팅이 길어졌을 때 이전 컨텍스트를 요약합니다. Codex는 채팅을 자동으로 압축하기도 합니다.
• /subagents로 현재 채팅의 하위 에이전트 스레드 간에 전환합니다.
• /theme으로 구문 강조 테마를 선택합니다.
• /apps로 Codex에서 ChatGPT 앱을 직접 사용합니다.
• /status로 현재 세션 상태를 확인합니다.

서로 관련된 작업은 하나의 채팅에서 진행하세요. 여전히 같은 문제를 다루고 있다면 추론 과정을 유지할 수 있도록 같은 채팅을 이어 가는 편이 좋습니다. 작업이 실제로 다른 방향으로 나뉠 때만 채팅을 포크하세요.

흔한 실수

Codex를 처음 사용할 때는 다음과 같은 실수를 피하세요.

• 계속 적용할 규칙을 AGENTS.md나 스킬로 옮기지 않고 프롬프트에 과도하게 넣는 것
• 빌드 및 테스트 명령어를 어떻게 실행해야 하는지 구체적으로 알려 주지 않아 에이전트가 작업 결과를 확인할 수 없게 하는 것
• 여러 단계가 필요하거나 복잡한 작업에서 계획 수립을 건너뛰는 것
• 워크플로우를 이해하기 전에 Codex에 컴퓨터 전체 권한을 부여하는 것
• Git 작업 트리를 사용하지 않고 같은 파일에서 여러 작업을 동시에 실행하는 것
• 수동으로 실행해도 아직 안정적이지 않은 작업을 반복 실행하도록 예약하는 것
• 자신의 작업과 병행해 Codex를 활용하지 않고 매 단계를 지켜봐야 한다고 생각하는 것
• 하나의 결과를 목표로 하는 작업마다 채팅을 나누지 않고 프로젝트 전체를 한 채팅에서 진행하는 것. 시간이 지날수록 컨텍스트가 불필요하게 커지고 결과의 품질이 떨어집니다.