摘要：V2EX 关于 Codex 项目上下文的讨论，指向一个更工程化的问题：如何让 AI 不再每次都像新来的开发，而是逐步理解项目结构、业务约定、代码风格和历史决策。
最近 V2EX 上有个讨论很典型：大家已经不满足于让 Codex “看代码、改代码、修 bug”，而是开始追问一个更工程化的问题：如何让 AI 不要每次都像新来的开发，而是能逐渐理解项目结构、业务约定、代码风格和历史决策？
这个问题背后，其实是 AI 编程从“单次对话提效”进入“组织知识沉淀”的信号。单次任务里，模型能力、上下文长度、工具调用都很重要；但一旦进入真实项目，真正决定稳定性的往往不是模型会不会写一段代码，而是它能不能知道“这个项目以前是怎么做的”。
一、项目经验应该放在哪里？
讨论里有几类答案：README、AGENTS.md、docs、rules、skill、MCP、Trellis。看起来很多，其实可以按职责分层。
README 面向人，适合写项目介绍、启动方式、部署说明。docs 面向人和 AI，适合放业务流程、架构设计、接口约定、模块说明。AGENTS.md 更像 AI 的入口路由文件，告诉 Agent 应该先读哪里、哪些规范优先、哪些命令能跑、哪些目录不要乱动。skill 则更适合沉淀跨项目、跨团队可复用的流程能力。MCP 负责连接外部系统，比如 GitHub、数据库、Issue、文档系统、浏览器。Trellis 这类框架则把 specs、tasks、journals、workflow 组织成一套更完整的项目知识库。
所以更合理的答案不是选一个，而是分层：
- AGENTS.md：入口和路由。
- docs/spec：稳定的项目知识。
- skill：可复用的工作流程和团队经验。
- MCP：实时外部工具和数据。
- Trellis：任务、规范、日志、上下文的结构化承载层。
如果只做一个项目，AGENTS.md 加 docs 可能已经足够；如果是一组产品、多个仓库、多人协作，就应该把经验上升到产品级或组织级 skill；如果团队已经开始并行让多个 Agent 做任务，Trellis 这种任务化、渐进式披露的知识库就更有价值。
二、最重要的原则：经验由人掌控，AI 负责补全
这个讨论里一个很重要的共识是：项目经验不能完全交给 AI 自己沉淀。AI 可以总结代码结构，可以梳理业务流程，可以从历史提交里发现约定，但最后必须有人审核。
原因很简单：AI 很擅长把“局部事实”组织成文档，但它不一定知道哪些事实是原则，哪些只是历史包袱；哪些写法是推荐实践，哪些只是临时妥协；哪些接口不能动，哪些可以重构。真实项目里的经验不只是“代码里有什么”，还包括“为什么当时这么做”“哪些坑踩过”“哪些事情不要再犯”。
一个比较稳的流程是：
- 让 Codex 先读代码、读文档、读提交记录，整理初版项目说明。
- 人审核：删除错的、补充隐含约定、标出高风险边界。
- 再让 Codex 基于修订后的说明生成实施计划。
- 人 review 计划，发现缺失规范就继续补 docs 或 AGENTS.md。
- 每次任务结束后，让 Codex 写工作日志和经验补丁，但不要自动合入核心规范。
这套流程的重点不是让 AI 自己“记忆”，而是让 AI 帮人维护一套可审计、可演进、可回滚的项目手册。
三、AGENTS.md 和 skill 的区别
有个争议点很有意思：如果 skill 只是把 AGENTS.md 从项目层提到公司层，那它的优势在哪里？
我的理解是，AGENTS.md 和 skill 的边界不在“内容高级不高级”，而在“作用范围和可复用性”。
AGENTS.md 更适合绑定具体仓库。它应该告诉 Agent：这个项目是什么、目录结构如何、前端后端分别在哪、测试怎么跑、哪些命令危险、编码风格看哪些文件、遇到某类任务先读哪个文档。它是项目入口。
skill 更适合绑定一类工作方式。比如代码审查、发布检查、接口生成、数据库迁移评审、日报发布、日志排查、Java Spring Boot 分层开发规范。这些流程可能在多个项目里复用，甚至可以带脚本、模板和参考资料。skill 是可迁移的能力包。
如果团队里有多个仓库、多个 Agent 工具、多个开发者，skill 的优势会更明显：它可以通过 Git 管理，可以统一升级，可以被不同项目引用，也可以避免每个仓库复制一份越来越散的提示词。
四、MCP 不该泛化接入，应该按权限设计
MCP 的价值很直接：让 Agent 不只是读本地代码，还能访问 GitHub、Issue、数据库、内部文档、浏览器和 CI。真实项目里，MCP 最适合处理“当前工作区之外”的信息。
但 MCP 也最容易失控。数据库要不要接？要接，但优先只读。Issue 要不要接？要接，但写回评论前最好人工确认。生产系统要不要接？能不接就不接，必须接也要有明确权限边界和审计。
一个实用原则是：MCP 负责“取证”和“执行外部动作”，skill 负责“告诉 Agent 怎样判断和操作”。两者不要混在一起。比如排查线上 bug 时，MCP 可以读日志、查 issue、看监控；skill 则规定排查顺序、输出格式、风险边界和何时必须停下来问人。
五、Trellis 的价值：把项目知识变成渐进式披露
这次链接指向的 reply16 提到了 Trellis。它最值得借鉴的点，不是又多了一个 AI 工具，而是“渐进式披露的项目知识库”。
很多团队维护 AI 上下文时会走两个极端：要么只写一个很短的 AGENTS.md，信息不够；要么把所有规范塞进一个巨大文档，Agent 每次都读一堆无关内容。Trellis 的思路更像工程化分层：工作流放 .trellis/workflow.md，分层规范放 .trellis/spec/，任务和 PRD 放 .trellis/tasks/，工作日志和会话轨迹放 .trellis/workspace/。
这样做的好处是，Agent 不必一次吃完整个知识库，而是在不同任务阶段读取相关上下文。做 API 就读 API 规范，改前端就读组件规范，收尾时写工作日志，继续任务时从 task 和 journal 恢复。它解决的不是“模型不聪明”，而是“上下文如何被组织、维护和按需加载”。
对个人项目来说，Trellis 可能显得重；但对多仓库、多模块、长期迭代的项目，它可以减少三类浪费：重复解释背景、重复踩旧坑、重复让 Agent 猜项目约定。
六、推荐的一套落地路径
如果从零开始，我不建议一上来就搭很复杂的 AI 工程体系。可以按四步走。
第一步，先补 AGENTS.md。写清项目定位、技术栈、目录结构、常用命令、测试方式、危险操作、文档入口。目标是让 Agent 进项目后知道先读什么。
第二步，建立 docs/spec。把稳定知识拆出来：业务流程、接口约定、数据模型、错误码、组件规范、部署流程、常见故障。不要写成口号，要写成 Agent 可以执行的判断依据。
第三步，把高频流程做成 skill。比如“新增一个 Spring Boot 接口”“审查 SQL 变更”“发布前检查”“排查日志”“生成测试”。skill 里可以放步骤、检查清单、模板和脚本，让同一类任务每次都按同一套流程走。
第四步，再考虑 Trellis。只要项目开始出现多任务并行、长期任务恢复、多人共用 AI 规范、跨仓库上下文共享，就可以引入 Trellis 这类结构化框架，把任务、规范、日志和工作流统一起来。
七、对 Java / Spring Boot 项目的特别建议
Java 后端项目通常业务重、分层厚、历史包袱多。对这类项目，最有效的不是让 Codex 自由发挥，而是让它模仿团队已有做法。
可以把以下内容写进规范：
- Controller、Service、Repository 的职责边界。
- DTO、Entity、VO 的转换方式。
- 事务边界和异常处理规则。
- 状态码、错误码、返回体格式。
- 日志格式和敏感字段脱敏规则。
- 单测、集成测试、Mock 策略。
- 数据库迁移和 SQL 审查流程。
- 已有工具类、封装库、内部组件的使用示例。
一句话：不要告诉 Agent “写得优雅一点”，要告诉它“这个项目以前怎么写，现在继续这么写”。
结语
这次 V2EX 讨论真正有价值的地方，是把 Codex 的使用问题从“怎么调提示词”推进到了“怎么管理组织知识”。AI 编程的上限不只取决于模型，也取决于团队能否把经验沉淀成结构化、可维护、可复用的上下文。
AGENTS.md 是入口，docs 是事实，skill 是流程，MCP 是工具，Trellis 是组织方式。它们不是互相替代，而是共同构成一套 AI 时代的软件工程基础设施。
未来优秀的开发团队，可能不只是代码写得好，还会有一套同样优秀的 Agent 工作手册：让新人能更快上手，也让 AI 不再像新来的开发。
参考链接：