부록 D. AGENTS.md / SKILL.md 템플릿 모음

좋은 템플릿은 설명보다 빠르다. 특히 Codex를 처음 세팅할 때는 더 그렇다. AGENTS.md와 SKILL.md는 원리를 이해하는 것도 중요하지만, 실제로는 빈칸을 채워 넣고 바로 돌려보는 순간부터 감이 잡힌다. 이 부록은 그 출발점을 만들기 위한 페이지다.

AGENTS.md는 세션 시작 시 읽히는 프로젝트 운영 규칙서이고, 디렉터리 계층에 따라 가까운 파일이 더 강하게 작동한다. 같은 레벨에서는 AGENTS.override.md가 일반 AGENTS.md를 대체한다.¹ SKILL.md는 name과 description이 먼저 읽히고, 실제 본문과 보조 자료는 필요할 때만 불러오는 구조라서, 설명보다 트리거 문장과 핵심 절차가 특히 중요하다.²³

이 부록의 사용법은 단순하다. 먼저 가장 짧은 템플릿을 복사해 넣고, Codex가 자주 틀리는 부분만 한 줄씩 추가하면 된다. 처음부터 완벽한 문서를 만들려 하지 않는 편이 오히려 더 잘 굴러간다.

가장 먼저 복사할 템플릿

처음이라면 아래 두 개부터 시작하면 된다. 하나는 프로젝트 루트용 AGENTS.md, 하나는 첫 번째 팀 스킬용 SKILL.md다.

최소 AGENTS.md 템플릿

# AGENTS.md

## Project
- This repository is a [프로젝트 한 줄 설명]
- Main stack: [예: Next.js App Router, TypeScript, Supabase]
- Package manager: [pnpm / npm / bun]

## Commands
- Install: `[설치 명령]`
- Dev: `[개발 서버 명령]`
- Lint: `[린트 명령]`
- Typecheck: `[타입체크 명령]`
- Test: `[테스트 명령]`
- Build: `[빌드 명령]`

## Structure
- `[디렉터리]`: [역할]
- `[디렉터리]`: [역할]
- `[디렉터리]`: [역할]

## Rules
- Use `[패키지 매니저]`, never `[금지 도구]`
- Do not modify `[생성 파일/금지 경로]`
- Access env only through `[env 진입점]`
- New `[기능 종류]` must include `[테스트/스키마/문서]`
- Follow existing patterns before introducing new libraries

## Done when
- `[검증 1]` passes
- `[검증 2]` passes
- `[변경 영향에 맞는 테스트]` is updated

최소 SKILL.md 템플릿

---
name: [skill-name]
description: Use this skill when [언제 쓰는지]. Focus on [핵심 판단 기준]. Do not use it for [쓰면 안 되는 상황].
---

# [스킬 제목]

## Goal
[이 스킬이 달성해야 할 목표]

## Inputs
- [입력 1]
- [입력 2]
- [입력 3]

## Workflow
1. [첫 단계]
2. [둘째 단계]
3. [셋째 단계]
4. [출력 정리 단계]

## Guardrails
- [하면 안 되는 것]
- [위험 시 확인할 것]
- [추측 금지 규칙]

## Output
- [출력 항목 1]
- [출력 항목 2]
- [출력 항목 3]

이 두 템플릿만 제대로 채워도 Codex는 갑자기 덜 헤맨다. 마치 새 팀원이 "이 프로젝트는 어디부터 봐야 하나요?"를 덜 묻게 되는 것과 비슷하다.

AGENTS.md 템플릿 모음

AGENTS.md는 철학 문서가 아니라 작업 문서다. 그래서 멋진 문장보다 오해를 줄이는 문장이 더 좋다. 아래 템플릿은 한국 개발자가 실제로 자주 만들 프로젝트를 기준으로 골랐다.

템플릿 1. 전역 ~/.codex/AGENTS.md

전역 AGENTS.md는 개인 습관만 넣는 것이 좋다. 여기에 프로젝트 구조를 잔뜩 넣으면 나중에 중요한 프로젝트 규칙이 32KiB 한도 안에서 밀려날 수 있다.¹⁴

