사용자 지정

Codex를 사용자 지정하면 팀의 작업 방식에 맞춰 동작하도록 설정할 수 있습니다.

Codex에서는 다음 요소를 함께 사용해 작업 방식을 조정합니다.

• 프로젝트 지침(AGENTS.md): 작업할 때마다 적용할 지침을 정합니다.
• 메모리: 이전 작업에서 얻은 유용한 컨텍스트를 보관합니다.
• 스킬: 워크플로우와 분야별 전문 지식을 여러 작업에서 재사용합니다.
• MCP: 외부 도구와 공유 시스템에 접근합니다.
• 하위 에이전트: 특정 작업을 전문으로 하는 하위 에이전트에게 일을 맡깁니다.

각 요소는 서로 보완합니다. AGENTS.md는 Codex의 행동 기준을 정하고, 메모리는 로컬 컨텍스트를 다음 작업으로 이어 줍니다. 스킬은 반복할 절차를 하나로 묶고, MCP는 Codex를 로컬 워크스페이스 밖의 시스템에 연결합니다.

AGENTS 지침

AGENTS.md는 리포지터리에 함께 보관하는 프로젝트 지침 파일입니다. Codex는 작업을 시작하기 전에 이 지침을 적용합니다. 파일은 간결하게 유지하세요.

Codex가 해당 리포지터리에서 작업할 때마다 따라야 할 규칙을 적으세요. 예를 들면 다음과 같습니다.

• 빌드 및 테스트 명령어
• 코드 리뷰 기준
• 리포지터리별 규칙
• 디렉터리별 지침

에이전트가 코드베이스에 대해 잘못 가정한 부분이 있으면 AGENTS.md에 올바른 내용을 명시하세요. 잘못된 가정을 바로잡을 때마다 에이전트에게 AGENTS.md를 업데이트하도록 요청하면 다음 작업에도 피드백이 반영됩니다.

AGENTS.md를 업데이트할 때

• 같은 실수가 반복될 때: 에이전트가 같은 실수를 거듭하면 규칙을 추가하세요.
• 문서를 지나치게 많이 읽을 때: 에이전트가 필요한 파일을 찾기는 하지만 문서를 너무 많이 읽는다면 어떤 디렉터리와 파일을 먼저 확인할지 명시하세요.
• PR 피드백이 반복될 때: 같은 피드백을 두 번 이상 남겼다면 규칙으로 정리하세요.
• 지침 점검을 자동화할 때: 예약 작업을 설정해 빠진 지침이 있는지 정기적으로 확인하고 AGENTS.md에 추가할 내용을 제안하도록 하세요. 예를 들어 매일 점검할 수 있습니다.

AGENTS.md와 함께 규칙을 자동으로 검사하는 도구도 사용하세요. pre-commit 훅, 린터, 타입 검사기가 문제를 미리 잡아 주므로 같은 실수가 반복되는 것을 더 효과적으로 예방할 수 있습니다.

Codex는 여러 위치에서 지침을 불러올 수 있습니다. 개발자 개인에게 적용할 전역 파일은 Codex 홈 디렉터리에 두고, 팀이 공유할 리포지터리별 파일은 해당 리포지터리에 커밋할 수 있습니다. 작업 디렉터리에 더 가까운 파일이 우선합니다. 전역 파일에는 리뷰 스타일, 답변의 상세도, 기본 설정 등 Codex가 개발자와 소통하는 방식에 관한 지침을 두세요. 리포지터리 파일에는 팀과 코드베이스에 적용되는 규칙을 담으세요.

AGENTS.md로 사용자 지정 지침 작성하기

스킬

스킬을 사용하면 반복되는 워크플로우에 필요한 기능을 Codex에서 재사용할 수 있습니다. 자세한 지침과 스크립트, 참고 자료를 함께 담아 여러 작업에서 그대로 활용할 수 있으므로 반복되는 워크플로우에는 스킬이 가장 적합한 경우가 많습니다. 스킬을 불러오면 에이전트는 최소한 각 스킬의 메타데이터를 확인할 수 있습니다. 따라서 사용자가 명시적으로 지정하지 않아도 Codex가 적합한 스킬을 찾아 선택할 수 있습니다. 처음부터 컨텍스트를 과도하게 늘리지 않고도 복잡한 워크플로우를 활용할 수 있습니다.

로컬에서 워크플로우를 작성하고 개선할 때는 스킬 폴더를 사용하세요. 해당 워크플로우를 제공하는 플러그인이 이미 있다면 먼저 설치해 검증된 구성을 재사용하세요. 직접 만든 워크플로우를 여러 팀에 배포하거나 커넥터와 함께 제공하려면 플러그인으로 패키징하세요. 워크플로우를 작성하는 형식은 스킬이고, 설치할 수 있는 배포 단위는 플러그인입니다.

스킬은 보통 SKILL.md 파일로 구성되며, 필요에 따라 스크립트, 참고 자료, 에셋을 추가할 수 있습니다.

스킬 디렉터리의 scripts/ 폴더에는 Codex가 워크플로우를 수행하면서 호출할 CLI 스크립트를 넣을 수 있습니다. 예를 들어 초기 데이터를 채우거나 검증을 실행하는 스크립트를 둘 수 있습니다. 워크플로우에 이슈 트래커, 디자인 도구, 문서 서버 같은 외부 시스템이 필요하면 스킬을 MCP와 함께 사용하세요.

