다음은 제공된 마크다운 콘텐츠를 한국어로 번역한 결과물입니다.
@OpenAI Codex 또는 코딩 에이전트 자체가 처음이시라면, 이 가이드가 더 빠르게 더 나은 결과를 얻는 데 도움이 될 것입니다. 이 가이드는 CLI, IDE 확장 프로그램, Codex 앱 전반에서 Codex를 더 효과적으로 사용하게 하는 핵심 습관들을 다룹니다. 여기에는 프롬프트 작성, 계획 수립부터 검증, MCP, 스킬, 자동화까지 포함됩니다.
Codex는 일회성 도우미라기보다는 시간이 지남에 따라 설정하고 개선해 나가는 팀원처럼 대할 때 가장 잘 작동합니다.
유용한 사고 방식은 다음과 같습니다: 올바른 작업 컨텍스트로 시작하고, AGENTS.md를 지속적인 지침으로 사용하며, Codex를 작업 흐름에 맞게 구성하고, MCP로 외부 시스템을 연결하며, 반복 작업을 스킬로 전환하고, 안정적인 워크플로우를 자동화하는 것입니다.
1. 명확한 컨텍스트와 프롬프트로 Codex의 첫 사용을 강력하게 준비하세요
Codex는 프롬프트가 완벽하지 않더라도 유용할 만큼 이미 강력합니다. 최소한의 설정만으로도 어려운 문제를 던져주고 강력한 결과를 얻을 수 있는 경우가 많습니다. 명확한 프롬프트 작성이 가치를 얻기 위해 필수적인 것은 아니지만, 특히 더 큰 코드베이스나 중요도가 높은 작업에서 결과의 신뢰성을 높여줍니다.
크거나 복잡한 저장소에서 작업하는 경우, 가장 큰 개선점은 일반적으로 Codex에 올바른 작업 컨텍스트와 수행하려는 작업에 대한 명확한 구조를 제공하는 것입니다.
좋은 기본값은 프롬프트에 다음 네 가지를 포함하는 것입니다.
- 목표: 무엇을 변경하거나 구축하려고 합니까?
- 컨텍스트: 이 작업과 관련된 파일, 폴더, 문서, 예제 또는 오류는 무엇입니까? 특정 파일을 컨텍스트로 @멘션할 수 있습니다.
- 제약 조건: Codex가 따라야 할 표준, 아키텍처, 안전 요구 사항 또는 규칙은 무엇입니까?
- 완료 조건: 테스트 통과, 동작 변경, 버그 수정 등 작업이 완료되기 전에 충족되어야 하는 조건은 무엇입니까?
이렇게 하면 Codex가 범위를 유지하고, 가정을 덜 하며, 검토하고 검증하기 쉬운 결과물을 생성하는 데 도움이 됩니다.
작업의 난이도에 따라 추론 수준을 선택하고 작업 흐름에 가장 잘 맞는 것을 테스트해 보세요. 사용자와 작업에 따라 다른 설정이 유리하게 작용할 수 있습니다.
- 낮음: 더 빠르고, 범위가 명확한 작업에 적합
- 중간 또는 높음: 더 복잡한 변경이나 디버깅에 적합
- 매우 높음: 길고, 에이전트 기반이며, 추론이 많이 필요한 작업에 적합
신규 사용자를 위한 팁
: 대부분의 사람들은 코드베이스에 대해 Codex에 질문하거나 작고 범위가 명확한 수정을 하는 등 몇 가지 기본적인 성공 사례를 먼저 경험함으로써 가장 빠르게 적응합니다. Codex 앱에서 음성 받아쓰기를 사용하여 반복 속도를 높이는 것을 적극 권장합니다.
Codex 추론 수준
2. Codex가 먼저 계획을 세우도록 하여 어려운 작업에서 실수를 줄이세요
작업이 복잡하거나, 모호하거나, 명확하게 설명하기 어렵다면 Codex에게 코딩을 시작하기 전에 계획을 세우도록 요청하세요.
이를 위한 몇 가지 좋은 방법이 있습니다.
Plan 모드 사용: 대부분의 사용자에게 이 방법이 가장 쉽고 효과적인 옵션입니다. Plan 모드를 사용하면 Codex가 컨텍스트를 수집하고, 명확한 질문을 하며, 구현 전에 더 강력한 계획을 수립할 수 있습니다. /plan 또는 Shift+Tab을 사용하여 전환합니다.
Codex가 당신에게 질문하도록 요청: 원하는 것에 대한 대략적인 아이디어는 있지만 어떻게 잘 설명해야 할지 확신이 서지 않는다면, Codex에게 먼저 질문하도록 요청하세요. 당신의 가정에 이의를 제기하고 모호한 아이디어를 코드를 작성하기 전에 구체적인 것으로 바꾸도록 지시하세요.
PLANS.md 템플릿 사용: 더 고급 워크플로우의 경우, Codex가 장기 실행 또는 다단계 작업을 위해 PLANS.md 또는 실행 계획 템플릿을 따르도록 구성할 수 있습니다. 자세한 내용은 실행 계획 가이드를 확인하세요.
Plan 모드
3. AGENTS.md로 성공적인 지침을 재사용 가능하게 만드세요
프롬프트 패턴이 효과가 있는 것으로 확인되면, 다음 단계는 수동으로 반복하는 것을 중단하는 것입니다. 바로 여기서 AGENTS.md가 등장합니다.
AGENTS.md를 에이전트를 위한 README라고 생각하세요. 컨텍스트에 자동으로 로드되는 간단하고 개방적인 형식이며, 저장소에서 귀하와 귀하의 팀이 Codex가 어떻게 작동하기를 원하는지 인코딩하기에 가장 좋은 곳입니다.
좋은 AGENTS.md는 일반적으로 다음을 다룹니다.
- 저장소 레이아웃 및 중요한 디렉토리
- 프로젝트 실행 방법
- 빌드, 테스트, 린트 명령어
- 엔지니어링 규칙 및 PR 기대 사항
- 제약 사항 및 금지 규칙
- 완료의 의미와 작업 확인 방법
CLI의 /init 슬래시 명령어는 현재 디렉토리에 시작용 AGENTS.md를 빠르게 생성하는 명령어입니다. 훌륭한 시작점이지만, 결과물을 팀이 실제로 코드를 빌드, 테스트, 검토, 배포하는 방식에 맞게 편집해야 합니다.
AGENTS.md 파일은 여러 수준으로 만들 수 있습니다: ~/.codex에 위치한 개인 기본값을 위한 전역 AGENTS.md, 공유 표준을 위한 저장소 수준 파일, 그리고 로컬 규칙을 위한 하위 디렉토리의 더 구체적인 파일입니다. 현재 디렉토리에 더 가까운 구체적인 파일이 있으면 해당 지침이 우선 적용됩니다.
실용적으로 유지하세요. 짧고 정확한 AGENTS.md가 모호한 규칙으로 가득 찬 긴 파일보다 더 유용합니다. 기본부터 시작한 다음, 반복적인 실수를 발견한 후에야 새 규칙을 추가하세요.
AGENTS.md가 너무 커지기 시작하면, 메인 파일은 간결하게 유지하고 계획 수립, 코드 리뷰, 아키텍처와 같은 작업을 위한 작업별 마크다운 파일을 참조하세요.
팁
: Codex가 같은 실수를 두 번 반복하면, 회고를 요청하고 AGENTS.md를 업데이트하세요. 지침이 실제 마찰에 기반하여 실용적으로 유지됩니다.
AGENTS.md 웹사이트
4. Codex를 작업 흐름에 맞게 구성하여 더 일관된 동작을 얻으세요
구성은 Codex가 세션과 표면 전반에서 더 일관되게 동작하도록 만드는 주요 방법 중 하나입니다. 예를 들어, 모델 선택, 추론 노력, 샌드박스 모드, 승인 정책, 프로필 및 MCP 설정에 대한 기본값을 설정할 수 있습니다.
좋은 시작 패턴은 다음과 같습니다.
- 개인 기본값은 ~/.codex/config.toml에 유지 (Codex 앱에서 설정 → 구성 → config.toml 열기)
- 저장소별 동작은 .codex/config.toml에 유지
- 일회성 상황에만 명령줄 재정의 사용 (CLI를 사용하는 경우)
Config.toml은 MCP 서버, 프로필, 멀티 에이전트 설정, 실험적 기능과 같은 지속적인 기본 설정을 정의하는 곳입니다. 직접 편집하거나 Codex에게 업데이트를 요청할 수 있습니다.
Codex는 운영 수준 샌드박싱과 함께 제공되며, 제어할 수 있는 두 가지 주요 설정이 있습니다. 승인 모드는 Codex가 명령을 실행하기 위해 언제 허가를 요청할지 결정하고, 샌드박스 모드는 Codex가 디렉토리에서 읽거나 쓸 수 있는지 그리고 에이전트가 액세스할 수 있는 파일을 결정합니다.
코딩 에이전트가 완전히 처음이라면, 기본 권한을 보수적으로 시작하는 것이 좋습니다. 기본적으로 승인 및 샌드박싱을 엄격하게 유지하고, 필요성이 명확해진 후에만 신뢰할 수 있는 저장소나 특정 워크플로우에 대해 권한을 완화하세요.
CLI, IDE, Codex 앱은 모두 동일한 구성 레이어를 공유합니다. 샘플 구성 문서 페이지에서 자세히 알아보세요.
팁
: Codex를 실제 환경에 맞게 초기에 구성하세요. 많은 품질 문제는 실제로 잘못된 작업 디렉토리, 쓰기 권한 부족, 잘못된 모델 기본값, 누락된 도구나 커넥터와 같은 설정 문제입니다.
5. Codex가 작업을 테스트, 검증 및 검토하도록 하여 신뢰성을 향상시키세요
Codex에게 변경만 요청하는 데서 멈추지 마세요. 필요할 때 테스트를 생성하고, 관련 검사를 실행하며, 결과를 검증하고, 수락하기 전에 작업을 검토하도록 요청하세요.
Codex는 이 루프를 스스로 수행할 수 있지만, "좋은" 것이 무엇인지 알아야만 가능합니다. 그 지침은 프롬프트나 AGENTS.md에서 제공될 수 있습니다.
여기에는 다음이 포함될 수 있습니다.
- 변경 사항에 대한 테스트 작성 또는 업데이트
- 올바른 테스트 스위트 실행
- 린트, 포맷팅 또는 타입 검사 확인
- 최종 동작이 요청과 일치하는지 확인
- 버그, 회귀 또는 위험한 패턴에 대한 Diff 검토
팁:
Codex 앱에서 Diff 패널을 전환하여 로컬에서
변경 사항 검토를 직접 수행하세요. 특정 행을 클릭하면 다음 Codex 턴에 컨텍스트로 제공되는 피드백을 제공할 수 있습니다.
여기서 유용한 옵션은 슬래시 명령어 /review입니다. 이를 통해 코드를 검토하는 여러 가지 방법을 제공합니다.
- 기본 브랜치와 비교하여 PR 스타일로 검토
- 커밋되지 않은 변경 사항 검토
- 커밋 검토
- 사용자 정의 검토 지침 사용
귀하와 귀하의 팀이 AGENTS.md에서 참조되는 code_review.md 파일을 가지고 있다면, Codex는 검토 중에도 해당 지침을 따를 수 있습니다. 이는 검토 동작이 저장소와 기여자 간에 일관되게 유지되기를 원하는 팀에게 강력한 패턴입니다.
Codex는 단순히 코드를 생성해서는 안 됩니다. 올바른 지침을 사용하면 테스트, 검증 및 검토도 도울 수 있습니다.
GitHub Cloud를 사용하는 경우, Codex가 PR에 대한 코드 리뷰를 실행하도록 쉽게 설정할 수 있습니다. OpenAI에서는 Codex가 모든 PR의 100%를 검토합니다. 자동 리뷰를 활성화하거나 @Codex를 통해 Codex가 반응적으로 검토하도록 하는 옵션을 선택할 수 있습니다.
Codex CLI의 /review
6. MCP를 사용하여 외부 도구와 실시간 컨텍스트를 Codex로 가져오세요
Codex에 필요한 컨텍스트가 저장소 외부에 있을 때 MCP를 사용하세요. MCP를 사용하면 Codex가 이미 사용 중인 도구와 시스템에 연결할 수 있으므로, 프롬프트에 실시간 정보를 계속 복사하여 붙여넣을 필요가 없습니다.
Model Context Protocol(MCP)은 Codex를 외부 도구 및 시스템에 연결하기 위한 개방형 표준입니다.
다음과 같은 경우 MCP를 사용하세요.
- 필요한 컨텍스트가 저장소 외부에 있는 경우
- 데이터가 자주 변경되는 경우
- 붙여넣은 지침에 의존하기보다 Codex가 도구를 사용하도록 하려는 경우
- 사용자 또는 프로젝트 간에 반복 가능한 통합이 필요한 경우
Codex는 OAuth를 사용하는 STDIO 및 Streamable HTTP 서버를 모두 지원합니다.
Codex 앱에서 설정 → MCP 서버로 이동하여 사용자 정의 및 권장 서버를 확인하세요. 종종 Codex는 필요한 서버를 설치하는 데 도움을 줄 수 있습니다. 요청하기만 하면 됩니다. CLI에서 codex mcp add 명령어를 사용하여 이름, URL 및 추가 정보와 함께 사용자 정의 서버를 추가할 수도 있습니다.
팁
: 실제 워크플로우를 실현할 수 있을 때만 도구를 추가하세요. 사용하는 모든 도구를 처음부터 연결하지 마세요. 이미 자주 수행하는 수동 루프를 명확하게 제거하는 하나 또는 두 개의 도구로 시작한 다음, 그곳에서 확장하세요.
MCP 서버 관리
7. 반복되는 워크플로우를 재사용 가능한 스킬로 전환하세요
워크플로우가 반복 가능해지면, 긴 프롬프트나 반복적인 주고받기에 의존하지 마세요. 스킬을 사용하여 Codex가 일관되게 적용해야 하는 지침, 컨텍스트 및 지원 로직을 SKILL.md 파일에 패키징하세요. 스킬은 CLI, IDE 확장 프로그램 및 Codex 앱에서 작동합니다.
각 스킬은 하나의 작업에만 tightly scoped 되도록 유지하세요. 2~3개의 구체적인 사용 사례로 시작하고, 명확한 입력과 출력을 정의하며, 스킬이 수행하는 작업과 사용 시기를 명확히 설명하는 설명을 작성하세요. 사용자가 실제로 말할 법한 트리거 문구의 종류를 포함하세요.
모든 예외 상황을 처음부터 다루려고 하지 마세요. 하나의 대표적인 작업으로 시작하여 잘 작동하도록 만든 다음, 해당 워크플로우를 스킬로 전환하고 그곳에서 개선하세요. 신뢰성을 의미 있게 향상시킬 때만 스크립트나 추가 자산을 포함하세요.
좋은 경험 법칙은 다음과 같습니다. 동일한 프롬프트를 계속 재사용하거나 동일한 워크플로우를 계속 수정한다면, 스킬로 만들어야 할 가능성이 높습니다.
스킬은 다음과 같은 반복적인 작업에 특히 유용합니다.
- 로그 분류
- 릴리스 노트 초안 작성
- 체크리스트 기반 PR 검토
- 마이그레이션 계획
- 텔레메트리 또는 인시던트 요약
- 표준 디버깅 흐름
$skill-creator 스킬은 스킬의 첫 번째 버전을 빠르게 생성하는 가장 좋은 시작점이며, $skill-installer 스킬을 사용하여 로컬에 설치할 수 있습니다. 스킬의 가장 중요한 부분 중 하나는 설명입니다. 스킬이 수행하는 작업과 사용 시기를 명확히 설명해야 합니다.
팁
개인 스킬은
$HOME /.agents/skills에 저장되며, 공유 팀 스킬은 저장소 내 .agents/skills에 체크인할 수 있습니다. 이는 특히 새 팀원을 온보딩할 때 유용합니다.
스킬 생성 및 설치
Codex 앱 스킬 UI
8. 자동화로 반복 작업 시간을 절약하세요
워크플로우가 안정화되면 Codex가 백그라운드에서 실행하도록 예약할 수 있습니다. Codex 앱에서 자동화를 사용하면 반복 작업에 대한 프로젝트, 프롬프트, 실행 주기 및 실행 환경을 선택할 수 있습니다.
작업이 반복적이 되면 Codex 앱의 자동화 탭에서 쉽게 자동화를 만들 수 있습니다. 실행할 프로젝트, 실행할 프롬프트(스킬을 호출할 수 있음), 실행 주기를 선택할 수 있습니다. 또한 자동화가 전용 git worktree에서 실행될지 로컬 환경에서 실행될지 선택할 수 있습니다. git worktrees에 대해 자세히 알아보세요.
좋은 후보는 다음과 같습니다.
- 최근 커밋 요약
- 잠재적인 버그 스캔
- 릴리스 노트 초안 작성
- CI 실패 확인
- 데일리 스탠드업 요약 생성
- 예약된 반복 가능한 분석 워크플로우 실행
유용한 규칙은 스킬이 방법을 정의하고 자동화가 일정을 정의한다는 것입니다. 워크플로우에 여전히 많은 조정이 필요하다면 먼저 스킬로 전환하세요. 예측 가능해지면 자동화는 힘을 배가시키는 요소가 됩니다.
팁
: 자동화를 실행뿐만 아니라 반성 및 유지 관리에도 사용하세요. 최근 세션을 검토하고, 반복되는 마찰을 요약하며, 시간이 지남에 따라 프롬프트, 지침 또는 워크플로우 설정을 개선하세요.
Codex 앱 자동화 생성
9. 세션 제어를 통해 장기 실행 작업을 체계적으로 유지하세요
Codex 세션은 단순한 채팅 기록이 아닙니다. 시간이 지남에 따라 컨텍스트, 결정 및 작업을 축적하는 작업 스레드이므로, 이를 잘 관리하는 것이 품질에 큰 영향을 미칩니다.
여러 스레드를 관리하는 것은 Codex 앱 UI에서 스레드를 고정하고 worktree를 생성할 수 있는 기능으로 가장 쉽습니다. 하지만 CLI를 사용하는 경우, 다음 슬래시 명령어가 특히 유용합니다.
- /experimental 실험적 기능을 전환하고 config.toml에 추가합니다.
- /resume 저장된 대화를 재개합니다.
- /fork 원본 대화를 유지하면서 새 스레드를 생성합니다.
- /compact 스레드가 길어지고 이전 컨텍스트의 요약된 버전을 원할 때 사용합니다. Codex는 자동으로 대화를 압축합니다.
- /agent 여러 에이전트를 실행 중이고 활성 에이전트 스레드 간에 전환하려는 경우 사용합니다.
- /theme 구문 강조 테마를 선택합니다.
- /apps Codex에서 직접 ChatGPT 앱을 사용합니다.
- /status 현재 세션 상태를 검사합니다.
하나의 일관된 작업 단위당 하나의 스레드를 유지하세요. 작업이 여전히 동일한 문제의 일부라면, 동일한 스레드에 머무르는 것이 추론 과정을 보존하기 때문에 종종 더 좋습니다. 작업이 진정으로 분기될 때만 포크하세요.
팁
:
Codex의
멀티 에이전트 워크플로우를 사용하여 메인 스레드에서 범위가 명확한 작업을 오프로드하세요. 메인 에이전트를 핵심 문제에 집중시키고, 하위 에이전트를 탐색, 테스트 또는 분류와 같은 작업에 사용하세요.
10. 피해야 할 일반적인 실수
Codex를 처음 사용할 때 피해야 할 몇 가지 일반적인 실수는 다음과 같습니다.
- 내구성 있는 규칙을 AGENTS.md나 스킬로 옮기지 않고 프롬프트에 과도하게 포함시키는 것
- 에이전트가 자신의 작업을 볼 수 있도록 빌드 및 테스트 명령을 가장 잘 실행하는 방법에 대한 세부 정보를 제공하지 않는 것
- 다단계 및 복잡한 작업에 대한 계획 수립을 건너뛰는 것
- 워크플로우가 이해되기 전에 Codex에 컴퓨터에 대한 모든 권한을 부여하는 것
- git worktree를 사용하지 않고 동일한 파일에서 여러 라이브 스레드를 실행하는 것
- 반복 작업을 수동으로 신뢰할 수 있게 되기 전에 자동화로 전환하는 것
- Codex를 단계별로 지켜봐야 하는 대상으로 취급하지 않고 자신의 작업과 병렬로 사용하는 것
시작하기 체크리스트
- Codex에 올바른 목표, 컨텍스트, 제약 조건 및 완료 조건을 제공하세요.
- 어려운 작업의 경우 Codex에게 먼저 계획을 세우도록 요청하세요.
- 시작용 AGENTS.md를 만드세요.
- Codex에게 빌드, 테스트, 검증 및 검토 방법을 알려주세요.
- 작업 흐름에 맞는 구성 기본값을 설정하세요.
- 가치 있는 외부 도구를 위해 MCP를 추가하세요.
- 반복되는 워크플로우를 스킬로 전환하세요.
- 워크플로우가 안정화되면 자동화를 사용하세요.
워크플로우, 표준 및 컨텍스트를 Codex가 사용할 수 있는 무언가로 더 많이 전환할수록 에이전트가 실제로 무엇을 할 수 있는지 더 많이 알게 될 것입니다. 지금 시작하세요!
