从“会写代码”到“会管理 AI 工程”：Codex 实战中的项目文档规范设计
AI 编程时代，最大的瓶颈不是 AI 不会写代码，而是 AI 不知道项目为什么这样设计。
当项目规模从几十个文件增长到几万行代码，单纯依赖聊天上下文已经不可持续。优秀的 AI Coding 实践，需要给 Agent 建立一套“项目记忆系统”。
一、AI Coding 的新问题：代码生成容易，项目理解困难
过去的软件开发流程：
需求
↓
架构设计
↓
编码
↓
测试
↓
上线开发者的大脑承担了大量隐性知识：
- 为什么选择这个技术？
- 为什么这个模块这样拆？
- 哪些坑踩过？
- 哪些方案被否决？
- 当前开发进行到哪里？
这些信息通常存在：
- 聊天记录
- Jira / 禅道
- 个人记忆
- 临时 Markdown
- Git commit message
但是 AI Agent 没有这些长期记忆。
每次开启 Codex / Claude Code / Cursor：
AI:
“请告诉我项目背景。”
开发者:
“你先看看代码……”
AI:
扫描几十分钟……然后：
- 上一次讨论的架构忘了
- 已经解决的问题重新分析
- 历史方案重复评估
- 上下文窗口快速消耗
因此，AI Coding 的核心问题变成：
如何让 AI 像一个长期参与项目的高级工程师一样工作？
答案：
建立项目级 AI 文档架构。
二、核心思想：把项目文档变成 AI 的长期记忆
实践中，一个好的 AI 工程项目，需要解决四件事：
根据实际规范设计，文档体系主要解决：
-
项目入口
新人或者 AI 能快速知道：
- 项目是什么
- 如何启动
- 如何验证
-
Agent 入口
AI 每次接手任务：
- 先读什么
- 不应该读什么
- 如何恢复上下文
-
决策追溯
记录：
- 为什么这么设计
- 为什么不用其他方案
- 历史问题如何解决
-
会话连续
每次 AI 会话结束：
- 保存现场
- 保存下一步
- 下次继续工作
这实际上就是给 AI 建立：
项目的“长期记忆层”。
三、推荐的 AI Coding 项目目录结构
一个适合 Codex / Claude Code 的工程结构：
project/
├── AGENTS.md
├── README.md
├── STARTUP.md
├── CHANGELOG.md
├── HANDOFF.md
├── DoneAndTODO.md
├── .codexignore
│
├── docs/
│ ├── README.md
│ ├── documentation-architecture-standard.md
│ │
│ ├── architecture/
│ │
│ ├── adr/
│ │
│ ├── validation/
│ │
│ ├── handoff/
│ │
│ ├── archive/
│ │ └── done-and-todo/
│ │
│ ├── troubleshooting.md
│ │
│ └── templates/
│
└── scripts/
├── session-start.sh
└── session-end-check.sh这个结构最大的特点：
高频信息放根目录，长期知识放 docs。
四、最重要的文件：AGENTS.md
如果说 README 是给人看的，
那么：
AGENTS.md 是给 AI Agent 看的。
它定义：
- AI 工作规则
- 项目约束
- 常用命令
- 会话启动方式
- 会话结束方式
例如：
# Project Agent Guide
## Runtime
Java 21
Spring Boot 3.x
Maven
## Session Start
开始编码前：
1. 阅读 HANDOFF.md
2. 阅读 DoneAndTODO.md
3. 阅读 active checklist
不要默认读取：
- archive
- history
- logs
## Risk Gate
以下操作必须确认：
- 数据库 migration
- 删除数据
- 架构调整
- 大范围重构
## Git Rules
不要主动 commit。这样以后 AI 任务：
用户：
继续上次任务AI：
自动：
读取 AGENTS.md
↓
读取 HANDOFF.md
↓
读取 DoneAndTODO.md
↓
恢复现场不再需要复制几千字 Prompt。
五、HANDOFF.md：解决 AI “失忆”
这是整个体系里最有价值的文件。
它不是历史记录。
它代表：
当前项目现场。
例如：
# HANDOFF
## Current Status
已完成：
- 用户登录模块重构
- Redis缓存优化
## Current Task
正在处理：
订单支付链路优化
## Blocker
支付回调测试环境不可用
## Next Step
1. 完成接口测试
2. 更新ADR
3. 验收
## Dirty Files
src/payment/*核心原则：
HANDOFF 永远保持短。
不要写成：
2026-01 做了什么
2026-02 做了什么
2026-03 做了什么
...历史交给：
docs/handoff/规范建议：
- HANDOFF：100～150 行以内
- 超过：归档旧版本。
六、DoneAndTODO.md：AI 的路线图
很多 AI Coding 失败，是因为：
AI 不知道：
“现在最重要的事情是什么”。
所以需要：
DoneAndTODO.md保存：
- 已完成
- 当前阶段
- 下一步
- 长期 TODO
例如：
# Done
## Completed
[x] 用户中心重构
[x] Redis缓存升级
# TODO
## Current Sprint
- 支付链路压测
- MQ异常恢复
## Long Term
- 引入搜索服务
- 优化RAG召回它和 HANDOFF 区别：
| 文件 | 作用 |
|---|---|
| HANDOFF | 当前接手现场 |
| DoneAndTODO | 项目路线图 |
七、ADR：让 AI 知道“为什么”
很多 AI 生成代码最大的问题：
代码能运行。
但是：
架构可能错。
原因：
AI 不知道历史决策。
例如：
为什么不用 Redis Search？
为什么使用 Milvus？
为什么订单服务拆出去？
需要：
docs/adr/保存：
Architecture Decision Record。
示例：
docs/adr/
0001-use-milvus-vector-search.md
0002-payment-service-split.md内容：
# ADR 0001
## Context
业务需要知识库检索。
## Decision
采用 Milvus + BGE Embedding。
## Alternatives
ES Vector Search
## Consequences
优点：
- 大规模向量检索
缺点：
- 增加运维组件ADR 解决：
AI 可以理解过去为什么这么做。
八、Validation：不要相信“应该可以”
AI Coding 最大风险：
AI 认为完成，实际上没有验证。所以需要：
docs/validation/保存：验证过程。例如：
docs/validation/
payment-checklist.md
2026-07-26-payment-report.mdChecklist:
## 验证步骤
1. 启动服务
2. 调用接口
curl xxx
预期：
返回200Report:
环境：
Ubuntu 24.04
结果：
通过
证据：
curl返回200
SQL结果正常区别：
| 文件 | 作用 |
|---|---|
| checklist | 怎么验证 |
| report | 这次验证结果 |
九、.codexignore：控制 AI 上下文成本
很多人不知道，AI 最大的问题不是不会搜索。而是搜索太多。
例如：
rg xxx .扫描：
node_modules
target
日志
编译产物
.git
缓存产生大量无价值 Token，因此需要增加.codexignore 文件
.codexignore例如：
.git/
.idea/
target/
node_modules/
dist/
.venv/
*.log对AI而言，最终产生的效果是：
有效代码
+
有效文档而不是：
代码
+
垃圾生成文件
+
历史日志十、AI 编程必须引入“证据等级”
传统开发：一句话 ---> “已经完成。”
AI 时代：肯定是远远不够的，必须区分：
| 标记 | 含义 |
|---|---|
| Verified | 已验证 |
| Source-read | 只读源码确认 |
| User-confirmed | 用户确认 |
| Target-design | 目标设计 |
| Assumption | 推测 |
| Blocked | 阻塞 |
例如：错误方式
已经支持千万级并发而实际正确的应该是：
Target-design:
设计支持千万级
Verified:
压测10000 QPS通过这个机制非常重要。
因为 AI 最容易犯浑：
把设计方案描述成已经实现。
十一、高风险操作必须增加人工确认
AI Agent 能力越来越强。
但是：
不能让 AI 自动执行所有事情。
必须人工确认：
- 数据库迁移
- 删除数据
- 架构调整
- 密钥操作
- 大范围重构
推荐流程：
AI：
当前状态：
计划：
修改：
验证：
风险：
需要确认：等待：
用户确认再执行。
十二、会话开始 / 结束自动化
优秀 AI Coding 流程：
不是：
打开IDE
输入问题
开始聊天而是：
Session Start
固定流程：
git status
git branch
git log
读取:
HANDOFF.md
DoneAndTODO.md
Active ChecklistSession End
完成工作后：
自动检查：
是否更新：
HANDOFF
DoneAndTODO
CHANGELOG
ADR
Troubleshooting十三、最终效果：AI 从“代码助手”升级为“项目成员”
没有规范：
AI:
帮我写个接口
↓
重新理解项目
↓
重复踩坑有规范：
AI:
读取项目记忆
↓
理解架构
↓
知道历史决策
↓
继续当前任务
↓
留下新的现场这实际上形成：
项目代码
|
|
+---------------+
| AI Knowledge |
| Layer |
+---------------+
|
--------------------------------
AGENTS
README
HANDOFF
ADR
Architecture
Validation
Troubleshooting
--------------------------------
|
Codex十四、适合企业落地的 AI Engineering 标准
未来的软件工程，不只是：
代码管理而是：
代码管理
+
知识管理
+
AI上下文管理
+
决策管理
+
验证管理一个成熟 AI Coding 项目应该具备：
✅ AI 可快速接手
✅ 新人快速理解
✅ 架构决策可追溯
✅ 历史问题可查询
✅ 会话上下文自动恢复
✅ 防止 AI 误操作
总结
Codex、Claude Code、Cursor 这些工具真正进入企业开发后，最大的变化不是：
AI 写代码更快。
而是：
软件项目开始拥有“机器可理解的工程记忆”。
未来优秀工程师的能力，不只是设计系统和写代码。
还包括：
如何设计一个让 AI 高效协作的软件工程体系。
而 AGENTS.md + HANDOFF.md + ADR + Validation + docs 架构，正在成为 AI Coding 时代新的工程基础设施。
封面彩蛋（均为一次性成图，未做二次优化）：
微信AI生图v1：
简短提示词优化：
标题：从 “会写代码” 到 “会管理 AI 工程”：Codex 实战中的项目文档规范设计
基于标题内容，以及参考图优化一下图并生成一个新的公众号AI生图v2
千问网页版：基于v1版生成
介于千问生成此图时，我和它沟通过具体事项，后单开一个会话，无上下文污染进行成图效果：
我也是笑了。。。。
豆包网页版基于V1版生成：
chatgpt网页版基于V1版生成：
Gemini网页版基于V1版生成：
汇聚全球AI编程工具，助力开发者即刻编程。
更多推荐
8
0- 0
已为社区贡献2条内容
所有评论(0)