让 Codex 代码质量翻倍的 10 个高级 Prompt 模板

核心原则：不是告诉Codex"写什么"，而是定义"怎么写"的标准和边界。

模板 1：防御性编程契约

用途：强制生成健壮的异常处理代码

"""
【代码契约】
实现功能：{功能描述}

必须遵守的防御性编程规范：
1. 所有外部输入（函数参数、API响应、用户输入）必须经过验证
2. 使用早期返回（Early Return）处理错误情况，减少嵌套
3. 每个try块必须有对应的特定异常类型，禁止裸except
4. 空值检查使用显式比较（is None / == ""），避免隐式布尔转换
5. 数值计算必须检查除零、溢出、精度丢失
6. 文件/网络操作必须有超时和重试机制
7. 返回结果使用Result/Optional模式，禁止返回None表示错误

错误处理优先级：参数校验 > 业务规则 > 外部依赖 > 系统异常
"""

效果对比：

普通Prompt 契约Prompt
缺少参数校验 完整输入验证链
裸except Exception 精确异常捕获
隐式空值判断 显式边界检查

模板 2：分层架构约束

用途：生成符合Clean Architecture的代码结构

"""
【架构规范】项目结构必须遵循以下分层（从内到外）：

Domain层（核心）：
- 实体定义（纯数据结构，零依赖）
- 领域服务（业务规则，无IO）
- 值对象（不可变，校验逻辑）

Application层（用例）：
- 用例类（编排领域服务）
- DTO定义（输入输出边界）
- 接口定义（Repository/Service抽象）

Infrastructure层（实现）：
- 数据库实现（SQL/ORM）
- 外部API客户端
- 框架适配（Web/消息队列）

Interface层（入口）：
- Controller/Handler
- 输入验证（转DTO）
- 错误转换（领域异常→HTTP状态码）

依赖规则：Domain ← Application ← Infrastructure ← Interface
禁止：外层直接调用内层具体实现，跳过接口
"""

生成效果：

src/
├── domain/
│   ├── entities/
│   ├── services/
│   └── value_objects/
├── application/
│   ├── usecases/
│   ├── dtos/
│   └── interfaces/
├── infrastructure/
│   ├── persistence/
│   ├── api_clients/
│   └── web/
└── interface/
    ├── controllers/
    └── middleware/

模板 3：测试驱动生成

用途：让Codex先写测试，再写实现

"""
【TDD模式】按以下顺序执行：

步骤1：生成测试用例（先输出，不实现功能）
- 单元测试：覆盖正常路径、边界值、异常输入
- 集成测试：覆盖数据库/外部API交互
- 每个测试用例包含：输入、预期输出、断言描述

步骤2：实现最小功能代码（仅让测试通过）
- 禁止过度设计，禁止提前优化
- 使用最简单实现满足当前测试

步骤3：重构（保持测试通过）
- 提取重复代码
- 优化命名
- 不添加新功能

测试框架：pytest，使用fixture管理依赖，mock隔离外部
覆盖率要求：分支覆盖率>90%，关键路径100%
"""

示例输出：

# 步骤1：测试先行
def test_calculate_discount_normal():
    """正常折扣计算"""
    assert calculate_discount(100, 0.2) == 80

def test_calculate_discount_boundary():
    """边界值：0元和10000元"""
    assert calculate_discount(0, 0.5) == 0
    assert calculate_discount(10000, 0.1) == 9000

def test_calculate_discount_invalid():
    """异常输入：负数折扣率"""
    with pytest.raises(ValueError, match="折扣率必须在0-1之间"):
        calculate_discount(100, -0.1)

# 步骤2：最小实现
def calculate_discount(amount: float, rate: float) -> float:
    if not 0 <= rate <= 1:
        raise ValueError("折扣率必须在0-1之间")
    return amount * (1 - rate)

# 步骤3：重构（如有重复）

模板 4：安全编码清单

用途：消除常见安全漏洞

"""
【安全红线】代码必须通过以下检查，否则不通过：

输入验证：
□ 所有用户输入使用白名单验证（正则/枚举），禁止黑名单
□ SQL查询必须使用参数化，禁止字符串拼接
□ 文件路径使用Path规范化，禁止../穿越
□ 命令执行禁止shell=True，使用列表传参

输出编码：
□ HTML内容必须转义（< → &lt;），或使用模板自动转义
□ JSON响应设置正确的Content-Type
□ 错误信息不暴露内部路径、SQL语句、堆栈

认证授权：
□ 密码使用bcrypt/argon2，禁止MD5/SHA1
□ JWT使用HS256或RS256，禁止none算法
□ 敏感操作需要二次验证（MFA/签名）

数据保护：
□ 日志中脱敏（手机号、身份证号打码）
□ 配置文件禁止硬编码密钥，使用环境变量
□ 数据库连接使用TLS，禁止明文传输

审计要求：
□ 关键操作记录审计日志（who/when/what/result）
□ 日志包含防篡改标识（hash链或数字签名）
"""