# AGENTS.md

## My defaults
- Prefer small, reviewable diffs
- Reuse existing patterns before introducing new dependencies
- When changing behavior, look for the nearest relevant test and update it
- If requirements are ambiguous, ask before changing public behavior

## Coding preferences
- Prefer explicit naming over abbreviations
- Prefer deleting dead code over leaving commented-out code
- Prefer existing lint/type/test tooling; do not introduce a new tool unless necessary

## Safety
- Never print secrets or copy credentials into files
- Avoid destructive commands unless explicitly requested
- If validation was not run, state that clearly

템플릿 2. Next.js + Supabase SaaS 루트용

이 템플릿은 한국에서 가장 많이 복붙될 가능성이 높은 조합이다. 로그인, 대시보드, 결제, 관리자 화면이 붙는 SaaS를 상상하면 된다.

# AGENTS.md

## Project
- This repository is a SaaS web app built with Next.js App Router and Supabase.
- Main stack: Next.js, TypeScript strict, Tailwind CSS, Supabase
- Package manager: pnpm

## Commands
- Install: `pnpm install`
- Dev: `pnpm dev`
- Lint: `pnpm lint`
- Typecheck: `pnpm typecheck`
- Test: `pnpm test`
- Build: `pnpm build`

## Structure
- `app/`: routes, layouts, server actions, route handlers
- `components/`: reusable UI components
- `lib/`: clients, helpers, shared server utilities
- `supabase/`: migrations, local config, seed-related files
- `tests/`: integration and e2e tests if not colocated

## Rules
- Use `pnpm`, never `npm`
- Use App Router patterns; do not add Pages Router files
- New API endpoints go under `app/api/`
- Access env only through `src/env.ts` or the project env wrapper
- Never edit old migration files in `supabase/migrations/`; create a new migration instead
- Prefer server-side data access for privileged operations
- If auth flow changes, review middleware, callback handling, and protected routes together
- Match existing UI primitives before adding a new component pattern

## Done when
- `pnpm lint` passes
- `pnpm typecheck` passes
- Relevant tests pass
- Auth, schema, or route changes include test updates or a clear gap note

템플릿 3. Express + MongoDB API 서버용

백엔드는 짧은 코드가 정답처럼 보일 때가 많다. 그래서 AGENTS.md가 더 중요하다. "짧게"보다 "레이어를 지켜서"가 핵심이기 때문이다.

# AGENTS.md

## Project
- This repository is an Express API server for a production service.
- Main stack: Express, TypeScript, MongoDB, Mongoose, Zod
- Package manager: pnpm

## Commands
- Install: `pnpm install`
- Dev: `pnpm dev`
- Lint: `pnpm lint`
- Typecheck: `pnpm typecheck`
- Test: `pnpm test`
- Build: `pnpm build`

## Structure
- `src/routes/`: routing only
- `src/controllers/`: request/response coordination
- `src/services/`: business logic
- `src/repositories/`: all database access
- `src/schemas/`: request/response validation schemas
- `src/middlewares/`: auth, errors, logging

## Rules
- Do not query MongoDB directly from routes or controllers
- Validate all new request bodies, params, and query values with Zod
- Reuse the common error middleware; do not add ad-hoc response shapes
- Use existing repository patterns before creating new data access styles
- Never modify generated files under `src/generated/`
- If changing indexes or query patterns, note expected impact on read/write performance

## Done when
- `pnpm lint` passes
- `pnpm typecheck` passes
- `pnpm test` passes
- New or changed endpoints include validation and tests

템플릿 4. 모노레포 루트용

모노레포에서는 루트 파일이 모든 걸 설명하려 들면 금방 무거워진다. 루트는 공통 규칙만 잡고, 앱별 세부 규칙은 하위 AGENTS.md로 내려보내는 편이 낫다.¹

# AGENTS.md

## Project
- This repository is a monorepo for a consumer superapp clone.
- Main tools: pnpm workspaces, Turbo, TypeScript

