1. 项目概述
这份AGENTS.md文档是我在长期使用Codex AI进行全栈开发过程中逐步完善的"智能助手工作手册"。它的核心目标是将Codex从一个单纯的代码生成工具,训练成能够独立完成从需求理解到部署上线的全流程交付伙伴。
在实际工作中,我发现很多开发者(包括曾经的我)都陷入了一个误区:把AI助手当作"高级代码补全工具"。这导致我们仍然需要花费大量时间在需求梳理、方案设计、测试验证等非编码环节。而这份手册的价值在于,它建立了一套完整的工程方法论,让AI能够真正以工程师的思维方式参与整个交付生命周期。
2. 核心设计理念
2.1 交付导向的工作哲学
与传统AI使用方式最大的不同在于,这份手册强调"交付"而非"编码"。这意味着:
- 结果可验证:每个任务都必须有明确的验收标准,不能停留在"代码看起来没问题"的阶段
- 闭环思维:前端改动要考虑后端接口,API开发要同步考虑调用方和测试方案
- 风险意识:对数据库变更、核心流程修改等高危操作建立严格的验证机制
实践心得:在早期版本中,我曾因为忽视部署环节导致多个"代码能跑但无法上线"的情况。现在会在方案设计阶段就要求AI提供部署影响分析。
2.2 证据优先原则
手册中反复强调的"证据优先"原则改变了我的工作方式:
- 调试时要求提供日志片段而非主观描述
- 性能优化必须附带基准测试数据
- 技术选型需要对比实验结果的量化指标
这种工作方式显著减少了"我觉得应该可以"带来的后续问题。一个典型案例是最近优化API响应时间的任务,通过要求AI提供各环节的耗时分析,我们准确锁定了N+1查询这个根本问题。
3. 任务分级体系
3.1 三级任务分类法
手册将任务分为L0-L2三个级别,这个分类在实践中表现出极强的实用性:
| 级别 | 典型场景 | 处理策略 | 文档要求 |
|---|---|---|---|
| L0 | 文案修改、样式调整 | 直接执行 | 变更说明 |
| L1 | 功能模块开发 | 最小化设计 | 验证报告 |
| L2 | 架构改造 | 完整流程 | 决策记录 |
3.2 分级实施案例
以实际项目中的支付模块改造为例:
- L0任务:修改错误提示文案 - 直接提交变更,附带截图验证
- L1任务:新增支付方式 - 提供接口契约和前端联调方案
- L2任务:支付流程重构 - 产出架构图、迁移方案和回滚计划
这种分级处理使项目进度可视化程度大幅提升,也避免了过度设计带来的资源浪费。
4. 全栈工作流详解
4.1 五阶段交付模型
手册定义的标准工作流已成为我的日常开发范式:
- 需求理解:创建
context-scan.json记录关键问题 - 方案设计:使用
shrimp-task-manager拆解子任务 - 实施开发:遵循"小步快跑"原则,每个commit都可独立验证
- 测试验证:根据风险等级选择测试策略
- 交付上线:提供部署checklist和监控指标
4.2 跨领域协作要点
在全栈开发中,最易出现的就是"前后端断层"。手册特别强调了几个关键控制点:
- 接口契约:使用OpenAPI规范作为唯一真相源
- 数据流验证:从数据库到UI的全链路检查
- 状态管理:明确加载、空态、错误等边界条件
最近开发的用户管理系统就受益于这套方法,前后端并行开发却实现了首次联调即通过。
5. 工具链最佳实践
5.1 智能工具矩阵
手册推荐的MCP工具组合极大提升了工作效率:
mermaid复制graph TD
A[复杂推理] --> B(sequential-thinking)
C[任务拆解] --> D(shrimp-task-manager)
E[代码理解] --> F(serena)
G[文档查询] --> H(context7)
注:实际使用中我发现
serena对TypeScript代码库的理解尤为出色,能准确识别跨模块依赖。
5.2 降级处理策略
当遇到工具不可用时,手册建议的降级方案非常实用:
- 本地grep替代语义搜索
- 手动拆分复杂任务
- 聚焦核心路径验证
这种务实态度避免了工具链故障导致的整体工作停滞。
6. 代码质量保障体系
6.1 四层验证策略
根据手册指导,我建立了分层次的验证机制:
- 静态检查:ESLint+TypeScript类型系统
- 单元测试:Jest+React Testing Library
- 集成测试:Cypress端到端测试
- 监控告警:Sentry错误追踪
6.2 代码审查要点
手册提出的"三要三不要"原则已成为团队CR标准:
- 要审查业务逻辑正确性
- 要检查异常处理完整性
- 要验证变更影响范围
- 不要纠结个人风格偏好
- 不要要求过度抽象
- 不要强求测试覆盖率数字
7. 文档管理实践
7.1 轻量级文档体系
基于手册建议,我们优化了文档结构:
code复制.codex/
├── decision-log.md // 关键决策记录
├── verification/ // 按日期的验证报告
└── operations/ // 特殊操作记录
这种结构既保证了必要信息的留存,又避免了文档负担。
7.2 活文档原则
我们特别认同手册中"文档服务于协作"的理念:
- 将API文档嵌入代码注释
- 用测试用例作为功能说明书
- 通过CHANGELOG记录迭代历程
8. 风险控制机制
8.1 确认边界清单
根据项目特点,我们扩展了必须确认的操作类型:
- 修改身份认证相关逻辑
- 涉及第三方服务计费的操作
- 影响核心业务指标的变更
8.2 熔断机制
当出现以下情况时自动暂停任务:
- 连续3次测试失败
- 部署预检查不通过
- 关键路径性能下降超过30%
9. 持续改进方法
9.1 手册迭代周期
我们建立了季度回顾机制:
- 分析
.codex/operations-log.md中的高频问题 - 评估工具链使用效率
- 调整任务分级标准
9.2 效果度量指标
通过三个维度评估改进效果:
- 交付效率:从需求到上线的平均周期
- 缺陷密度:每千行代码的缺陷数
- 返工率:因需求误解导致的修改比例
经过半年实践,我们的返工率下降了62%,这很大程度上归功于手册中强调的"先理解再实现"原则。
10. 典型问题排查
10.1 需求理解偏差
现象:交付物与预期不符
解决方案:
- 使用
structured-request.json模板澄清需求 - 制作原型图确认理解
- 拆分验收标准为可验证条目
10.2 接口不一致
现象:前后端联调失败
预防措施:
- 开发前约定接口契约
- 使用Mock服务并行开发
- 建立接口测试套件
11. 效能提升技巧
11.1 上下文加速
通过预加载常用上下文提升效率:
bash复制# 预加载项目架构
serena --preload ./src
# 缓存文档索引
context7 --cache-docs react,vue
11.2 智能补全配置
在.vscode/settings.json中添加:
json复制{
"codex.promptPrefix": "根据AGENTS.md L1标准",
"codex.responseFormat": "markdown"
}
12. 经验总结
这套方法论给我带来的最大改变是思维方式的转变 - 从"写代码"到"交付价值"。最明显的收益体现在:
- 需求阶段:问题发现提前,减少后期返工
- 开发阶段:代码质量提升,缺陷率下降
- 交付阶段:上线过程平稳,故障处理更快
建议初次使用者可以从L1任务开始实践,逐步适应这种工作模式。对于复杂项目,务必坚持"先设计后实现"的原则,这个时间投入最终会带来数倍的回报。
