AI 工程化落地：推翻"完美架构"，回归提示词本质

TL;DR

AI 工程化的本质不是设计复杂的 Agent 架构，而是把知识结构化地写成提示词。一个 AGENTS.md 文件，比三层架构 + 九步工作流更有效。

一个”完美”架构的诞生与死亡

团队最初设计了一套”正经”的 AI 辅助开发架构：Command 层 → Agent 层（phase-router、design-manager、impl-coordinator、experience-depositor）→ Skill 层，配合严格的九步工作流。

每一步都有专门的 Agent，每个 Agent 都有专门的 Skill，一切井井有条。

然后现实打脸了。

改一个配置文件的默认值，需要：创建微需求 → 等待路由识别 → 初始化工作空间 → 改那一行代码。15 分钟走流程，1 秒钟改代码。

而直接在聊天框里说”帮我在 user 表加一个 last_login_at 字段”，5 分钟，完事。

如果按照设计的架构来做，效率更高还是更低？ 这个问题让人很不舒服——意味着过去几天的设计工作可能是无效的。

两个产品的启发

NotebookLM：简单到让人惭愧

没有”智能路由”，没有”多 Agent 协作”，没有”知识图谱”。就是来源 + 对话 + 输出，三栏设计。但它解决了核心问题：让人能快速消化大量信息。

本质公式：

输出 = f(来源, 输出格式)

我们的三层架构是在 f 上做文章，但 NotebookLM 告诉我们：f 已经够强了，问题在于如何组织好输入。

Claude Code：反直觉的极简主义

Anthropic 团队的经验：

“一开始 Claude Code 就能给自己创建和使用工具。我们试图在后台创建一个复杂的工具图……我们做的越多，它就变得越不可靠。”

“你给模型的工具越少，每次调用的效率就越高。与其创造很多小的、精确的工具，不如创造大的、表达力强的工具，然后信任模型。”

“最好的工具是你不知道它存在的工具。”

核心洞察：LLM 本身就是最好的解释器，文本是通用接口。 不需要中间层的意图识别或路由调度，Markdown 就够了。

认知转变：从代码到文本

维度	旧思维	新思维
让 AI 遵循规范	开发工具强制执行	写成提示词让 AI 理解
管理 AI 状态	设计元数据系统	保存到文件，下次读取
沉淀经验	开发”经验管理 Agent”	写文档，放到 context 目录
路由意图	开发”路由 Agent”	在提示词里写清楚决策逻辑

提示词是声明式的，代码是命令式的。 用代码实现流程需要处理所有边界情况；用提示词描述规范，AI 会自己处理细节。这不是偷懒，是利用 LLM 的能力降低工程复杂度。

三个落地原则

原则一：文档即记忆（Dual Use）

AGENTS.md 既是新人的入职手册，也是 AI 的核心记忆。同一份文档，人类和 AI 都能读懂。不需要维护两套知识体系。

原则二：先跑起来

从最简单的提示词开始。一个能用的简单系统，好过一个完美但用不起来的复杂系统。

原则三：自然演进

观察团队如何使用工具，将高频模式固化为能力。不预设复杂架构，让需求驱动演进。

“构建一个足够开放的产品，观察人们如何’滥用’它，然后为此而构建。“

最简起点：一个文件搞定

在项目根目录创建 AGENTS.md：

# AGENTS.md

## 项目背景
这是 xxx 项目，使用 Go + MySQL，核心服务包括用户服务和订单服务。

## 工作规范
- 先读代码再改，不要猜测未检查的代码
- 代码注释用中文，变量命名用英文
- 不确定的地方问我，不要自己瞎猜

## 常见坑点
（遇到问题再补充）

这就是全部起点。 随着使用自然生长：基础背景 → 补充踩过的坑 → 形成知识索引。

提示词设计技巧

XML 标签隔离指令：用 <dos> <donts> 区分该做和不该做
写决策逻辑：而不是散乱的规则
记录 AI 易犯的错：每次犯错后加入 AGENTS.md，最低成本的”模型微调”
简单自然语言：比复杂工具更有效——“有不清楚的就问我”、“先想想方案再动手”

何时封装成工具？

如果在 AGENTS.md 里写几句话就能达到同样效果，那就不需要封装。只为高频的”内部循环”操作封装——比如每天用数十次的 /commit-push-pr。

解决 AI “失忆”问题

AI 是无状态的纯函数。解决方案：把记忆保存到文件，新会话时恢复。

# process.txt

## 当前状态
正在开发用户认证功能，API 已完成，下一步写单元测试。

## 已完成
- [x] 设计 JWT Token 结构
- [x] 实现登录接口

## 待完成
- [ ] 编写单元测试
- [ ] 处理 Token 刷新逻辑

最重要的技巧：给 AI 验证方式

“这可能是从 Claude Code 获得出色结果的最重要的事情——给 Claude 一种验证其工作的方式。如果有反馈循环，最终结果的质量提高 2-3 倍。”

后端跑测试、前端浏览器预览、配置重启验证——给 AI 能看到输出的工具，告诉它这个工具存在，AI 会自己弄清楚其余的部分。

高级技巧：独立上下文自我审查

完成代码后，不要在同一个会话中 review。开启全新会话对改动进行审查——两个互不知道对方上下文的窗口，往往能发现明显的逻辑漏洞。

团队共享：单仓库模式

团队不需要”50 个 Agent 实例”，只需要”1 个 Agent 工程 + 50 个独立的上下文空间”。

团队共享仓库（master）
├── AGENTS.md          ← 所有人共用的 AI 记忆
├── context/           ← 所有人共用的知识库
└── .codebuddy/        ← 所有人共用的工具

开发者 A 的 checkout     开发者 B 的 checkout
├── (继承 master)        ├── (继承 master)
├── feature/auth         ├── feature/payment
└── 独立的工作空间        └── 独立的工作空间

知识共享 + 工作隔离。好的实践通过 PR 合并回 master，所有人受益。

为什么不需要 RAG

直接给 AI grep、find、ls 能力。它能像资深工程师一样，通过文件结构和关键词自己找到答案。对于代码库这种结构化数据，简单的语义搜索往往不如 Agent 主动探索精准。

复合工程：让每次实践产生复利

“我们团队为 Claude Code 仓库共享单个 CLAUDE.md。每当看到 Claude 做错什么，就添加到 CLAUDE.md，这样下次就知道不要那样做了。”

把纠错变成资产：

执行次数	耗时	原因
第 1 次	45 分钟	记录坑点
第 2 次	20 分钟	AI 自动提醒
第 n 次	5 分钟	知识已编码进系统

三层迭代循环：

日常：遇到问题 → 解决 → 记录
每周：整理归类 → PR → 团队 Review → 合并
每月：识别高频模式 → 讨论是否封装 → 创建 Command/Skill

核心总结

AI 工程化的三个认知转变：

从”精密设计”到”最简起点” —— 一个 AGENTS.md 比三层架构更有效
从”代码实现”到”文本描述” —— 提示词是声明式的，代码是命令式的
从”个人使用”到”团队共享” —— 单仓库模式让知识流动

AI 工程化没有银弹。 先让它跑起来，在实践中迭代。工具是线性的，系统是复利的。

本文整理自腾讯云开发者公众号文章，原作者侯迎圣。核心观点：不要为 AI 开发复杂工具，把知识结构化地写下来就够了。