## Commands
- Install: `pnpm install`
- Dev all: `pnpm dev`
- Lint all: `pnpm lint`
- Test all: `pnpm test`
- Typecheck all: `pnpm typecheck`
- Build all: `pnpm build`

## Workspace map
- `apps/web/`: customer-facing Next.js app
- `apps/admin/`: internal admin dashboard
- `apps/api/`: Express backend API
- `packages/ui/`: shared design system
- `packages/config/`: shared configs

## Rules
- Run commands from the repo root unless a package file says otherwise
- Use `pnpm`, never `npm`
- Prefer editing the owning package instead of duplicating shared code
- Keep changes scoped to the target app/package unless cross-package work is required
- Check for a nearer AGENTS.md before introducing package-specific conventions

## Done when
- Affected package checks pass
- Cross-package changes are called out explicitly
- Shared package changes mention downstream impact

템플릿 5. apps/web/AGENTS.md

루트가 큰 지도라면, 하위 AGENTS.md는 동네 골목 지도다. 실제로 길을 잃지 않게 만드는 건 보통 이쪽이다.

# AGENTS.md

## Scope
- Rules in this file apply to the web app under `apps/web/`.

## Commands
- Dev: `pnpm --filter web dev`
- Lint: `pnpm --filter web lint`
- Typecheck: `pnpm --filter web typecheck`
- Test: `pnpm --filter web test`

## Structure
- `app/`: routes and layouts
- `features/`: domain-specific UI and logic
- `components/ui/`: shared presentational components
- `lib/`: client wrappers and utilities

## Rules
- Use existing feature folders before creating a new top-level directory
- Prefer server components unless client interactivity is required
- Add `use client` only when necessary
- Forms should follow the existing validation and mutation flow
- Accessibility is mandatory for new interactive UI
- Do not mix API-only logic into UI components

## Done when
- Relevant web checks pass
- New UI states cover loading, empty, error, and success when applicable
- Accessibility labels and keyboard interaction are considered

템플릿 6. apps/api/AGENTS.md

# AGENTS.md

## Scope
- Rules in this file apply to the backend API under `apps/api/`.

## Commands
- Dev: `pnpm --filter api dev`
- Lint: `pnpm --filter api lint`
- Typecheck: `pnpm --filter api typecheck`
- Test: `pnpm --filter api test`

## Rules
- Keep route handlers thin
- Business logic belongs in services
- Database access belongs in repositories only
- All externally visible errors must use the common response contract
- If a change affects idempotency, retries, or transaction boundaries, call it out explicitly
- For schema changes, include migration notes and rollback considerations

## Done when
- API checks pass
- Contract changes are reflected in tests or documented as breaking
- Risky data changes include a rollback note

템플릿 7. AGENTS.override.md 핫픽스 모드

override 파일은 같은 레벨의 일반 AGENTS.md를 덮어쓴다. 즉 덧붙이는 문서가 아니라 임시 운전 모드 전환 스위치에 가깝다.¹

아래 템플릿은 결제 장애나 운영 핫픽스 때 유용하다.

# AGENTS.override.md

## Hotfix mode
- This session is for production hotfix work only.
- Limit changes to `services/payments/` and directly related tests.

## Priority
- Minimize blast radius
- Prefer the smallest safe fix
- Report suspected root cause separately from confirmed facts

## Commands
- Test payments: `pnpm test payments`
- Lint changed files: `pnpm lint`

## Rules
- Do not refactor unrelated code
- Do not rename files or symbols unless required for the fix
- If the fix is uncertain, stop and present the safest options
- State exactly what was validated and what remains unverified

## Done when
- Payment-specific tests pass
- Scope stayed limited
- Remaining risks are documented clearly

SKILL.md 템플릿 모음

스킬은 반복 작업을 파일로 굳히는 장치다. 그래서 잘 만든 스킬은 "프롬프트를 잘 치는 사람"의 장점을 팀 자산으로 바꿔 준다. 여기서는 가장 먼저 만들 가치가 높은 스킬부터 실전용 예시로 정리했다.

템플릿 1. 범용 스켈레톤

이건 모든 스킬의 뼈대다. 이름은 짧고 명확하게, description은 언제 쓰는지와 언제 쓰지 않는지를 같이 적는 것이 좋다.²

