Ch6. 프롬프트/스킬 설계

Codex는 목표·제약·검증 기준이 명확할수록 안정적으로 동작합니다. 시니어 개발자라면 프롬프트를 "작업 명세" 수준으로 쓰고, 반복되는 패턴은 Skills로 정리해 둡니다.

프롬프트 = 작업 명세(시니어용 포맷)

아래 6가지만 고정해도 결과 품질이 안정됩니다.

• 목표: 무엇을 만들거나 고칠지(정확한 산출물)
• 범위: 수정 가능한 폴더/파일, 제외할 영역(Non-goals)
• 제약: 보안/성능/호환성/코딩 컨벤션, "절대 하지 말 것"
• 검증: 통과해야 하는 테스트/체크, 재현/검증 명령
• 리스크: 변경 위험이 큰 지점(마이그레이션, 스키마 변경, 배포 영향)
• 출력 포맷: 최종 응답 형식(예: 체크리스트, diff 요약, JSON 스키마 등)

[목표]
- ...

[범위]
- 수정 가능: ...
- 제외: ...

[제약]
- ...

[검증]
- ...

[리스크]
- ...

[출력]
- ...

컨텍스트를 "정확히" 주는 법

• @로 파일을 찍어서 준다: 작성기에서 @ 입력 시 퍼지 파일 검색이 동작합니다. Tab/Enter로 삽입
• /mention으로 파일/폴더 첨부: 레포 전체 대신 지금 볼 파일/폴더를 지정해 작업 시간 절감
• Ctrl+G로 외부 에디터: 긴 프롬프트는 외부 에디터에서 작성(VISUAL/EDITOR 환경변수 설정)
• 긴 세션은 /compact로 정리: 긴 실행 뒤에는 요약을 남겨 컨텍스트 윈도우를 절약
• 작업 루틴 고정: /diff → /review → 테스트 → 요약을 팀 기본으로

음성 입력 (실험적, 0.105.0+)

스페이스바를 길게 누르면 음성 받아쓰기가 시작됩니다. 손이 바쁠 때 빠르게 지시하기 좋습니다.

지속 규칙: AGENTS.md(레포에 남는 계약)

Codex는 작업 전에 AGENTS.md 파일을 자동으로 읽습니다.

탐색 순서:

1. ~/.codex/AGENTS.override.md (또는 AGENTS.md) — 사용자 전역 설정
2. 프로젝트 루트에서 현재 디렉토리까지 순회하며 각 경로의 AGENTS.override.md → AGENTS.md

AGENTS.md는 현재 60,000+ 오픈소스 프로젝트가 쓰고 있고, Linux Foundation 산하 Agentic AI Foundation이 표준을 관리합니다.

팀에서는 아래를 표준으로 잡아 두면 효과가 큽니다.

• 레포 루트에 1개: 공용 규칙(금지/허용, 커밋 규칙, 테스트 규칙)
• 서브디렉토리별로 추가: 모노레포/서비스별 특이사항(폴더 규칙, 소유권, 도메인 용어)
• 리뷰 가능한 형태로: 규칙은 코드와 같이 리뷰/변경 관리("문서가 곧 정책")
• 피드백 루프: 반복되는 실수 → AGENTS.md에 규칙 추가, 불필요한 문서 탐색 → 라우팅 가이드 추가

Skills 체계 (정식)

Skills는 SKILL.md + 선택적 scripts/references/assets로 구성된 재사용 가능한 워크플로우 번들입니다.

디렉토리 구조

my-skill/
├── SKILL.md           (필수: name, description 포함)
├── scripts/           (선택: 실행 스크립트)
├── references/        (선택: 참조 문서)
├── assets/            (선택: 템플릿, 리소스)
└── agents/
    └── openai.yaml    (선택: UI 메타데이터, 의존성)

SKILL.md 최소 구조

---
name: release-notes
description: PR 기반 릴리즈 노트 자동 생성. PR이 머지된 후 트리거.
---
1. 최근 머지된 PR 목록을 수집
2. 각 PR의 변경사항을 요약
3. 카테고리별로 정리된 릴리즈 노트 생성

스킬 위치(탐색 순서)

Progressive Disclosure

Codex는 스킬의 메타데이터(name, description)만 먼저 로드하고, 실제로 쓸 때만 전체 SKILL.md를 읽습니다. 스킬이 아무리 많이 등록돼 있어도 컨텍스트 윈도우를 아낄 수 있습니다.

스킬 호출

• 명시적: 추천 목록이나 문맥 힌트로 스킬을 확인한 뒤 $skill-name으로 직접 호출
• 암묵적: 사용자 프롬프트가 스킬의 description에 매칭되면 Codex가 자동 선택
• 설치: $skill-installer로 외부 레포에서 스킬 설치

config에서 스킬 비활성화

[[skills.config]]
path = "/path/to/skill/SKILL.md"
enabled = false

agents/openai.yaml (선택)

interface:
  display_name: '릴리즈 노트'
  short_description: 'PR 기반 릴리즈 노트 생성'
  brand_color: '#3B82F6'

policy:
  allow_implicit_invocation: false # 명시적 호출만 허용

