코덱스 툴 사용법 22: Custom Prompts는 이관 대기열이다 | DAKER 커뮤니티

코덱스 툴 사용법 22: Custom Prompts는 이관 대기열이다

Codex를 오래 쓰다 보면 같은 말을 계속 붙여 넣게 됩니다. “이 브랜치를 리뷰해줘”, “PR 설명을 써줘”, “테스트 실패만 원인 분석해줘” 같은 지시는 한 번 잘 만들어두면 다음 작업에서도 다시 쓰고 싶습니다.

OpenAI Codex 공식 문서에는 이 용도의 오래된 기능으로 Custom Prompts가 남아 있습니다. ~/.codex/prompts/*.md 파일을 만들고 /prompts:name 형태로 호출하는 방식입니다. 하지만 같은 문서는 Custom Prompts를 deprecated로 표시하고, 반복 지침에는 Skills 사용을 권장합니다. 이유는 분명합니다. Custom Prompt는 로컬 홈 디렉토리에 있고 명시 호출만 됩니다. Skill은 SKILL.md, 참고 자료, 스크립트, 자산을 함께 묶을 수 있고 Codex가 명시적 또는 암묵적으로 사용할 수 있습니다.

그래서 실무 기준은 이렇게 잡으면 됩니다. 새 반복 절차는 Skill로 만들고, 이미 있는 Custom Prompt는 “삭제할 것”이 아니라 “Skill로 옮길 후보 목록”으로 관리합니다.

한 줄 요약

Custom Prompt는 개인용 로컬 단축 명령이고, Skill은 팀이 검증하고 재사용할 수 있는 절차 패키지입니다.

Custom Prompt가 하는 일

공식 문서 기준으로 Custom Prompt는 Markdown 파일을 Codex CLI나 IDE extension의 slash command처럼 호출하게 해주는 기능입니다. 예를 들어 ~/.codex/prompts/draftpr.md를 만들면 /prompts:draftpr처럼 부를 수 있습니다.

파일 앞에는 YAML frontmatter를 둘 수 있습니다.

---
description: "PR 초안을 준비한다"
argument-hint: "FILES=<paths> PR_TITLE=<title>"
---

변경 파일을 확인하고 PR 초안을 작성한다.
FILES가 있으면 해당 파일을 우선 검토한다.
PR_TITLE이 있으면 제목 후보로 사용한다.

문서에 따르면 $1부터 $9, $ARGUMENTS, $FILE 같은 named placeholder를 쓸 수 있고, 공백이 있는 값은 따옴표로 넘길 수 있습니다. 파일을 수정한 뒤에는 새 세션이나 재시작이 필요할 수 있고, Codex는 prompts 디렉토리의 top-level Markdown 파일만 읽습니다.

이 기능은 여전히 개인 단축키로 유용합니다. 하지만 팀 표준 절차나 반복 자동화의 최종 형태로 삼기에는 한계가 있습니다.

왜 Skill이 기본값인가

OpenAI 문서는 반복 가능한 지침에는 Skill을 쓰라고 안내합니다. Skill은 디렉토리 하나 안에 SKILL.md를 두고, 필요하면 scripts/, references/, assets/ 같은 보조 자료를 함께 둡니다. SKILL.md에는 이름과 description이 들어가고, Codex는 명시 호출뿐 아니라 작업 설명이 맞을 때 암묵적으로도 Skill을 선택할 수 있습니다.

차이는 아래처럼 정리할 수 있습니다.

구분	Custom Prompt	Skill
저장 위치	보통 `~/.codex/prompts`	Skill 디렉토리
공유 방식	개인 로컬 파일 중심	저장소나 플러그인으로 공유 가능
호출 방식	명시 호출 중심	명시 호출과 암묵 선택
보조 자료	Markdown 한 파일 중심	참고 문서, 스크립트, 자산 포함 가능
현재 권장도	deprecated	반복 지침 권장 경로

따라서 새 workflow를 만들 때는 Custom Prompt를 먼저 만들기보다 Skill로 갈 수 있는지부터 봐야 합니다.

Mermaid로 보는 이관 결정 흐름

아래는 초안에 남겨둔 Mermaid 의사결정 흐름입니다. 게시 본문에는 같은 흐름을 SVG로 렌더링해 넣습니다.

Mermaid 원본:
flowchart TD
  A[반복해서 쓰는 지시인가?] -->|아니오| B[일회성 프롬프트로 둔다]
  A -->|예| C{팀 공유가 필요한가?}
  C -->|아니오| D[로컬 Custom Prompt로 유지]
  C -->|예| E{Skill로 만들 수 있는가?}
  E -->|예| F[SKILL.md와 참고 자료로 이관]
  E -->|아니오| G[비밀값, 사용처, 인자를 먼저 정리]

이 흐름의 핵심은 “반복된다”만으로는 부족하다는 점입니다. 혼자만 쓰는 로컬 단축키라면 Custom Prompt로 남겨도 됩니다. 하지만 팀원이 같은 절차를 써야 하거나, 자료와 스크립트가 붙거나, Codex가 상황에 맞게 자동 선택해야 한다면 Skill이 맞습니다.

로컬 prompts 폴더는 감사 대상이다

현재 내 로컬 환경에도 ~/.codex/prompts 아래에 code-reviewer.md, executor.md, test-engineer.md, researcher.md, dependency-expert.md 같은 역할 프롬프트가 있습니다. 이런 파일은 바로 지우면 안 됩니다. 다른 workflow나 팀 런타임이 아직 참조하고 있을 수 있기 때문입니다.

대신 아래 순서로 봅니다.

파일 이름과 description을 목록화한다.
실제로 slash menu에서 쓰는지 확인한다.
팀에서 공유해야 하는 지시인지 분류한다.
비밀값, 개인 경로, 오래된 모델명 같은 위험 문구를 찾는다.
유지, Skill 이관, 삭제 후보로 나눈다.

이 작업은 정리 작업처럼 보이지만 실제로는 운영 안전 작업입니다. 오래된 프롬프트는 팀의 최신 규칙을 우회할 수 있고, 반대로 아직 필요한 프롬프트를 지우면 자동화가 갑자기 끊길 수 있습니다.

좋은 Custom Prompt의 조건

Custom Prompt를 당장 유지해야 한다면 최소한 아래 조건을 맞추는 편이 좋습니다.

조건	이유
description이 명확함	slash menu에서 무엇인지 바로 알아야 함
argument-hint가 있음	호출할 때 필요한 값을 추측하지 않음
placeholder가 안정적임	`$FILE`, `$TICKET_ID`처럼 의미가 분명해야 함
완료 기준이 있음	Codex가 어디서 멈출지 알 수 있음
검증 명령이 있음	“잘 해줘”가 아니라 증거를 남김
비밀값이 없음	로컬 단축키라도 토큰이나 쿠키를 넣으면 안 됨

아래처럼 쓰면 유지보수가 어렵습니다.

알아서 리뷰하고 좋은 방향으로 정리해줘.

반대로 이렇게 쓰면 다음 단계가 분명합니다.

현재 브랜치를 기준 브랜치와 비교해 리뷰한다.
출력은 심각도, 파일 경로, 근거, 수정 제안으로 제한한다.
보안, 데이터 손실, 테스트 누락을 먼저 본다.
추측이 필요한 경우에는 근거 부족으로 표시한다.

두 번째 프롬프트는 나중에 Skill로 옮기기도 쉽습니다. 목적, 출력 형식, 검증 기준이 이미 분리되어 있기 때문입니다.

Skill로 옮길 때 바꿔야 하는 것

Custom Prompt를 Skill로 옮길 때는 파일을 복사하는 것으로 끝내면 안 됩니다. Skill은 “긴 프롬프트 파일”이 아니라 작은 실행 매뉴얼입니다.

이관할 때는 아래처럼 구조를 바꿉니다.

Custom Prompt에 있던 것	Skill에서 바꿀 것
파일 첫머리 description	`SKILL.md`의 name과 description
긴 지시문	단계별 실행 규칙
붙여 넣은 참고 자료	`references/` 파일
반복 shell 예시	`scripts/` 실행 파일
결과 형식 설명	success criteria와 output contract
주의 문구	constraints와 ask gate

특히 description은 중요합니다. Codex가 암묵적으로 Skill을 선택하려면 “언제 써야 하는지”가 앞부분에 분명해야 합니다. “좋은 코딩 도우미” 같은 설명은 거의 쓸모가 없습니다. “보안 리뷰 요청 시 변경 파일을 읽고 심각도별 findings를 출력한다”처럼 trigger와 범위가 보여야 합니다.

언제 그냥 지워도 되는가

Custom Prompt를 삭제해도 되는 경우는 생각보다 적습니다. 아래 조건을 모두 만족할 때만 삭제 후보로 봅니다.

최근에 호출한 적이 없다.
같은 역할을 하는 Skill이 이미 있다.
자동화나 팀 스크립트가 참조하지 않는다.
안에 중요한 운영 지식이 없다.
삭제 전에 파일 내용을 저장소나 문서에서 대체했다.

그 전에는 파일명을 deprecated-로 바꾸거나, frontmatter description에 “Skill로 이관됨”이라고 적는 편이 더 안전합니다. 정리의 목표는 파일 수를 줄이는 것이 아니라, 사람이 어떤 절차를 신뢰해야 하는지 헷갈리지 않게 만드는 것입니다.

팀 가이드에 넣을 문장

Codex를 팀에서 쓴다면 아래 문장을 AGENTS.md나 온보딩 문서에 넣어둘 만합니다.

반복 가능한 Codex 절차는 새 Custom Prompt로 만들지 말고 Skill로 만든다.
기존 ~/.codex/prompts 파일은 개인 단축키로만 유지하고, 팀 공유가 필요하면 SKILL.md 구조로 이관한다.
프롬프트나 Skill에는 비밀값, 쿠키, 개인 계정 토큰을 넣지 않는다.
완료 기준과 검증 명령이 없는 재사용 지침은 운영 절차로 승인하지 않는다.

이 문장은 “Custom Prompt 금지”보다 낫습니다. 이미 돌아가는 로컬 단축키를 갑자기 끊지 않으면서도, 새 표준은 Skill로 모이게 하기 때문입니다.

시니어 엔지니어의 기준

프롬프트 재사용은 생산성 기능이지만, 동시에 운영 규칙입니다. 오래된 단축 명령 하나가 최신 보안 기준을 우회할 수 있고, 반대로 잘 정리된 Skill 하나가 팀 전체의 리뷰 품질을 끌어올릴 수 있습니다.

오늘 ~/.codex/prompts를 한 번 열어보세요. 그리고 각 파일에 대해 이 질문만 던지면 됩니다.

이 지시는 나만 쓰는 단축키인가, 팀이 검증해야 하는 절차인가?

전자는 Custom Prompt로 남겨도 됩니다. 후자는 Skill로 옮겨야 합니다. 좋은 Codex 운영은 프롬프트를 많이 저장하는 것이 아니라, 반복할 가치가 있는 절차를 올바른 표면에 두는 것입니다.

참고: OpenAI Codex의 Custom Prompts, Agent Skills, CLI slash commands, Codex app commands 문서를 2026-06-15 Asia/Seoul 기준으로 확인했습니다.