---
name: [short-hyphen-name]
description: Use this skill when [상황]. Focus on [핵심 판단]. Do not use it for [제외 상황].
---

# [Human-friendly title]

## Goal
[이 스킬의 목표를 한두 문장으로 적기]

## Inputs
- [입력 1]
- [입력 2]
- [입력 3]

## Workflow
1. [상황 파악]
2. [핵심 점검]
3. [필요 시 references 읽기]
4. [결론 정리]

## Guardrails
- [금지 사항]
- [근거 중심 규칙]
- [불확실성 표기 규칙]

## Output
- [결과 형식 1]
- [결과 형식 2]
- [결과 형식 3]

템플릿 2. Next.js + Supabase PR 리뷰 스킬

이건 첫 스킬로 가장 추천할 만하다. 모든 팀이 PR 리뷰를 하고, 품질 편차가 크고, 바로 효과가 보이기 때문이다.

---
name: next-supabase-pr-review
description: Use this skill when reviewing pull requests for a Next.js + Supabase product. Focus on auth flow changes, route handlers, schema migrations, RLS policies, environment variable safety, and test impact. Do not use it for feature ideation, design critique, or copywriting.
---

# Next.js + Supabase PR Review

## Goal
Pull request를 병합하기 전에 기능 영향, 보안 리스크, 데이터 안전성, 테스트 누락 가능성을 일관된 기준으로 검토한다.

## Inputs
- PR 설명
- 변경 파일 목록과 diff
- 테스트/CI 결과
- 관련 이슈 링크

## Workflow
1. PR 범위를 세 문장 이내로 요약한다.
2. 인증 관련 변경을 먼저 확인한다.
3. `supabase/migrations/` 변경이 있으면 마이그레이션 의도와 영향 범위를 읽는다.
4. RLS 또는 권한 관련 변경은 사용자 데이터 노출 가능성을 먼저 본다.
5. 테스트가 없거나 약하면 어떤 테스트가 필요한지 구체적으로 적는다.
6. 결과를 Must fix / Should fix / Nice to have / Questions 형식으로 정리한다.

## Guardrails
- 근거 없는 추측성 리뷰를 하지 않는다.
- 마이그레이션은 한 줄씩 읽고, 되돌리기 가능성을 함께 본다.
- 보안 이슈는 severity와 영향 범위를 함께 적는다.

## Output
- Scope
- Must fix
- Should fix
- Nice to have
- Questions
- Merge recommendation

템플릿 3. Express + MongoDB API 리뷰 스킬

---
name: express-mongo-api-review
description: Use this skill when reviewing backend pull requests in an Express + MongoDB service. Focus on route safety, validation, repository boundaries, query efficiency, error handling, and test coverage. Do not use it for frontend UI review or product ideation.
---

# Express + MongoDB API Review

## Goal
백엔드 PR에서 계약 변경, 검증 누락, 성능 저하, 에러 처리 불일치, 테스트 부족을 빠르게 찾아낸다.

## Inputs
- PR diff
- API contract or route docs
- Test results
- Related issue or incident context

## Workflow
1. 바뀐 엔드포인트와 영향 범위를 먼저 요약한다.
2. 입력 검증이 추가되었는지 확인한다.
3. 라우트-서비스-리포지토리 경계가 지켜졌는지 본다.
4. MongoDB 쿼리가 비효율적이거나 누락된 인덱스를 암시하는지 확인한다.
5. 에러 응답 형식이 공통 규약을 따르는지 본다.
6. 결과를 Critical / Major / Minor / Questions로 정리한다.

## Guardrails
- 구현 취향보다 계약 안정성을 우선한다.
- 성능 우려는 구체적인 쿼리 패턴과 함께 적는다.
- 테스트 누락을 막연히 말하지 말고 필요한 케이스를 제안한다.

## Output
- 변경 범위 요약
- 주요 리스크
- 리뷰 항목
- 추가 테스트 제안

템플릿 4. 배포 전 점검 스킬