SKILL.md 예시:

---
name: commit
description: Stage and commit changes in semantic groups. Use when the user wants to commit, organize commits, or clean up a branch before pushing.
---

1. `git add .` 명령어를 실행하지 마세요. 목적이 같은 파일끼리 묶어 스테이징하세요.
2. feat → test → docs → refactor → chore 순서로 유형별 커밋을 따로 만드세요.
3. 각 커밋의 변경 범위에 맞게 커밋 메시지를 간결하게 작성하세요.
4. 각 커밋은 한 가지 목적에 집중해 쉽게 리뷰할 수 있도록 하세요.

다음과 같은 경우에 스킬을 사용하세요.

• 릴리스 절차, 정기적인 리뷰, 문서 업데이트 등 반복되는 워크플로우
• 팀 고유의 전문 지식 활용
• 예시, 참고 자료 또는 보조 스크립트가 필요한 절차

스킬은 사용자 디렉터리에 두어 개발자 개인의 전역 스킬로 사용하거나, .agents/skills에 커밋해 팀의 리포지터리별 스킬로 사용할 수 있습니다. 해당 프로젝트에 적용되는 워크플로우라면 스킬을 .agents/skills에 두세요. 모든 리포지터리에서 사용하려는 스킬은 사용자 디렉터리에 두세요.

Codex는 스킬에 필요한 정보를 단계적으로 불러옵니다.

• 먼저 메타데이터(name, description)를 확인해 스킬을 찾습니다.
• 스킬을 선택했을 때만 SKILL.md를 불러옵니다.
• 필요한 경우에만 참고 자료를 읽거나 스크립트를 실행합니다.

스킬을 직접 호출할 수도 있고, 작업이 스킬 설명과 일치하면 Codex가 스스로 선택할 수도 있습니다. 스킬 설명을 명확하게 작성하면 Codex가 필요한 상황에서 해당 스킬을 더 정확하게 선택합니다.

스킬 만들기

MCP

MCP(Model Context Protocol)는 Codex를 외부 도구와 컨텍스트 제공자에 연결하는 표준 방식입니다. Figma, Linear, GitHub 또는 팀에서 사용하는 사내 지식 서비스처럼 원격에서 호스팅되는 시스템에 특히 유용합니다.

Codex에 이슈 트래커, 디자인 도구, 브라우저, 공유 문서 시스템 등 로컬 리포지터리 밖의 기능이 필요하면 MCP를 사용하세요.

각 구성 요소의 역할은 다음과 같습니다.

• 호스트: Codex
• 클라이언트: Codex 내부의 MCP 연결
• 서버: 외부 도구 또는 컨텍스트 제공자

MCP 서버는 다음을 제공할 수 있습니다.

• 도구(실행할 수 있는 동작)
• 리소스(읽을 수 있는 데이터)
• 프롬프트(재사용할 수 있는 프롬프트 템플릿)

이렇게 구분하면 무엇을 신뢰할지, 각 서버로 어떤 작업까지 할 수 있는지 판단하기 쉽습니다. 주로 컨텍스트를 제공하는 서버도 있고 강력한 작업 기능을 제공하는 서버도 있습니다.

실제로 MCP는 스킬과 함께 사용할 때 특히 유용한 경우가 많습니다.

• 스킬에서 워크플로우를 정의하고 사용할 MCP 도구를 지정합니다.

Model Context Protocol

하위 에이전트

역할이 서로 다른 에이전트를 만들고 프롬프트로 각자 도구를 다르게 사용하도록 지시할 수 있습니다. 예를 들어 한 에이전트에게는 특정 명령어와 설정으로 테스트를 실행하도록 하고, 다른 에이전트에는 디버깅에 필요한 프로덕션 로그를 가져오는 MCP 서버를 연결할 수 있습니다. 각 하위 에이전트는 맡은 작업에 집중하며 그에 맞는 도구를 사용합니다.

하위 에이전트

스킬과 MCP 함께 사용하기

스킬은 반복할 워크플로우를 정의하고 MCP는 그 워크플로우를 외부 도구 및 시스템에 연결합니다. 스킬이 MCP에 의존한다면 agents/openai.yaml에 해당 종속성을 선언하세요. 그러면 Codex가 필요한 MCP 서버를 자동으로 설치하고 연결할 수 있습니다(스킬 만들기 참고).

다음 단계

다음 순서로 구성하세요.

1. AGENTS.md로 사용자 지정 지침을 작성해 Codex가 리포지터리의 규칙을 따르도록 하세요. pre-commit 훅과 린터를 추가해 규칙을 자동으로 검사하세요.
2. 재사용할 수 있는 워크플로우가 이미 있다면 플러그인을 설치하세요. 없다면 스킬을 만들고, 공유할 때 플러그인으로 패키징하세요.
3. 워크플로우에 Linear, GitHub, 문서 서버, 디자인 도구 같은 외부 시스템이 필요하면 MCP를 사용하세요.
4. 실행 과정에서 출력이 많거나 전문성이 필요한 작업을 위임할 준비가 되면 하위 에이전트에게 맡기세요.