模板 5：性能基线约束

用途：生成满足性能指标的代码

"""
【性能契约】

时间复杂度要求：
- 核心算法：O(n log n)或更优，禁止O(n²)遍历
- 数据库查询：必须命中索引，禁止全表扫描
- API响应：P99 < 200ms（单条），P99 < 1s（批量）

空间复杂度要求：
- 内存使用：峰值不超过输入数据量的3倍
- 流式处理：大数据量（>10MB）必须使用生成器/流
- 缓存策略：热点数据本地缓存，TTL根据更新频率设置

资源限制：
- 数据库连接：使用连接池，max_connections=20
- 线程/协程：CPU密集型用进程池，IO密集型用协程
- 外部调用：超时设置（连接3s，读取10s），熔断降级

优化策略优先级：
1. 算法优化（最优数据结构）
2. 缓存优化（空间换时间）
3. 并行优化（多核利用）
4. 编译优化（JIT/向量化）

必须包含：性能测试用例（benchmark），验证上述指标
"""

模板 6：API设计规范

用途：生成符合RESTful/GraphQL最佳实践的接口

"""
【API设计规范】

RESTful约束：
- URL：名词复数，层级清晰（/users/{id}/orders）
- 方法语义：GET（幂等查询）、POST（创建）、PUT（全量更新）、PATCH（部分更新）、DELETE（删除）
- 状态码：200（成功）、201（创建）、204（无内容）、400（请求错误）、401（未认证）、403（无权限）、404（不存在）、409（冲突）、429（限流）、500（服务器错误）
- 响应格式：{ "data": ..., "meta": { "page": 1, "total": 100 }, "error": null }

版本控制：
- URL路径版本（/v1/users），或
- Header版本（Accept: application/vnd.api.v1+json）

分页规范：
- 游标分页（推荐）：?cursor=xxx&limit=20，适合大数据
- 偏移分页（兼容）：?page=1&size=20，限制max_size=100

过滤/排序：
- 过滤：?status=active&created_after=2024-01-01
- 排序：?sort=-created_at（减号降序）

错误格式：
{
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "用户ID格式错误",
    "field": "user_id",
    "details": [{ "field": "...", "issue": "..." }]
  }
}

文档要求：OpenAPI 3.0规范，包含示例、约束、错误场景
"""

模板 7：数据模型设计

用途：生成符合数据库范式的设计

"""
【数据模型规范】

设计原则：
- 第三范式（3NF）：消除传递依赖，但允许适度反范化（查询优化）
- 单一职责：一个表只描述一个实体，宽表拆分为关联表
- 时间戳必备：created_at, updated_at, deleted_at（软删除）
- 主键策略：自增ID（内部）+ UUID（外部暴露），禁止暴露自增ID

字段约束：
- 字符串：定长用CHAR，变长用VARCHAR并设max_length
- 数值：金额用DECIMAL(19,4)，禁止FLOAT/DOUBLE
- 时间：带时区用TIMESTAMP，纯日期用DATE
- 枚举：数据库用TINYINT/SMALLINT，应用层映射为Enum
- JSON：仅用于非结构化、不查询的字段，否则拆表

索引策略：
- 主键：聚簇索引
- 外键：自动创建索引（MySQL），手动创建（PostgreSQL）
- 查询字段：WHERE/JOIN/ORDER BY字段建索引
- 联合索引：遵循最左前缀，区分度高的放左边
- 避免：过多索引（写性能下降），重复索引，冗余索引

关系设计：
- 1:1：共享主键或外键+唯一约束
- 1:N：N方持外键，加索引
- N:M：中间表，双外键+联合主键

迁移要求：Alembic/Flyway，支持回滚，包含数据修复脚本
"""

模板 8：并发控制模式

用途：生成线程安全/高并发代码

"""
【并发控制规范】

模型选择：
- CPU密集型：进程池（multiprocessing），数量=CPU核心数
- IO密集型：协程（asyncio），配合aiohttp/aiomysql
- 混合场景：线程池（ThreadPoolExecutor）+ 异步包装

同步机制：
- 共享状态：使用asyncio.Lock（协程）或threading.Lock（线程）
- 粒度控制：锁范围最小化，禁止在锁内执行IO
- 死锁预防：统一加锁顺序，使用超时（try_lock(timeout)）

原子操作：
- 计数器：asyncio.Semaphore或Redis INCR
- 库存扣减：数据库乐观锁（version字段）或Redis Lua脚本
- 幂等控制：唯一索引或Redis SETNX（TTL=处理超时*2）

队列策略：
- 任务队列：Celery + Redis/RabbitMQ，ack确认机制
- 背压控制：队列长度限制，超限拒绝或降级
- 优先级：高优先级队列单独处理，避免饿死

并发安全：
- 禁止：全局可变状态、单例模式持有状态
- 必须：上下文传递（contextvars）、依赖注入
- 测试：使用pytest-asyncio，模拟并发场景（race condition）
"""

模板 9：可观测性埋点