릴리스 직전에는 모두가 바쁘다. 이때 사람도 AI도 가장 쉽게 빠지는 함정은 "대충 됐겠지"다. 이 스킬은 그 대충을 줄여 준다.

---
name: predeploy-check
description: Use this skill before deploying a web or API service. Focus on build status, environment variables, migrations, rollback readiness, monitoring, and release risk. Do not use it for feature implementation or exploratory debugging.
---

# Predeploy Check

## Goal
배포 전에 필수 점검 항목을 빠짐없이 확인하고, 출시 가능 여부를 짧고 명확하게 판단한다.

## Inputs
- target branch or commit
- CI results
- migration summary
- environment variable changes
- release notes or PR links

## Workflow
1. 배포 범위를 요약한다.
2. 빌드, 린트, 타입체크, 테스트 상태를 확인한다.
3. 마이그레이션과 환경변수 변경을 우선 점검한다.
4. 롤백 경로가 있는지 확인한다.
5. 모니터링 또는 알림 포인트를 정리한다.
6. 결과를 Ready / Risky but possible / Not ready로 판단한다.

## Guardrails
- 테스트 누락을 모호하게 넘기지 않는다.
- 롤백 불가 변경은 반드시 강조한다.
- 확인하지 못한 항목은 명시적으로 미확인이라고 적는다.

## Output
- 배포 범위
- 통과 항목
- 미확인 항목
- 리스크
- 권고

템플릿 5. Supabase 마이그레이션 점검 스킬

---
name: supabase-migration-review
description: Use this skill when reviewing Supabase schema or policy changes. Focus on migration safety, backward compatibility, RLS impact, seed/dev mismatch, and rollback considerations. Do not use it for generic frontend review.
---

# Supabase Migration Review

## Goal
스키마 변경과 정책 변경이 실제 운영 데이터에 어떤 위험을 만드는지 빠르게 파악한다.

## Inputs
- migration files
- schema diff
- policy changes
- related feature context

## Workflow
1. 변경 목적을 먼저 요약한다.
2. destructive change 여부를 확인한다.
3. 기존 데이터와의 호환성을 본다.
4. RLS 정책 변경이 읽기/쓰기 권한에 미치는 영향을 점검한다.
5. 롤백 가능 여부와 필요한 수동 작업을 정리한다.

## Guardrails
- 단순 SQL 문법 검토에서 끝내지 않는다.
- 멀티테넌시 누수 가능성을 항상 점검한다.
- 운영 영향이 크면 테스트 전략을 함께 요구한다.

## Output
- 변경 요약
- 데이터 리스크
- 권한 리스크
- 롤백 메모
- 병합 전 확인 사항

템플릿 6. 장애 트리아지 스킬

운영 장애에서 제일 무서운 건 로그보다 상상력이 앞서는 것이다. 이 스킬은 그 상상력을 적당히 묶어 둔다.

---
name: incident-triage
description: Use this skill for incident investigation, repeated failures, error spikes, or service degradation. Focus on symptoms, evidence, likely causes, blast radius, and next checks. Do not use it for feature delivery or speculative architecture debate.
---

# Incident Triage

## Goal
장애 상황에서 증상, 근거, 가능한 원인, 다음 조치를 빠르게 정리한다.

## Inputs
- logs
- alerts or metrics
- recent deploy context
- user reports

## Workflow
1. 영향을 받은 서비스와 시간 범위를 정리한다.
2. 핵심 증상을 한두 문장으로 요약한다.
3. 가장 관련 있는 로그와 메트릭을 먼저 모은다.
4. 반복 패턴을 그룹화한다.
5. 근거와 함께 최대 3개의 가능한 원인을 적는다.
6. 다음 확인 항목을 우선순위대로 제시한다.

## Guardrails
- 근거 없이 root cause를 단정하지 않는다.
- 영향 범위를 추정일 경우 추정이라고 적는다.
- 로그 한 줄보다 타임라인과 상관관계를 우선한다.

## Output
- Symptom
- Evidence
- Likely causes
- Blast radius
- Next checks

템플릿 7. PRD 초안 작성 스킬

