Codex나 코딩 에이전트를 처음 사용한다면 이 가이드를 통해 더 빠르게 좋은 결과를 얻을 수 있습니다. 프롬프팅과 계획 수립부터 검증, MCP, 스킬, 예약 작업까지, CLI, IDE 확장, ChatGPT 데스크톱 앱 전반에서 Codex를 더 효과적으로 활용하는 핵심 습관을 다룹니다.
Codex를 일회성 도우미가 아니라 시간이 지날수록 구성하고 개선해 나가는 팀원처럼 대할 때 가장 효과적입니다.
다음과 같이 생각하면 유용합니다. 작업에 맞는 컨텍스트로 시작하고, 지속적으로 적용할 가이드는 AGENTS.md에 작성하며, 워크플로우에 맞게 Codex를 구성하고, MCP로 외부 시스템을 연결하세요. 반복 작업은 스킬로 만들고 안정된 워크플로우는 자동화하세요.
첫 활용의 핵심: 컨텍스트와 프롬프트
프롬프트가 완벽하지 않아도 Codex는 충분히 유용합니다. 최소한의 설정만으로 어려운 문제를 맡겨도 좋은 결과를 얻는 경우가 많습니다. Codex를 유용하게 활용하는 데 명확한 프롬프팅이 반드시 필요한 것은 아니지만, 특히 코드베이스가 크거나 중요한 작업일수록 결과의 신뢰도를 높여 줍니다.
규모가 크거나 복잡한 레포지토리에서 작업한다면, 작업에 맞는 컨텍스트를 제공하고 원하는 바를 명확하게 구조화해 전달하는 것이 Codex의 성능을 크게 끌어올립니다.
기본적으로 프롬프트에 다음 네 가지를 포함하는 것이 좋습니다:
- 목표: 무엇을 변경하거나 구현하려고 하나요?
- 컨텍스트: 이 작업에서 중요한 파일, 폴더, 문서, 예시 또는 오류는 무엇인가요? 특정 파일을 @ 멘션해 컨텍스트로 제공할 수 있습니다.
- 제약 조건: Codex가 따라야 할 표준, 아키텍처, 안전 요구 사항 또는 규칙은 무엇인가요?
- 완료 조건: 예를 들어 테스트 통과, 동작 변경, 버그 재현 중단 등 작업이 완료되었다고 판단할 조건은 무엇인가요?
이렇게 하면 Codex가 작업 범위에 집중하고, 가정을 줄이며, 더 검토하기 쉬운 결과를 만드는 데 도움이 됩니다.
작업 난이도에 따라 추론 수준을 선택하고 워크플로우에 가장 적합한 수준을 테스트해 보세요. 사용자와 작업마다 가장 적합한 설정이 다릅니다.
- 빠르고 범위가 명확한 작업에는 Low
- 더 복잡한 변경이나 디버깅에는 Medium 또는 High
- 장시간 진행되는 에이전트형 고강도 추론 작업에는 Extra High
컨텍스트를 더 빠르게 제공하려면 ChatGPT 데스크톱 앱의 음성 받아쓰기 기능으로, 키보드로 입력하는 대신 Codex에 원하는 작업을 말해 보세요.
어려운 작업은 먼저 계획하기
작업이 복잡하거나 모호하거나 설명하기 어렵다면, 코딩을 시작하기 전에 Codex에 먼저 계획을 세우도록 요청하세요.
다음과 같은 접근 방식이 효과적입니다:
플랜 모드 사용: 대부분의 사용자에게 가장 쉽고 효과적인 옵션입니다. 플랜 모드에서는 Codex가 컨텍스트를 수집하고, 명확히 해야 할 사항을 질문하며, 구현 전에 더 탄탄한 계획을 세울 수 있습니다. /plan 또는 Shift+Tab 단축키로 전환하세요.
Codex에게 인터뷰 요청: 원하는 바는 대략 알지만 잘 설명하기 어렵다면, Codex가 먼저 질문하도록 요청하세요. 코드를 작성하기 전에 가정의 허점을 짚고 모호한 아이디어를 구체화하도록 지시하세요.
PLANS.md 템플릿 사용: 고급 워크플로우에서는 장시간 또는 여러 단계로 진행되는 작업에 Codex가 PLANS.md 또는 실행 계획 템플릿을 따르도록 구성할 수 있습니다. 자세한 내용은 실행 계획 가이드에서 확인하세요.
AGENTS.md로 가이드 재사용하기
프롬프팅 패턴이 효과적이라는 점을 확인했다면, 다음 단계는 이를 매번 수동으로 반복하지 않는 것입니다. 이때 AGENTS.md를 활용할 수 있습니다.
AGENTS.md는 에이전트를 위한 자유 형식 README라고 생각하면 됩니다. 컨텍스트에 자동으로 로드되며, 레포지토리에서 Codex가 사용자와 팀이 원하는 방식으로 작업하도록 가이드를 기록하기에 가장 적합합니다.
잘 작성된 AGENTS.md에 포함할 내용:
- 레포지토리 구조와 주요 디렉터리
- 프로젝트 실행 방법
- 빌드, 테스트 및 린트 명령어
- 엔지니어링 규칙과 PR 요구 사항
- 제약 조건 및 금지 사항
- 완료 기준과 작업 검증 방법
CLI의 /init 슬래시 명령어는 현재 디렉터리에 초기 AGENTS.md를 스캐폴딩하는 빠른 시작 명령어입니다. 좋은 출발점이지만, 팀에서 실제로 코드를 빌드하고 테스트하고 검토하고 배포하는 방식에 맞게 결과를 수정해야 합니다.
AGENTS.md 파일은 여러 수준에 만들 수 있습니다. 개인 기본값을 위한 전역 AGENTS.md는 ~/.codex에 두고, 공유 표준을 위한 파일은 레포지토리 수준에 두며, 로컬 규칙이 필요하면 하위 디렉터리에 더 구체적인 파일을 둘 수 있습니다. 현재 디렉터리에 더 가까운 위치에 더 구체적인 파일이 있으면 해당 가이드가 우선 적용됩니다.
실용적으로 작성하세요. 모호한 규칙으로 가득한 긴 파일보다 짧고 정확하게 작성한 AGENTS.md 파일이 더 유용합니다. 기본 사항부터 시작하고, 같은 실수가 반복되는 것을 확인한 후에만 새 규칙을 추가하세요.
AGENTS.md 파일이 너무 커지기 시작하면 기본 파일은 간결하게 유지하고 계획, 코드 검토, 아키텍처 같은 작업별 Markdown 파일을 참조하세요.
Codex가 같은 실수를 두 번 하면 회고를 요청하고
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에 변경을 요청하는 데서 멈추지 마세요. 필요할 때 테스트를 만들고, 관련 검사를 실행하고, 결과를 확인하고, 작업을 수락하기 전에 검토하도록 요청하세요.
Codex가 이 과정을 대신 수행할 수 있지만, 무엇이 “좋은” 결과인지 알아야 합니다. 이 기준은 프롬프트나 AGENTS.md에서 제공할 수 있습니다.
예를 들면 다음과 같습니다:
- 변경 사항에 맞는 테스트 작성 또는 업데이트
- 적절한 테스트 스위트 실행
- 린트, 서식 또는 타입 검사 확인
- 최종 동작이 요청과 일치하는지 확인
- 버그, 회귀 또는 위험한 패턴이 있는지 diff 검토
ChatGPT 데스크톱 앱에서 diff 패널을 열어 변경 사항을 로컬에서 직접 검토하세요. 특정 행을 클릭해 피드백을 제공하면 다음 Codex 턴에 컨텍스트로 전달됩니다.
여기서 유용한 옵션은 /review 슬래시 명령어입니다. 이 명령어를 사용하면 다음과 같은 방법으로 코드를 검토할 수 있습니다:
- PR 방식으로 기본 브랜치와 비교 검토
- 커밋되지 않은 변경 사항 검토
- 커밋 검토
- 사용자 지정 검토 지침 사용
본인과 팀에 code_review.md 파일이 있고 AGENTS.md에서 이 파일을 참조하면 Codex도 검토 중에 해당 지침을 따를 수 있습니다. 레포지토리와 기여자가 달라도 검토 방식을 일관되게 유지하려는 팀에 효과적인 패턴입니다.
Codex는 코드를 생성하는 데 그쳐서는 안 됩니다. 적절한 지침을 제공하면 코드를 테스트하고 검사하고 검토하는 데도 활용할 수 있습니다.
GitHub Cloud를 사용한다면 Codex가 PR 코드 검토를 실행하도록 설정할 수 있습니다. OpenAI에서는 Codex가 PR의 100%를 검토합니다. 자동 검토를 활성화하거나 @Codex를 멘션해 필요할 때 검토를 요청할 수 있습니다.
외부 컨텍스트에 MCP 사용하기
Codex에 필요한 컨텍스트가 레포지토리 외부에 있다면 MCP를 사용하세요. MCP를 사용하면 Codex를 기존 도구 및 시스템에 연결할 수 있으므로 최신 정보를 프롬프트에 계속 복사해 붙여 넣을 필요가 없습니다.
Model Context Protocol(MCP)은 Codex를 외부 도구 및 시스템에 연결하기 위한 개방형 표준입니다.
다음과 같은 경우 MCP를 사용하세요:
- 필요한 컨텍스트가 레포지토리 외부에 있는 경우
- 데이터가 자주 변경되는 경우
- 붙여 넣은 지침에 의존하기보다 Codex가 도구를 사용하게 하려는 경우
- 사용자나 프로젝트가 달라도 반복해서 사용할 수 있는 통합이 필요한 경우
Codex는 STDIO 서버와 OAuth를 사용하는 Streamable HTTP 서버를 모두 지원합니다.
ChatGPT 데스크톱 앱에서 설정 > MCP 서버로 이동하면 사용자 지정 서버와 권장 서버를 확인할 수 있습니다. Codex가 필요한 서버를 설치하도록 도와줄 수 있는 경우가 많습니다. Codex에 요청하기만 하면 됩니다. CLI에서는 codex mcp add 명령어를 사용해 이름, URL 및 기타 세부 정보를 지정하여 사용자 지정 서버를 추가할 수도 있습니다.
도구가 있어야 가능한 실제 워크플로우가 있을 때만 추가하세요. 처음부터 사용하는 모든 도구를 연결하지 마세요. 자주 반복하는 수동 작업을 확실히 줄여 주는 도구 한두 개로 시작한 다음 점차 확장하세요.
반복 작업을 스킬로 전환하기
워크플로우를 반복해서 사용할 수 있게 되면 긴 프롬프트나 반복적인 문답에 의존하지 마세요. 스킬을 사용해 지침은 SKILL.md 파일에 담고, 컨텍스트와 Codex가 일관되게 적용해야 할 지원 로직까지 함께 패키징하세요. 스킬은 CLI, IDE 확장, ChatGPT 데스크톱 앱에서 모두 사용할 수 있습니다.
각 스킬은 한 가지 작업만 담당하도록 범위를 정하세요. 구체적인 사용 사례 2~3개로 시작해 입력과 출력을 명확히 정의하고, 설명에는 스킬이 하는 일과 사용 시점을 명시하세요. 사용자가 실제로 말할 법한 트리거 문구도 포함하세요.
처음부터 모든 에지 케이스를 다루려고 하지 마세요. 대표적인 작업 하나로 시작해 제대로 작동하게 만든 다음, 해당 워크플로우를 스킬로 전환하고 계속 개선하세요. 안정성을 높이는 경우에만 스크립트나 추가 에셋을 포함하세요.
같은 프롬프트를 계속 재사용하거나 같은 워크플로우를 반복해서 수정하고 있다면 스킬로 전환할 때입니다.
스킬은 다음과 같은 반복 작업에 특히 유용합니다:
- 로그 트리아지
- 릴리스 노트 초안 작성
- 체크리스트를 기준으로 한 PR 검토
- 마이그레이션 계획
- 텔레메트리 또는 인시던트 요약
- 표준 디버깅 플로우
$skill-creator 스킬은 스킬의 첫 버전 기본 구조를 만들 때 가장 좋은 출발점입니다. 개선하는 동안 첫 버전은 로컬에 유지하세요. 널리 공유할 준비가 되면 플러그인으로 패키징하세요. 스킬에서 가장 중요한 요소 중 하나는 설명입니다. 설명에는 스킬이 하는 일과 사용 시점을 명시해야 합니다.
개인 스킬은 $HOME/.agents/skills에 저장되며, 팀 공유 스킬은
레포지토리의 .agents/skills에 체크인할 수 있습니다. 이는 새 팀원의
온보딩에 특히 유용합니다.
반복 작업에 예약 작업 사용하기
워크플로우가 안정되면 Codex가 워크플로우를 백그라운드에서 실행하도록 예약할 수 있습니다. ChatGPT 데스크톱 앱에서 예약 작업을 사용하면 반복 작업의 프로젝트, 프롬프트, 실행 주기, 실행 환경을 선택할 수 있습니다.
예약 작업 페이지에서 예약 작업을 만드세요. 프로젝트, 프롬프트, 실행 주기, 그리고 작업을 전용 Git 작업 트리에서 실행할지 로컬 환경에서 실행할지를 선택하세요. 프롬프트에서 스킬을 호출할 수 있습니다. 자세한 내용은 Git 작업 트리를 참조하세요.
적합한 예시는 다음과 같습니다:
- 최근 커밋 요약
- 발생 가능성이 높은 버그 탐색
- 릴리스 노트 초안 작성
- CI 실패 확인
- 스탠드업 요약 작성
- 일정에 따른 반복 가능한 분석 워크플로우 실행
유용한 원칙은 스킬은 방법을 정의하고 예약 작업은 일정을 정의한다는 것입니다. 워크플로우에 아직 세세한 지시가 많이 필요하다면 먼저 스킬로 만드세요. 동작을 예측할 수 있게 되면 예약 실행으로 시간을 절약할 수 있습니다.
예약 작업은 실행뿐 아니라 회고와 유지관리에도 활용하세요. 최근 채팅을 검토하고 반복되는 걸림돌을 요약하여 프롬프트, 지침 또는 워크플로우 설정을 꾸준히 개선하세요.
오래 이어지는 채팅 정리하기
채팅에는 컨텍스트, 결정 사항, 작업 내역이 시간이 지날수록 쌓이므로 잘 관리하는 것이 품질에 큰 영향을 줍니다.
ChatGPT 데스크톱 앱에서는 채팅을 고정하고 작업 트리를 만들 수 있습니다. CLI를 사용한다면 다음 슬래시 명령어가 특히 유용합니다:
/experimental: 실험적 기능을 전환하고 설정을config.toml에 추가/resume: 저장된 채팅 재개/fork: 원본 대화 기록을 유지한 채 새 채팅 만들기/compact: 채팅이 길어져 이전 컨텍스트를 요약한 버전이 필요할 때 사용. Codex는 채팅을 자동으로 압축하기도 합니다/agent: 여러 에이전트를 병렬로 실행할 때 활성 에이전트 스레드 전환/theme: 구문 강조 테마 선택/apps: Codex에서 ChatGPT 앱 직접 사용/status: 현재 세션 상태 확인
서로 밀접하게 연관된 작업 단위마다 하나의 채팅을 사용하세요. 작업이 여전히 같은 문제의 일부라면 추론 과정이 보존되므로 같은 채팅을 계속 사용하는 편이 좋습니다. 작업이 실제로 분기될 때만 포크하세요.
Codex의 하위 에이전트 워크플로우를 사용해 범위가 한정된 작업을 메인 스레드에서 하위 에이전트로 넘기세요. 메인 에이전트는 핵심 문제에 집중하게 하고, 탐색, 테스트, 트리아지 같은 작업에는 하위 에이전트를 사용하세요.
흔히 하는 실수
Codex를 처음 사용할 때 피해야 할 몇 가지 흔한 실수는 다음과 같습니다:
- 지속적으로 적용할 규칙을
AGENTS.md또는 스킬로 옮기지 않고 프롬프트에 과도하게 넣기 - 빌드 및 테스트 명령어를 적절하게 실행하는 방법을 자세히 알려주지 않아 에이전트가 작업 결과를 확인하지 못하게 하기
- 여러 단계로 이루어진 복잡한 작업에서 계획을 생략하기
- 워크플로우를 파악하기 전에 컴퓨터에 대한 전체 권한을 Codex에 부여하기
- Git 작업 트리를 사용하지 않고 같은 파일에서 여러 작업을 동시에 실행하기
- 수동 실행에서 안정성을 확보하기 전에 반복 작업을 예약하기
- Codex를 자신의 작업과 병행해 사용하지 않고 단계마다 지켜봐야 하는 도구처럼 다루기
- 일관된 결과물마다 채팅을 나누지 않고 프로젝트 전체에 하나의 채팅만 사용하기. 시간이 지날수록 컨텍스트가 불필요하게 비대해져 결과의 품질이 떨어집니다