dependencies:
  tools:
    - type: 'mcp'
      value: 'github'
      description: 'GitHub MCP 서버'

Plugins와 @plugin 멘션 (0.110.0~0.117.0)

최근 릴리스에서는 Skills/MCP/apps를 플러그인 단위로 묶어 배포하는 방향이 뚜렷해졌습니다.

• Plugin catalog: 로컬 marketplace 또는 config 기반으로 skills/MCP/app connector를 로드
• 세션 시작 시 플러그인 인벤토리 주입: Codex가 어떤 플러그인이 활성화되어 있는지 먼저 알고 시작
• @plugin 멘션: 채팅에서 특정 플러그인을 직접 언급하면, 관련된 MCP/app/skill 컨텍스트를 의도적으로 붙일 수 있음
• 제품 범위 플러그인 sync (0.117.0): 시작 시 product-scoped plugin을 동기화하고 설치 상태를 더 일관되게 유지
• /plugins 브라우저 (0.117.0): 플러그인을 전용 메뉴에서 탐색·설치·제거하는 흐름이 추가됨

실전 팁:

• 플러그인 이름은 짧고 모호하지 않게 유지합니다
• "한 플러그인 = 한 업무 컨텍스트" 원칙을 지키면 @plugin 멘션 품질이 좋아집니다
• 위험한 외부 시스템 플러그인은 기본 비활성화하고, 승인 가능한 팀만 enable 하세요

[예시]
- "@release-notes 플러그인 기준으로 이번 변경을 요약해줘"
- "@figma-mcp 컨텍스트를 포함해서 이 화면 수정 포인트를 정리해줘"
- "@jira-triage 플러그인으로 이 이슈를 분류하고 다음 액션을 제안해줘"

플러그인 Marketplace와 라이프사이클 관리 (0.113.0)

0.113.0에서 플러그인 워크플로우가 크게 넓어졌습니다. Marketplace 검색, 메타데이터 강화, 설치 시 인증 검사, 삭제 엔드포인트가 들어오면서 플러그인 라이프사이클을 처음부터 끝까지 관리할 수 있습니다.

Marketplace 검색

플러그인을 로컬 config에서만 관리하던 방식에서 벗어나, 중앙 marketplace에서 검색·설치할 수 있습니다.

# marketplace에서 플러그인 검색
codex plugin search "release-notes"

# 검색 결과에서 바로 설치
codex plugin install @org/release-notes-plugin

강화된 메타데이터 (plugin/list)

plugin/list 응답에 버전, 의존성, 권한 요구사항, 호환 모델 같은 메타데이터가 함께 담깁니다. 팀에서 플러그인 호환성을 미리 검증하거나, CI에서 플러그인 인벤토리를 자동 감사할 때 쓰기 좋습니다.

설치 시 인증 검사

외부 API를 쓰는 플러그인은 설치 시점에 필요한 인증 정보(API 키, OAuth 토큰 등)가 있는지 자동으로 확인합니다. 인증이 빠져 있으면 설치를 막고, 어떤 설정이 필요한지 안내합니다.

플러그인 삭제 (plugin/uninstall)

더 이상 사용하지 않는 플러그인을 깔끔하게 제거할 수 있습니다.

# 플러그인 삭제
codex plugin uninstall @org/release-notes-plugin

플러그인 설치 프롬프트 (0.116.0)

0.116.0부터 Codex가 빠진 플러그인의 설치를 먼저 제안합니다. 프롬프트나 스킬에 특정 플러그인이 필요한데 아직 안 깔려 있으면, Codex가 설치할지 물어봅니다.

• Suggestion allowlist: config에서 설치 제안이 허용되는 플러그인 목록을 지정할 수 있어, 승인되지 않은 플러그인이 무분별하게 제안되는 것을 방지합니다
• 원격 동기화: 플러그인 설치/제거 상태를 원격으로 동기화해, 여러 머신에서 같은 플러그인 환경을 유지합니다
• 팀 운영에서는 allowlist를 조직 표준으로 두고, 원격 동기화로 개발자 간 환경 편차를 줄이길 권장합니다

내장 시스템 스킬 비활성화 (0.114.0)

0.114.0부터 config에서 번들된 시스템 스킬을 한 번에 끄는 스위치가 생겼습니다. 조직 자체 스킬만 쓰거나, 시스템 스킬과 충돌을 막고 싶을 때 쓰기 좋습니다.

[skills]
disable_bundled = true   # 내장 스킬(skill-creator, plan 등) 비활성화

참고 문서

• Prompting 가이드: https://developers.openai.com/codex/prompting (영어)
• Skills: https://developers.openai.com/codex/skills (영어)
• AGENTS.md 가이드: https://developers.openai.com/codex/guides/agents-md (영어)
• Customization: https://developers.openai.com/codex/concepts/customization (영어)
• 슬래시 커맨드: https://developers.openai.com/codex/cli/slash-commands (영어)
• Team Config(스킬/규칙 공유): https://developers.openai.com/codex/team-config (영어)
• Rules: https://developers.openai.com/codex/rules (영어)
• GitHub Releases: https://github.com/openai/codex/releases (영어)