AI辅助开发的任务、上下文与验收

定义任务与必要上下文

需能阅读 Python 函数和 JSON 用例。本页从任务范围、上下文选择讲到验收；离线任务包用 format_label 的空白输入修复贯穿规则、候选补丁和审查表，不需要模型账号或 SDK。 示例未在本轮执行。

Codex 任务契约

Codex任务契约写明目标、允许修改的目录和验收依据。本课程只讨论离线文件，不调用模型；明确范围能帮助人工判断输出是否解决原问题，不能保证一次生成正确。

Codex 上下文选择

Codex上下文应覆盖相关接口、调用方与边界测试，按问题定位再读取。把历史材料与当前约束区分，摘录必要内容时保留出处，避免把压缩摘要当作代码事实。

Codex AGENTS.md

Codex的AGENTS.md用于稳定项目规则。官方说明存在用户级与目录层次指令；课程示例给出仓库规则文件，但具体发现机制、覆盖顺序和大小限制应依当前官方页及本次客户端环境核对。

依据与适用范围

• 本课官方依据，资料核对日2026-10-17。

以上依据用于解释本文列明的规则；示例未执行，不代表产品全部能力或跨平台验证。历史资料的版本、账号与界面位置需按目标环境确认。

• OpenAI Docs：执行环境与安全
• OpenAI Docs：技能

本地能力核对：本会话工具清单确实提供本地文件与终端工具，权限由会话沙箱和用户约束控制；这不是所有Codex客户端都具备相同工具的保证。未调用模型、SDK或API。

控制权限、技能与验证证据

Codex 权限边界

Codex权限边界由执行环境控制。写作任务明确禁止运行示例或外发时，生成命令文本不等于获准执行；审批与沙箱是执行约束，不能因提示词要求就假定拥有系统权限。

Codex 技能文件

Codex技能以SKILL.md表达重复工作流。描述应限定触发条件与输入，正文说明步骤和验收；安装了技能不代表外部账号已连接，引用的脚本仍需审阅权限和副作用。

Codex 验证证据

Codex验证证据应记录实际命令、退出状态和适用范围。仅源码审阅就写源码审阅；静态编译不代表服务运行。模型名称、费率和账号额度会变化，本课不复制旧价格或承诺可用模型。

识别错误假设与范围漂移

Codex 幻觉接口

Codex幻觉接口常表现为不存在的方法、错误版本参数或伪造引用。先查锁定依赖和官方定义，再做纯语法或类型核对；能编译仍不足以确认业务语义，必须对照需求逐项审阅。

Codex 范围漂移

Codex范围漂移是改动扩展到任务之外。把每个变更映射到验收条件，无法对应的整理先移出补丁；长期任务用文件保存决策、当前状态与下一步，避免用重复读取全部仓库维持进度。

Codex 成本判断

Codex成本判断先区分订阅额度、API计量与实际任务记录。旧文的模型分工和价格仅代表历史上下文；本课只建议减少无关上下文、重复输出和返工，不以字符数直接推算所有模型的Token账单。

AI 辅助开发实践

本文整理需求分析、编码、测试与审查中适合使用 AI 的任务，以及开发者需要提供和验收的内容。

适用场景

效果较好的场景

需求分析

在开发前拆解需求，补充正常流程、异常流程、边界条件和潜在风险，形成待确认问题清单。

新功能与新服务开发

对于上下文清晰、历史依赖较少的项目，AI 可以快速完成：

• 项目或模块基础结构搭建
• Handler、Service、Repository 等分层代码
• 数据结构、接口和错误处理框架
• 重复性较高的增删改查代码

独立逻辑与算法

对于输入输出明确、依赖较少的逻辑，AI 通常能够较快产出可验证的实现，例如：

• 牌型与规则计算
• 排序、过滤和数据统计
• 数据格式转换
• 独立工具函数

测试

AI 可以根据实现补充：

• 单元测试与表驱动测试
• 正常、异常和边界测试场景
• Mock 数据与测试桩
• 未覆盖分支和回归风险提示

Code Review

AI 适合辅助发现常见问题，包括：