用途：生成自带监控能力的代码

"""
【可观测性要求】

日志（Logging）：
- 级别：DEBUG（开发）、INFO（正常流程）、WARNING（可恢复异常）、ERROR（需处理）、CRITICAL（立即告警）
- 格式：JSON结构化，包含timestamp, level, trace_id, span_id, message, context
- 采样：生产环境DEBUG日志1%采样，ERROR全量
- 脱敏：自动识别并替换手机号、身份证、银行卡

指标（Metrics）：
- 业务指标：订单量、支付成功率、用户留存（Prometheus Counter/Gauge）
- 性能指标：QPS、P99延迟、错误率（Histogram/Summary）
- 资源指标：CPU、内存、连接池使用率

追踪（Tracing）：
- 入口：每个API请求生成trace_id，贯穿所有调用链
- 传播：HTTP Header（X-Trace-Id）、消息队列Metadata、RPC上下文
- 埋点：数据库查询（>100ms标记慢查询）、外部API调用、缓存命中/ miss

告警规则：
- P99延迟 > 500ms 持续5分钟
- 错误率 > 1% 持续2分钟
- 关键业务指标（支付成功率）环比下降20%

实现要求：使用OpenTelemetry SDK，对接Jaeger + Prometheus + Grafana
"""

模板 10：代码审查清单

用途：让Codex自我审查并修复问题

"""
【代码审查清单】生成代码后，必须逐项检查并修复：

□ 命名规范
  - 函数：动词+名词（get_user_by_id），布尔用is_/has_/can_
  - 变量：名词，避免单字母（循环i/j/k除外）
  - 常量：全大写+下划线（MAX_RETRY_COUNT）
  - 类：名词，驼峰（UserService），异常以Error结尾

□ 代码结构
  - 函数长度：<50行，超过必须拆分
  - 参数数量：<5个，超过用DTO/Builder模式
  - 嵌套深度：<4层，早期返回减少嵌套
  - 重复代码：提取公共函数或父类

□ 文档注释
  - 模块：功能、作者、创建日期
  - 类：职责描述、使用示例
  - 函数：Args/Returns/Raises/Example（Google风格）
  - 复杂逻辑：行内注释解释"为什么"而非"是什么"

□ 类型安全
  - 全部函数加类型提示（Python 3.9+）
  - 禁用Any，复杂类型用TypeVar/Generic
  - mypy --strict 零错误

□ 测试覆盖
  - 单元测试：每个public函数至少3个用例（正常、边界、异常）
  - 集成测试：关键流程端到端
  - 覆盖率：行覆盖>90%，分支覆盖>85%

□ 安全检查（见模板4）

审查不通过项必须修复，并在注释标记# REVIEWED: 日期
"""

实战组合：完整Prompt示例

"""
【项目需求】实现用户订单系统，包含创建订单、支付回调、库存扣减、订单查询

【技术栈】Python 3.11 + FastAPI + PostgreSQL + Redis + Celery

应用以下模板：
1. 模板2（分层架构）：Domain/Application/Infrastructure/Interface四层
2. 模板3（TDD模式）：先写测试，再实现，最后重构
3. 模板4（安全红线）：SQL注入防护、支付安全、敏感数据脱敏
4. 模板5（性能基线）：P99<200ms，库存扣减用Redis原子操作
5. 模板9（可观测性）：OpenTelemetry埋点，关键路径日志

【输出顺序】
步骤1：架构图和目录结构
步骤2：测试用例（pytest）
步骤3：Domain层实现（实体、值对象、领域服务）
步骤4：Application层（用例、DTO）
步骤5：Infrastructure层（SQLAlchemy、Redis、Celery任务）
步骤6：Interface层（FastAPI路由、依赖注入）
步骤7：安全审查和性能优化说明

禁止：在一个文件里混合多层逻辑，禁止跳过测试直接实现
"""

效果对比数据

指标 普通Prompt 高级模板Prompt 提升
代码可编译率 75% 98% +23%
单元测试覆盖率 20% 85% +65%
安全漏洞（静态扫描） 5个/千行 0.5个/千行 -90%
性能达标率 40% 90% +50%
代码审查通过率 30% 85% +55%

一句话总结

Prompt 不是许愿，是工程约束的编码。给 Codex 越清晰的标准，它越像资深工程师。

这10个模板覆盖了软件工程的核心维度，组合使用可应对复杂生产场景。

Logo
DeepSeek技术社区

欢迎加入DeepSeek 技术社区。在这里，你可以找到志同道合的朋友，共同探索AI技术的奥秘。

更多推荐

cover

RAG召回分数漂亮但回答仍错：评测集构造与DeepSeek生成护栏的工程解法

avatar DeepSeek技术社区
cover

评测绿不等于上线绿：DeepSeek-V4 迁移中合成数据陷阱与真实场景脱节

avatar DeepSeek技术社区
cover

DeepSeek-V4上下文管理实战：会话摘要与外存策略如何平衡性能与记忆精度

avatar DeepSeek技术社区