自定义指令与扩展

Level 1: 内联指令     — 在 Prompt 中直接写的临时指令
Level 2: codex.yaml   — 项目级持久化指令（之前学过）
Level 3: 指令模板      — 可命名、可复用、可共享的指令包

请用以下规范生成代码：
- 所有函数必须有 try-catch
- API 返回 {code, data, message} 格式
- 变量命名用 camelCase

现在请帮我写一个...

instructions: |
  你是全栈工程师...
  项目使用 Next.js 14...
  所有 API 返回 {code, data, message}...

项目根目录/
├── codex.yaml
└── .codex/
    └── instructions/
        ├── new-api-route.md        # 指令模板 1
        ├── code-review.md          # 指令模板 2
        ├── generate-test.md        # 指令模板 3
        └── refactor-component.md   # 指令模板 4

<!-- .codex/instructions/new-api-route.md -->

# 指令：创建新 API 路由

## 描述
按照项目规范创建一个完整的 RESTful API 路由。

## 参数
- ROUTE_PATH：路由路径，如 /api/users
- RESOURCE_NAME：资源名称，如 User
- FIELDS：需要的字段列表

## 执行规范

请你完成以下步骤：

1. 在 src/types/ 中创建 ${RESOURCE_NAME} 类型定义
2. 在 src/app/api/${ROUTE_PATH}/ 创建路由文件，实现：
   - GET    /api/${ROUTE_PATH}     — 列表查询（分页）
   - GET    /api/${ROUTE_PATH}/[id] — 单条查询
   - POST   /api/${ROUTE_PATH}     — 创建
   - PATCH  /api/${ROUTE_PATH}/[id] — 更新
   - DELETE /api/${ROUTE_PATH}/[id] — 删除
3. 在 src/services/ 中创建业务逻辑层
4. 使用 Prisma 做数据库操作
5. 所有接口返回 { code, data, message } 格式
6. 包含输入验证（Zod schema）
7. 处理常见错误：404、409、500

## 需要的字段
${FIELDS}

/instruction new-api-route ROUTE_PATH=users RESOURCE_NAME=User FIELDS="name, email, role"

<!-- .codex/instructions/code-review.md -->

# 指令：全面代码审查

## 描述
对指定范围进行深度代码审查，输出结构化的审查报告。

## 参数
- SCOPE：审查范围（文件路径 或 "staged" 或 "branch"）

## 审查清单

请按以下维度逐项审查 ${SCOPE} 中的代码：

### 1. 正确性
- [ ] 逻辑是否有错误
- [ ] 边界条件是否处理
- [ ] 空值/undefined 是否安全处理
- [ ] 异步操作是否正确 await

### 2. 安全性
- [ ] 是否有 SQL/NoSQL 注入风险
- [ ] 是否有 XSS 风险
- [ ] 敏感信息是否硬编码
- [ ] 输入验证是否充分

### 3. 性能
- [ ] 是否有 N+1 查询
- [ ] 不必要的重渲染
- [ ] 大循环中的重复计算
- [ ] 缺失的数据库索引

### 4. 可维护性
- [ ] 函数是否过长（>80 行）
- [ ] 命名是否清晰
- [ ] 是否有重复代码
- [ ] 注释是否充分

### 5. 测试
- [ ] 核心逻辑是否有测试覆盖
- [ ] 边界情况是否有测试

### 输出格式
| 维度 | 严重程度 | 文件:行号 | 问题描述 | 修复建议 |
|------|----------|-----------|----------|----------|

<!-- .codex/instructions/ship-feature.md -->

# 指令：发布新功能

## 描述
执行功能发布前的所有检查和准备工作。

## 参数
- FEATURE_BRANCH：功能分支名称

## 执行步骤

请严格按照以下顺序执行：

1. **代码审查**
   /review 审查 ${FEATURE_BRANCH} 分支的所有变更

2. **运行测试**
   运行 pnpm test，如果失败则修复

3. **类型检查**
   运行 pnpm typecheck，确保无类型错误

4. **Lint 检查**
   运行 pnpm lint，自动修复可修复的问题

5. **生成 CHANGELOG**
   根据 ${FEATURE_BRANCH} 的 commit 历史，更新 CHANGELOG.md

6. **生成 PR 描述**
   生成包含以下内容的 PR 描述：
   - 变更概述
   - 测试说明
   - 截图（如有 UI 变更）
   - 迁移步骤（如有）

7. **创建 PR**
   使用 gh CLI 创建 Pull Request

所有步骤通过后，报告"功能 ${FEATURE_BRANCH} 已准备好发布"。

/instruction ship-feature FEATURE_BRANCH=feat/user-management

# 将指令纳入版本控制
git add .codex/instructions/
git commit -m "chore: add team codex instruction templates"
git push

# 团队成员 pull 后即可使用相同的指令

<!-- 指令编写规范建议 -->

1. 文件名使用 kebab-case，清晰描述功能
2. 必须包含「描述」和「参数」部分
3. 复杂指令列出执行步骤编号
4. 每条指令必须可独立执行，不依赖上下文
5. 在指令末尾注明作者和更新日期
6. 指令变更通过 PR review，如同代码变更

# 示例项目结构
codex-instructions/
├── README.md
├── web/
│   ├── new-nextjs-page.md
│   ├── add-tailwind-component.md
│   └── fix-react-hydration-error.md
├── backend/
│   ├── new-api-route.md
│   ├── optimise-db-query.md
│   └── setup-docker.md
└── devops/
    ├── setup-ci.md
    └── deploy-to-vercel.md

使用指令 → 发现问题 → 改进指令 → 提交更新 → 团队同步

<!-- .codex/instructions/CHANGELOG.md -->

## 2025-07-16
- `code-review`: 增加"安全性"检查维度
- `new-api-route`: 添加输入验证步骤
- `ship-feature`: 修复 step 5 在 monorepo 中的路径问题