비개발자 바이브 코더나 PM 성향의 창업자에게 특히 유용하다. 말로 하던 기획을 일정한 문서 형태로 바꾸는 데 좋다.

---
name: saas-prd-draft
description: Use this skill when turning a product idea into a practical PRD for a SaaS feature or MVP. Focus on user problem, scope, non-goals, success metrics, edge cases, and implementation constraints. Do not use it for code review or low-level debugging.
---

# SaaS PRD Draft

## Goal
아이디어를 구현 가능한 제품 요구사항 문서로 정리한다.

## Inputs
- product idea
- target user
- business goal
- constraints

## Workflow
1. 해결하려는 문제를 한 문단으로 정리한다.
2. 핵심 사용자와 주요 시나리오를 정의한다.
3. 반드시 포함할 범위와 제외할 범위를 나눈다.
4. 성공 지표와 실패 조건을 정리한다.
5. 구현 시 주의할 제약을 적는다.
6. 결과를 PM과 개발자가 같이 읽을 수 있는 형태로 정리한다.

## Guardrails
- 기능 목록만 늘어놓지 않는다.
- 비목표를 반드시 적는다.
- 측정 가능한 성공 기준을 최소 하나 포함한다.

## Output
- Problem
- User
- Scope
- Non-goals
- Success metrics
- Constraints
- Open questions

같이 두면 좋은 보조 파일 템플릿

스킬은 SKILL.md만 있어도 시작할 수 있다. 하지만 반복 작업이 많아지면 references/와 assets/를 붙이는 편이 훨씬 낫다. 본문은 짧게 유지하고, 자세한 내용은 필요할 때만 읽게 만드는 방식이 Codex와 잘 맞는다.³

references/review-checklist.md

# Review Checklist

## Security
- 인증 우회 가능성은 없는가?
- 권한 검사가 빠진 엔드포인트는 없는가?
- 민감 정보가 클라이언트로 노출되지 않는가?

## Data
- 마이그레이션이 기존 데이터를 깨뜨리지 않는가?
- 롤백 경로가 있는가?
- 멀티테넌시 누수 가능성은 없는가?

## Tests
- 변경된 동작을 검증하는 테스트가 있는가?
- 실패 케이스가 빠지지 않았는가?
- 테스트 이름이 의도를 설명하는가?

assets/review-output-template.md

## Scope

## Must fix

## Should fix

## Nice to have

## Questions

## Merge recommendation

assets/incident-report-template.md

# Incident Report

## Summary
- Service:
- Time range:
- Severity:
- User impact:

## Symptoms
- Main symptom:
- First detected at:

## Evidence
- Logs:
- Metrics:
- Traces:

## Likely causes
1.
2.
3.

## Next checks
1.
2.
3.

AGENTS.md에서 Skills로 라우팅하는 템플릿

AGENTS.md와 SKILL.md를 따로 써두기만 하면 연결이 약할 때가 있다. 이럴 땐 AGENTS.md 안에 "어떤 상황에서 어떤 스킬을 고려할지"를 짧게 적어 두면 좋다. 이 방식은 사람에게도 친절하고, Codex에게도 방향을 준다.²

## Task routing

### Use `next-supabase-pr-review`
When the task involves:
- pull request review
- auth or Supabase changes
- route handler safety
- migration or RLS review

Expected output:
- scope summary
- must-fix items
- risk notes
- merge recommendation

### Use `predeploy-check`
When the task involves:
- release readiness
- deploy checklist
- migration readiness
- rollback planning

Expected output:
- passed checks
- pending checks
- risks
- recommendation

이 한 덩어리만 있어도 스킬이 공중에 붕 뜨지 않는다. 말하자면 "도구함은 만들었는데, 언제 망치를 쓰는지 라벨도 붙여 둔" 상태가 된다.

빈칸 채우기 가이드

템플릿을 복사한 뒤 어디부터 채워야 할지 막막하면 아래 순서로 가면 된다.

• 첫째, Commands를 정확히 채운다. Codex가 가장 자주 헷갈리는 부분이라 효과가 크다.

