맞춤 설정

맞춤 설정은 Codex가 팀의 업무 방식에 맞게 작동하도록 만드는 방법입니다.

Codex의 맞춤 설정은 함께 작동하는 몇 가지 계층으로 구성됩니다:

• 프로젝트 지침 (AGENTS.md): 지속적으로 적용할 지침
• 메모리: 이전 작업에서 학습한 유용한 컨텍스트
• 스킬: 재사용 가능한 워크플로우와 도메인 전문 지식
• MCP: 외부 도구 및 공유 시스템에 대한 접근
• 하위 에이전트: 전문 하위 에이전트에 작업 위임

이 기능들은 서로 경쟁하는 것이 아니라 상호 보완합니다. AGENTS.md는 동작 방식을 정하고, 메모리는 로컬 컨텍스트를 이후 작업에도 이어가며, 스킬은 반복 가능한 프로세스를 패키징하고, MCP는 Codex를 로컬 워크스페이스 외부의 시스템에 연결합니다.

AGENTS 지침

AGENTS.md는 레포지토리와 함께 유지되며 에이전트가 작업을 시작하기 전에 적용되는 프로젝트 지침을 Codex에 제공합니다. 간결하게 유지하세요.

다음과 같이 Codex가 레포지토리에서 항상 따르도록 할 규칙을 작성하세요:

• 빌드 및 테스트 명령
• 검토 기준
• 레포지토리별 규칙
• 디렉터리별 지침

에이전트가 코드베이스에 대해 잘못된 가정을 하면 이를 AGENTS.md에서 바로잡고, 수정 사항이 계속 적용되도록 에이전트에게 AGENTS.md를 업데이트하라고 요청하세요. 이 과정을 피드백 루프로 활용하세요.

AGENTS.md 업데이트 시점

• 반복되는 실수: 에이전트가 같은 실수를 반복하면 규칙을 추가하세요.
• 문서를 과도하게 읽는 경우: 적절한 파일은 찾지만 너무 많은 문서를 읽는다면 우선할 디렉터리와 파일을 지정하는 라우팅 지침을 추가하세요.
• 반복되는 PR 피드백: 같은 피드백을 두 번 이상 남기게 된다면 규칙으로 명문화하세요.
• GitHub에서: Pull Request 댓글에서 @codex를 태그해 요청하고(예: @codex add this to AGENTS.md), 업데이트를 클라우드 채팅에 위임하세요.
• 드리프트 검사 자동화: 예약 작업을 사용해 지침의 누락된 부분을 찾고 AGENTS.md에 추가할 내용을 제안하는 검사를 정기적으로 실행하세요(예: 매일).

AGENTS.md를 해당 규칙을 강제하는 인프라와 함께 사용하세요. pre-commit 훅, 린터, 타입 검사기가 문제가 눈에 띄기 전에 이를 감지하므로 시스템이 반복되는 실수를 더 효과적으로 방지할 수 있습니다.

Codex는 여러 위치에서 지침을 로드할 수 있습니다. 여기에는 개발자 개인을 위한 Codex 홈 디렉터리의 전역 파일과 팀이 체크인할 수 있는 레포지토리별 파일이 포함됩니다. 작업 디렉터리에 가까운 파일일수록 우선 적용됩니다. 전역 파일에는 Codex가 사용자와 소통하는 방식(예: 검토 스타일, 상세도, 기본값)을 지정하고, 레포지토리 파일에는 팀 및 코드베이스 규칙만 작성하세요.

AGENTS.md를 사용한 맞춤 지침

스킬

스킬은 반복 가능한 워크플로우에 재사용할 수 있는 기능을 Codex에 제공합니다. 스킬은 작업 간에 재사용할 수 있으면서 더 상세한 지침, 스크립트, 참조 자료를 지원하므로 재사용 가능한 워크플로우에 가장 적합한 경우가 많습니다. 스킬은 로드되어 에이전트에 표시되며(적어도 메타데이터는 표시됨), Codex는 이를 찾아 작업에 맞으면 자동으로 선택할 수 있습니다. 이렇게 하면 처음부터 컨텍스트를 불필요하게 늘리지 않고도 풍부한 워크플로우를 사용할 수 있습니다.

스킬 폴더를 사용해 로컬에서 워크플로우를 작성하고 개선하세요. 해당 워크플로우용 플러그인이 이미 있다면 먼저 설치하여 검증된 설정을 재사용하세요. 자체 워크플로우를 여러 팀에 배포하거나 커넥터와 함께 번들로 제공하려면 플러그인으로 패키징하세요. 스킬은 계속 워크플로우 작성 형식이고, 플러그인은 설치 가능한 배포 단위입니다.

스킬은 일반적으로 SKILL.md 파일과 선택적 스크립트, 참조 자료, 애셋으로 구성됩니다.

스킬 디렉터리에는 워크플로우의 일부로 Codex가 호출하는 CLI 스크립트(예: 시드 데이터 생성 또는 검증 실행)가 있는 scripts/ 폴더를 포함할 수 있습니다. 워크플로우에 외부 시스템(이슈 트래커, 디자인 도구, 문서 서버)이 필요하다면 스킬을 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. Do not run `git add .`. Stage files in logical groups by purpose.
2. Group into separate commits: feat → test → docs → refactor → chore.
3. Write concise commit messages that match the change scope.
4. Keep each commit focused and reviewable.

스킬 사용 사례:

• 반복 가능한 워크플로우(릴리스 단계, 검토 절차, 문서 업데이트)
• 팀별 전문 지식
• 예시, 참조 자료 또는 도우미 스크립트가 필요한 절차

스킬은 개발자 개인용으로 사용자 디렉터리에 두는 전역 스킬이거나, 팀에서 사용하도록 .agents/skills에 체크인하는 레포지토리별 스킬일 수 있습니다. 워크플로우가 해당 프로젝트에 적용된다면 레포지토리 스킬을 .agents/skills에 두고, 모든 레포지토리에서 사용할 스킬은 사용자 디렉터리에 두세요.

Codex는 스킬에 점진적 공개 방식을 사용합니다:

• 스킬을 찾기 위해 먼저 메타데이터(name, description)를 확인합니다
• 스킬이 선택된 경우에만 SKILL.md를 로드합니다
• 필요한 경우에만 참조 자료를 읽거나 스크립트를 실행합니다

스킬을 명시적으로 호출할 수도 있으며, 작업이 스킬 설명과 일치하면 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는 이러한 워크플로우를 외부 도구 및 시스템에 연결합니다. 스킬에 MCP 종속성이 있다면 Codex가 MCP를 자동으로 설치하고 연동할 수 있도록 해당 종속성을 agents/openai.yaml에 선언하세요(스킬 빌드 참조).

다음 단계

다음 순서로 구성하세요:

1. Codex가 레포지토리 규칙을 따르도록 AGENTS.md를 사용한 맞춤 지침을 작성하세요. pre-commit 훅과 린터를 추가해 해당 규칙을 강제 적용하세요.
2. 재사용 가능한 워크플로우가 이미 있다면 플러그인을 설치하세요. 그렇지 않다면 스킬을 만들고, 공유하려면 해당 스킬을 플러그인으로 패키징하세요.
3. 워크플로우에 외부 시스템(Linear, GitHub, 문서 서버, 디자인 도구)이 필요하면 MCP를 사용하세요.
4. 번거롭거나 전문성이 필요한 작업을 하위 에이전트에게 위임할 준비가 되면 하위 에이전트를 사용하세요.