• 明显的逻辑错误和遗漏分支
• 空指针、越界和错误未处理
• 并发安全与资源释放问题
• 简单的性能和代码规范问题

效果有限的场景

以下场景不宜直接依赖 AI 完成：

• 维护时间长、代码量大、业务约定复杂的历史项目
• 涉及资金、账号、权限、数据一致性等高风险逻辑
• 缺少需求文档，只能依赖口头约定或隐性知识的需求
• 修改范围跨越多个服务，但缺少完整调用链和协议说明的任务
• 线上紧急问题中未经验证的自动修改

实际收益

降低重复劳动

AI 对模板化代码、数据结构转换、测试用例和文档整理的处理效率较高，可以减少重复编码时间。

提前发现遗漏

在需求评审和编码前引入 AI，可以从输入校验、异常处理、并发、兼容性和可测试性等角度补充检查项。

加快方案探索

开发人员可以让 AI 提供多个实现思路并比较复杂度、可维护性和风险，再结合项目实际情况选择方案。

提升基础代码质量

当项目规范和上下文明确时，AI 能够较稳定地遵循分层、命名、错误处理和测试要求，减少基础规范问题。

主要问题与风险

历史上下文理解不足

长期维护的项目通常包含大量隐性规则、兼容逻辑和跨服务依赖。AI 无法仅通过局部代码准确理解全部背景，容易出现：

• 业务含义理解偏差
• 修改范围过大或过小
• 忽略历史数据和旧版本兼容
• 只修复表面问题，破坏原有调用链

因此，历史项目应先提供模块说明、调用链、关键约束和相关代码范围，再让 AI 分阶段处理。

上下文与 Token 限制

大型需求会持续消耗上下文。上下文过长或多次切换任务后，可能出现信息遗漏、回答不连续和实现质量下降。

建议将大任务拆分为“分析、方案、实现、测试、审查”等阶段，每个阶段明确输入、输出和完成标准，并将关键结论沉淀到文档中。

需求质量直接影响结果

“和上次一样”“按原逻辑处理”等描述依赖团队成员的长期记忆，AI 无法准确识别对应的历史方案和隐藏规则。

提交给 AI 的任务至少应包含：

• 业务目标和非目标
• 输入、输出和接口约定
• 正常流程、异常流程和边界条件
• 涉及的模块、数据表和上下游服务
• 历史兼容要求
• 验收标准

生成结果可能看似正确

AI 生成的代码通常结构完整，但仍可能存在错误假设、伪造接口、遗漏错误处理或测试只覆盖实现而未验证需求等问题。代码能够编译不代表业务正确。

人工验收成本仍然存在

AI 输出必须由开发人员负责验证，包括：

• 确认需求理解和设计方案
• 检查代码修改范围
• 运行单元测试、集成测试和回归测试
• 核对兼容性、性能、安全与数据影响
• 完成人工 Code Review

推荐使用流程

第一步：准备上下文

提供需求文档、相关代码范围、项目规范、调用链和历史兼容要求，避免一次性加载无关文件。

第二步：先分析再修改

先让 AI 输出需求理解、影响范围、风险点和实施计划。开发人员确认方向后，再进入编码阶段。

第三步：拆分任务

将复杂需求拆成可独立验证的小任务，每个任务明确：

• 要修改什么
• 不允许修改什么
• 需要遵循哪些约束
• 如何验证完成

第四步：实现并自检

要求 AI 在修改后执行格式化、静态检查和相关测试，并说明实际修改内容、验证结果和未覆盖风险。

第五步：人工验收

开发人员重点检查业务正确性、兼容逻辑、数据安全、并发行为和修改边界，不能只依据 AI 的自检结论。

第六步：沉淀经验

将反复出现的项目结构、编码规范、业务约束和验证命令写入项目文档，减少后续重复补充上下文的成本。

适用范围

MCP 接入步骤

添加 MCP 服务器

1. 进入 Codex 设置中的 MCP 服务器页面，选择添加服务器。
2. 按目标服务提供的信息填写服务名称、协议类型、服务 URL 和所需鉴权信息。
3. 保存配置，确认服务器已启用。

适用范围

使用文档检索或诊断工具前，应确认目标环境、权限和数据范围；本页不提供内部服务配置。