• 둘째, 금지 구역을 적는다. 생성 파일, 마이그레이션, 운영 설정처럼 잘못 건드리면 아픈 곳부터 막는다.

• 셋째, 완료 기준을 적는다. 무엇을 통과해야 끝인지 없으면 Codex는 쉽게 "끝난 척"한다.

• 넷째, SKILL.md의 description을 다듬는다. 자동 선택 정확도는 본문보다 여기서 갈린다.²

• 다섯째, 본문은 길게 설명하지 말고 절차와 출력 형식만 남긴다. 자세한 팀 규정은 references/로 보낸다.³

처음엔 10분 안에 완성해도 충분하다. 중요한 건 첫 버전을 만드는 것이다. 완벽한 문서를 기다리다 보면, 결국 아무 문서도 없다.

자주 망하는 문장, 이렇게 고치면 된다

아래는 실제로 많이 보이는 나쁜 문장과, 바로 쓸 수 있는 대체 문장이다.

AGENTS.md에서 자주 망하는 표현

나쁜 예시:

- Write clean code
- Follow best practices
- Be careful with security

좋은 예시:

- Use `pnpm`, never `npm`
- Never modify `supabase/migrations/` history files; add a new migration
- New public endpoints must include request validation and tests

SKILL.md에서 자주 망하는 description

나쁜 예시:

description: Review pull requests.

좋은 예시:

description: Use this skill when reviewing pull requests in a Next.js + Supabase product. Focus on auth flow, migrations, RLS, route safety, and test impact. Do not use it for UI copy or greenfield planning.

출력 형식이 흐릿한 경우

나쁜 예시:

## Output
Leave helpful feedback.

좋은 예시:

## Output
- Scope
- Must fix
- Should fix
- Questions
- Merge recommendation

모호한 문장을 구체적인 행동 문장으로 바꾸는 것만으로도 품질이 꽤 달라진다. AI는 분위기를 읽는 데보다, 명시된 행동을 따르는 데 더 강하다.

템플릿 운영 팁

템플릿은 한 번 복붙하고 끝나는 문서가 아니다. 팀에서 실제로 굴릴 때는 다음 감각이 중요하다.

• Codex가 세 번 이상 같은 실수를 하면, 프롬프트를 길게 쓰기보다 템플릿을 고친다.

• AGENTS.md는 프로젝트 사실과 규칙만 담고, 재사용 가능한 절차는 Skill로 뺀다.

• 전역 AGENTS.md는 가볍게 유지한다. 안 그러면 정작 하위 폴더의 중요한 규칙이 묻힐 수 있다.¹⁴

• 스킬 본문이 길어지면 references/로 쪼갠다. 모든 걸 본문에 넣는 것은 친절해 보이지만 실제로는 비효율적이다.³

• 스킬 이름은 짧고 설명적이어야 한다. 나중에 /skill-name으로 직접 부를 때도 편하다.²

결국 좋은 템플릿은 거창하지 않다. 명령어가 정확하고, 금지 구역이 분명하고, 출력 형식이 선명한 문서면 된다. 그렇게만 해도 Codex는 훨씬 덜 헤매고, 팀은 훨씬 덜 반복 설명하게 된다.

바로 시작하는 추천 조합

처음 한 주 동안은 아래 조합이면 충분하다.

• 루트 AGENTS.md

• 첫 번째 팀 스킬 next-supabase-pr-review 또는 express-mongo-api-review

• 배포 직전용 predeploy-check

• 사고 났을 때를 위한 incident-triage

이 네 개만 있어도 체감이 온다. 평소에는 리뷰와 구현 품질이 올라가고, 배포 직전에는 덜 불안해지고, 장애가 나면 덜 허둥댄다. 템플릿의 가치는 거기 있다. 설명을 줄이고, 시행착오를 줄이고, 결국 일을 앞으로 밀어준다.

참고

¹Custom instructions with AGENTS.md - Codex | OpenAI Developers

²Agent Skills - Codex | OpenAI Developers

³skills/skills/.system/skill-creator/SKILL.md at main · openai/skills · GitHub

⁴AGENTS.md for OpenAI Codex: Complete Setup and Configuration Guide (2026)