ChatGPT 문서
한국어
문의 goolvyouyou@gmail.com

사용자 지정

프로젝트 지침, 스킬, MCP, 하위 에이전트로 Codex를 사용자 지정하는 방법

사용자 지정은 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 add this to AGENTS.md)과 함께 @codex을 태그하여 클라우드 채팅에 업데이트를 위임하세요.
  • 변경 감지 검사 자동화: 예약된 작업을 사용하여 지침의 누락을 찾고 AGENTS.md에 추가할 내용을 제안하는 반복 검사(예: 매일)를 실행하세요.

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

Codex는 여러 위치에서 지침을 불러올 수 있습니다. Codex 홈 디렉터리의 전역 파일(개발자 개인용)과 팀이 체크인할 수 있는 저장소별 파일을 사용할 수 있습니다. 작업 디렉터리에 더 가까운 파일이 우선합니다. 전역 파일은 Codex가 사용자와 소통하는 방식(예: 리뷰 스타일, 답변 상세도, 기본값)을 정하는 데 사용하고, 저장소 파일은 팀과 코드베이스 규칙에 집중하세요.

<FileTree class="mt-4" tree={[ { name: "~/.codex/", open: true, children: [ { name: "AGENTS.md", comment: "전역(개발자 개인용)" }, ], }, { name: "repo-root/", open: true, children: [ { name: "AGENTS.md", comment: "저장소별(팀용)" }, ], }, ]} />

AGENTS.md를 사용한 사용자 지정 지침

스킬

스킬은 반복 가능한 워크플로에 사용할 수 있는 재사용 가능한 기능을 Codex에 제공합니다. 스킬은 작업 전반에서 재사용할 수 있으면서도 더 풍부한 지침, 스크립트, 참조 자료를 지원하므로 재사용 가능한 워크플로에 가장 적합한 경우가 많습니다. 스킬은 에이전트에 로드되어 표시되므로(최소한 메타데이터는 표시됨) Codex가 이를 암묵적으로 발견하고 선택할 수 있습니다. 따라서 처음부터 맥락을 불필요하게 늘리지 않으면서 풍부한 워크플로를 사용할 수 있습니다.

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

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

<FileTree class="mt-4" tree={[ { name: "my-skill/", open: true, children: [ { name: "SKILL.md", comment: "필수: 지침 + 메타데이터" }, { name: "scripts/", comment: "선택 사항: 실행 코드" }, { name: "references/", comment: "선택 사항: 문서" }, { name: "assets/", comment: "선택 사항: 템플릿, 리소스" }, ], }, ]} />

스킬 디렉터리에는 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에 배치하고, 모든 저장소에서 사용하려는 스킬에는 사용자 디렉터리를 사용하세요.

계층 전역 저장소
AGENTS ~/.codex/AGENTS.md 저장소 루트 또는 중첩 디렉터리의 AGENTS.md
스킬 ~/.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가 이를 자동으로 설치하고 연결할 수 있도록 agents/openai.yaml에 해당 의존성을 선언하세요(스킬 빌드하기 참조).

다음 단계

다음 순서로 구성하세요.

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