自定义 Prompts 完全指南
本指南深入探讨 Codex 提供的两种核心自定义方式:自定义斜杠命令 和 AGENTS.md 配置文件,旨在通过可复用的模板和持久化的项目上下文,将您的工作效率提升至全新水平。
I. 自定义斜杠命令 (Custom Slash Commands)
简介与原理
自定义斜杠命令是将常用提示词保存为 Markdown 文件模板的强大功能。它允许你通过简单的 /命令名
快速调用复杂、结构化的 Prompts,极大地简化了重复性任务。
- 存储位置:
~/.codex/prompts/
- 文件格式:
.md
结尾的 Markdown 文件。 - 命令名称: 文件名(去除
.md
)。例如review-pr.md
→/review-pr
。 - 参数支持:
$1
-$9
(位置参数),$ARGUMENTS
(所有参数)。
实用案例库
以下是一些高效的命令模板,你可以直接创建对应文件并使用。
代码审查 (review-code.md)
请对以下文件进行详细的代码审查:$1
审查维度:
1. **代码质量**:命名、结构、可读性
2. **潜在bug**:边界条件、错误处理、并发问题
3. **性能**:算法复杂度、不必要的计算、内存泄漏
4. **安全性**:输入验证、SQL注入、XSS等
5. **可维护性**:注释、文档、测试覆盖率
输出格式:
- 🟢 优点(2-3条)
- 🟡 改进建议(3-5条,标注严重程度 Critical/Major/Minor)
- 🔴 必须修复的问题(如有)
请给出具体的代码片段建议。
生成单元测试 (gen-tests.md)
为以下文件/函数生成完整的单元测试:$1
测试要求:
- 测试框架:自动检测项目使用的框架(Jest/Vitest/pytest等)
- 覆盖场景:✅ 正常情况, ❌ 边界条件, 💥 异常情况
- Mock 外部依赖(API 调用、数据库、文件系统)
- 测试数据:使用真实但匿名化的样本数据
- 测试名称:描述性强(用 "should..." 或 "when... then..." 格式)
解释复杂代码 (explain.md)
请详细解释以下代码的工作原理:$ARGUMENTS
解释要求:
1. **高层概述**(1-2句话):这段代码做什么?
2. **逐行分析**:关键变量、每个步骤的作用、控制流程
3. **使用的技术/模式**:设计模式、算法、数据结构
4. **潜在陷阱**:边界情况、性能考虑
5. **改进建议**(如果有明显问题)
请用通俗易懂的语言解释,适合给新手看。
重构建议 (refactor.md)
分析以下代码并提供重构建议:$1
分析维度:
1. **代码异味(Code Smells)**:过长函数/类、重复代码、复杂条件等
2. **设计模式应用**:SRP, OCP等
3. **现代语法**:是否可以使用新版本语言特性
输出格式:
### 当前问题
- [列出 3-5 个主要问题]
### 重构方案
#### 方案 1: [名称]
- 优点/缺点
- 代码示例...
生成 API 文档 (api-docs.md)
为以下 API 端点/函数生成 OpenAPI 3.0 风格的完整文档:$1
包含内容:
1. **端点信息**:HTTP 方法、路径、功能描述
2. **请求参数/请求体**:Schema、示例
3. **响应**:成功/错误响应示例
4. **使用示例**:cURL, JavaScript/Python 客户端代码
Bug 诊断助手 (debug.md)
帮我诊断以下问题:$ARGUMENTS
诊断流程:
1. **问题复现**:复现步骤是什么?
2. **日志分析**:检查相关日志和错误堆栈
3. **可能原因**(列出 3-5 个假设,按概率排序)
4. **调试建议**:添加哪些日志/断点?
5. **临时解决方案**(workaround)
性能优化分析 (optimize.md)
分析以下代码的性能并提供优化建议:$1
分析维度:
1. **算法复杂度**:时间/空间复杂度分析
2. **常见性能问题**:不必要的循环、重复计算、N+1查询等
3. **语言/框架特定优化**
4. **Benchmark**:生成性能测试代码对比优化前后
数据库 Schema 设计 (db-schema.md)
为以下需求设计数据库 Schema:$ARGUMENTS
设计要求:
1. **表结构**:字段、类型、约束、主外键、索引
2. **关系**:使用 Mermaid 绘制 ER 图
3. **最佳实践**:范式、软删除、时间戳字段
4. **生成迁移脚本** 和 **示例数据**
Git Commit 消息生成 (commit-msg.md)
根据当前的 Git 变更(`git diff --staged`)生成符合 Conventional Commits 规范的提交消息。
分析变更类型(`feat`, `fix`, `docs`, `refactor`等),并生成 3 个候选消息,按推荐度排序。
环境配置检查 (check-env.md)
检查项目的环境配置是否完整且正确:$1
检查内容:
1. **依赖项**:版本冲突、安全漏洞
2. **环境变量**:是否缺少必需变量
3. **配置文件**:`tsconfig.json`等是否合理
4. **开发工具**:Linter/Formatter/Git hooks配置
高级技巧
- 组合参数: 使用引号传递包含空格的参数,如
/explain "React useEffect vs useLayoutEffect"
。 - 嵌套命令: 在 `AGENTS.md` 中为斜杠命令添加额外的项目特定指令。
- 命令别名: 在
prompts
目录中创建符号链接,如ln -s review-code.md rc.md
,即可使用/rc
。 - 版本控制: 将你的
~/.codex/prompts
目录初始化为 Git 仓库,方便团队共享和版本管理。
II. AGENTS.md 配置文件
简介与区别
AGENTS.md
是一个提供持久化上下文的配置文件。与一次性的斜杠命令不同,它会在每次会话中自动加载,为 Codex 提供项目级别的编码规范、技术栈信息和领域知识,使其响应更贴合项目实际。
加载顺序与作用域
Codex 会按顺序合并多个 AGENTS.md
文件,形成最终上下文,越后面的配置优先级越高:
斜杠命令 vs AGENTS.md
特性 | 斜杠命令 | AGENTS.md |
---|---|---|
触发方式 | 手动调用 /command | 自动加载 |
适用场景 | 一次性、重复性任务 | 持久化规范、项目上下文 |
作用域 | 全局 (~/.codex/prompts/ ) | 全局 / 项目 / 目录 |
配置模板精选
将以下模板内容保存到项目根目录的 `AGENTS.md` 文件中,为 Codex 提供强大的项目上下文。
Python/Django 项目模板
# Python/Django 项目指南
## 技术栈
- Python 3.11+, Django 4.2, DRF, PostgreSQL, Celery, pytest
## 编码规范
- **格式化**: Black (行长 88), isort
- **Linting**: Ruff + mypy
...
React/TypeScript 项目模板
# React/TypeScript 前端项目规范
## 技术栈
- React 18+ (Hooks only), TypeScript 5+ (strict mode), Vite, TailwindCSS, React Query
## TypeScript 规范
- **严格模式**: `strict: true`
- **类型定义**: Props用 `interface`,其他用 `type`。避免 `any`。
...
Rust 系统编程项目模板
# Rust 系统编程项目规范
## 项目信息
- Edition: 2021, MSRV: 1.70, Linter: Clippy (pedantic)
## 错误处理
- 库代码返回 `Result`,应用代码用 `anyhow::Result`。
- 生产代码中禁止 `unwrap()`/`expect()`。
...
DevOps/Infrastructure 项目模板
# DevOps & Infrastructure 项目规范
## 技术栈
- Terraform, Kubernetes + Helm, Ansible, GitHub Actions, Prometheus
## Terraform 规范
- **模块化**: 每个资源类型一个模块。
- **State 管理**: 远程 backend (S3 + DynamoDB lock),环境隔离。
...
数据科学/机器学习项目模板
# 数据科学与机器学习项目规范
## 技术栈
- Python 3.10+, PyTorch, Pandas/Polars, Scikit-learn, MLflow, DVC
## 项目结构
- `data/`, `notebooks/`, `src/`, `models/`
## 数据处理规范
- **版本控制**: 用 DVC 跟踪大文件。
- **可复现性**: 数据管道必须可复现。
...
代码审查 Checklist 模板
# 代码审查 Checklist
当你帮我审查代码时,请检查以下方面:
1. **功能正确性** ✅: 实现了需求、处理了边界条件和错误。
2. **代码质量** 📐: 命名清晰、职责单一、无重复代码。
...
Bug 修复指南模板
# Bug 修复指南
当修复 bug 时,请遵循以下流程:
1. **理解问题** 🔍: 阅读日志、确认复现步骤。
2. **定位根因** 🎯: 用二分法、添加日志、`git blame`。
3. **修复方案** 🔧: 优先最小改动,添加测试防止回归。
...
性能优化指南模板
# 性能优化指南
优化前必须先 **测量**,不要凭感觉优化!
## 1. 性能分析工具 📊
- Web: Chrome DevTools, Node.js: `clinic.js`, DB: `EXPLAIN ANALYZE`
## 2. 常见性能问题
- N+1 查询、阻塞 I/O、未用索引、大 Bundle、重复渲染。
...
III. 实战场景扩展
以下是更多结合了 Codex 功能的真实世界应用案例。
重构老代码
codex -m gpt-5-codex "把 src/legacy/ 目录下的 ES5 代码重构成 TypeScript"
安全审计
codex --profile safe "扫描整个项目,生成安全漏洞报告(Markdown 格式)"
CI/CD 集成
在 GitHub Actions 中,使用 Codex 对 Pull Request 的代码变更进行自动审查,并将结果评论到 PR 中。
数据库迁移生成
codex "根据 models.py 的变更,生成 Django 数据库迁移并检查是否有数据丢失风险"
跨语言代码迁移
codex -m o3 --profile complex "把 legacy/calculator.py (Python 2) 迁移到 Rust,保持完全相同的API"
Dockerfile 优化
codex "优化这个 Dockerfile,减小镜像体积,提升构建速度,增强安全性"
Git 冲突解决
codex "帮我解决 feature/new-ui 分支与 main 的合并冲突,保留两边的功能"
IV. 最佳实践
分层配置策略
个人通用配置放 `~/.codex/`,团队共享规范放项目根目录的 `AGENTS.md`。
Profile 命名规范
使用 `dev`, `prod`, `test`, `ci`, `review` 等有意义的名称来组织你的 Profile。
Sandbox 安全等级
任务类型 | 推荐配置 |
---|---|
阅读代码 | read-only + untrusted |
编写功能 | workspace-write + on-failure |
CI/CD | read-only 或 workspace-write + never |
团队协作
将项目根目录下的 AGENTS.md
和 .codex/config.toml
提交到版本库,统一团队的开发规范和工具配置。
V. 快捷命令速查表
# 基本使用
codex "任务描述" # 带初始提示启动
codex exec "任务" # 非交互模式
codex resume --last # 恢复最后一个会话
# 配置与模型
codex -m o3 "任务" # 指定模型 (o3)
codex --profile review "任务" # 使用 'review' 配置
# Sandbox 与审批
codex --sandbox read-only "任务" # 只读模式
codex -a never "任务" # 全自动(危险!)
# MCP 管理
codex mcp list # 列出所有服务器
codex mcp login NAME # OAuth 登录
# 图片输入
codex -i screenshot.png "解释这个错误"
# 调试与日志
RUST_LOG=debug codex # 详细日志
tail -f ~/.codex/log/codex-tui.log