1. 从完美架构到提示词本质:AI工程化的实践反思
作为一名长期从事AI落地的技术从业者,我最近经历了一次深刻的认知转变。我们团队原本设计了一套看似完美的AI辅助开发架构,却在实践中发现过度设计反而成为效率的绊脚石。这段经历让我意识到:在AI工程化领域,简单直接的提示词往往比复杂架构更有效。
1.1 完美架构的幻灭
我们最初的设计包含三层架构:
- Command层:处理用户输入
- Agent层:包含设计管理、实现协调等专业Agent
- Skill层:各种具体执行技能
还配套设计了严格的九步工作流,从需求录入到需求关闭,每一步都有专门的Agent负责。这个架构在纸面上看起来非常完美,但当我们尝试用它完成一个简单的数据库字段添加任务时,发现问题了:
"帮我在user表加一个last_login_at字段,datetime类型,默认null,然后在登录接口里更新它。"
这个简单的需求如果走完整架构流程,需要:
- 创建微需求
- 等待意图识别
- 路由到实现协调Agent
- 初始化工作空间
- 最后才能修改代码
而直接给AI下指令,5分钟就完成了全部工作。这个对比让我们开始反思:复杂的架构是否真的必要?
1.2 两个产品的启示
Google的NotebookLM和Anthropic的Claude Code给了我们重要启发。NotebookLM的界面简单到让人惭愧——就是来源、对话、输出三栏设计,但它能高效解决信息消化问题。其核心公式是:
code复制输出 = f(来源, 输出格式)
Claude Code团队则分享了一个关键发现:
"一开始Claude Code就能给自己创建和使用工具。我们试图在后台创建一个复杂的工具图...我们做的越多,它就变得越不可靠。"
他们最终选择了最小化工具数量,信任模型的大表达能力。这与我们的复杂架构设计形成了鲜明对比。
2. 认知转变:从复杂架构到简单提示词
2.1 新旧思维对比
我们总结了新旧两种思维方式的差异:
| 维度 | 旧思维 | 新思维 |
|---|---|---|
| 规范执行 | 开发工具强制执行 | 写成提示词让AI理解 |
| 状态管理 | 设计元数据系统 | 保存到文件下次读取 |
| 经验沉淀 | 开发"经验管理Agent" | 写文档放到context目录 |
| 意图路由 | 开发"路由Agent" | 在提示词里写决策逻辑 |
核心观点:不需要为AI开发复杂工具,只需把知识结构化地写下来。
2.2 具体案例:代码规范执行
假设有个规范:提交代码前必须运行lint检查。
旧做法:
python复制# 开发pre-commit Skill
# 在impl-coordinator Agent里调用
# 检查失败返回特定错误码
# Agent根据错误码决定下一步
新做法:
markdown复制# AGENTS.md
## 代码提交规范
- 提交前必须运行`make lint`
- lint不通过不要提交,先修复问题
AI会自己读这段话并执行lint检查,不需要任何额外代码。这不是偷懒,而是利用LLM的理解能力降低工程复杂度。
3. 落地实践:三个核心原则
基于反思,我们提炼出三个落地原则:
3.1 文档即记忆(Dual Use)
AGENTS.md既是新人入职手册,也是AI的核心记忆。同一份文档,人类和AI都能读懂使用,无需维护两套知识体系。
写文档时要想象在给一个聪明但对项目一无所知的新同事讲解——这个新同事可能是人类,也可能是AI。
3.2 先跑起来
从最简单的提示词开始,让AI辅助工作能用起来。不要追求完美设计,先让流程运转。
Claude Code创作者的工作流:
"大多数会话都从计划模式开始。与Claude来回讨论直到满意其计划,然后切换到自动接受编辑模式。"
不是设计复杂"计划Agent",而是用对话确认计划后再执行。
3.3 自然演进
观察团队如何使用(甚至"滥用")工具,将高频模式固化为能力。不预设复杂架构,让需求驱动演进。
"构建一个足够开放的产品,观察人们如何'滥用'它,然后为此而构建。"
4. 最简起点:一个文件搞定AI工程化
4.1 基础配置:AGENTS.md
在项目根目录创建AGENTS.md:
markdown复制# AGENTS.md
## 项目背景
这是xxx项目,使用Go + MySQL,核心服务包括用户服务和订单服务。
## 工作规范
- 先读代码再改,不要猜测未检查的代码
- 代码注释用中文,变量命名用英文
- 不确定的地方问我,不要自己瞎猜
## 常见坑点
(遇到问题再补充)
这就是全部起点。启动AI工具,它会自动读取这个文件开始工作。
4.2 提示词演进路径
随着使用,提示词会自然生长:
起步阶段:基础背景
markdown复制## 项目背景
微服务架构,Go语言,核心服务有用户服务、订单服务。
积累阶段:补充踩坑经验
markdown复制## 常见坑点
- Apollo配置格式:key必须是xxx.yyy.zzz三段式
- 数据库连接:测试环境IP是10.0.0.1,不是localhost
- 商品发放:虚拟商品发到虚拟钱包,实物商品发到实体钱包
成熟阶段:形成知识索引
markdown复制## 关键知识
详细的技术背景见context/目录:
- 服务架构:context/tech/services/
- 业务逻辑:context/business/
- 历史经验:context/experience/
关键:不要一开始设计完美知识结构,遇到什么记什么,自然演进。
5. 高级技巧与最佳实践
5.1 提示词设计技巧
技巧1:用XML标签隔离指令类型
xml复制<coding_style>
<dos>
- 错误处理必须包装:fmt.Errorf("failed to x: %w", err)
- 日志必须带traceId
</dos>
<donts>
- 禁止使用panic
- 禁止在循环中调用数据库
</donts>
</coding_style>
技巧2:写决策逻辑而非散乱规则
markdown复制## 遇到不确定的业务逻辑时
1. 先搜索context/business/下的相关文档
2. 如果文档没写,搜索相关代码实现
3. 如果代码也不明确,再问我
技巧3:记录AI易犯错误
markdown复制## AI注意事项
- 【重要】修改config后要重启服务才能生效
- 【重要】用户表的status字段:0=未激活,1=正常,2=封禁(不是布尔值!)
这是最低成本的"模型微调"——记一次,终身受益。
5.2 何时需要封装工具?
判断标准:如果在AGENTS.md里写几句话能达到同样效果,就不需要封装。
| 场景 | 是否需要封装 |
|---|---|
| 需要特定领域知识 | ✅ 是 |
| 流程复杂且固定 | ✅ 是 |
| 自然对话能完成 | ❌ 否 |
| 只是提示词优化 | ❌ 否 |
Claude Code创作者的经验:只为高频"内部循环"封装工具,如每天使用数十次的/commit-push-pr命令。
6. 解决AI"失忆"问题
6.1 核心问题与解决方案
LLM本质上是无状态的纯函数。会话结束,记忆清空。解决方案是把"记忆"保存到文件,新会话时恢复。
code复制会话内存(易失) 文件系统(持久)
↓ ↓
当前思维状态 ──保存──→ process.txt
↑ ↓
新会话开始 ←──恢复── process.txt
6.2 保存与恢复示例
会话结束前保存:
markdown复制# process.txt
## 当前状态
正在开发用户认证功能,API已完成,下一步是写单元测试。
## 已完成
- [x] 设计JWT Token结构
- [x] 实现登录接口
- [x] 实现Token校验中间件
## 待完成
- [ ] 编写单元测试
- [ ] 处理Token刷新逻辑
## 注意事项
- Token过期时间配置在config/auth.yaml
- 测试时需要先启动Redis
新会话开始时AI读取这个文件就能恢复上下文。
6.3 长期任务管理
对于复杂任务,创建features.json:
json复制{
"requirement_id": "example-requirement",
"features": [
{
"id": "F001",
"name": "用户登录",
"description": "实现用户登录功能",
"status": "done",
"related_files": ["src/login.ts"]
},
{
"id": "F002",
"name": "Token刷新",
"description": "实现Token刷新能力",
"status": "in_progress",
"related_files": ["src/refresh.ts"]
}
]
}
7. 团队协作:单仓库模式
7.1 为什么用单仓库?
团队不需要"50个Agent实例",只需要"1个Agent工程+50个独立上下文空间"。
知识层面:共享同一套AI配置(AGENTS.md、context/)
执行层面:每个成员在独立分支工作,互不干扰
目录结构示例:
code复制AgenticMetaEngineering/
├── AGENTS.md # AI的"入职手册"
├── context/ # 团队知识库
│ ├── team/ # 团队通用知识
│ └── project/ # 项目特定知识
├── requirements/ # 需求记录
└── .codebuddy/
└── commands/ # 自定义命令
7.2 知识组织原则
不需要向量数据库做RAG,直接给AI赋予grep、find、ls能力,让它像工程师一样主动探索。
组织原则:
- 按领域分文件夹:tech/、business/、experience/
- 文件名要清晰:让ls出来的列表就有语义
- 内容是Markdown:最自然的文本格式
8. 复合工程:让实践产生复利
8.1 核心理念
让每一单元的工程工作使后续工作变得更简单。
Claude Code团队实践:
"我们团队为Claude Code仓库共享单个CLAUDE.md。将它检入git,整个团队每周贡献多次。每当看到Claude做错什么,就添加到CLAUDE.md,这样Claude下次就知道不要那样做了。"
8.2 三层迭代循环
- 日常开发循环(每天):遇到问题→解决→记录
- 周期整理循环(每周):Review记录→整理归类→提交PR
- 能力固化循环(每月):识别高频模式→讨论封装→创建Command/Skill
8.3 通过PR共享经验
好的实践通过PR合并到master,全团队受益。示例PR:
markdown复制## PR标题
add: 商品发放钱包选择经验
## 变更内容
- 新增context/experience/商品发放-钱包问题.md
## 背景
开发xxx需求时发现虚拟商品和实物商品的钱包配置不同,多次踩坑后整理成文档。
9. 回顾与关键收获
9.1 核心认知转变
- 从"精密设计"到"最简起点"
- 从"代码实现"到"文本描述"
- 从"个人使用"到"团队共享"
9.2 落地三原则
- 文档即记忆:AGENTS.md是人机共用的入职手册
- 先跑起来:从最简单的提示词开始
- 自然演进:观察使用模式,让需求驱动演进
9.3 最重要的经验
给AI一种验证其工作的方式。Claude Code创作者强调:
"这可能是从Claude Code获得出色结果的最重要的事情——给Claude一种验证其工作的方式。如果Claude有这个反馈循环,它会将最终结果的质量提高2-3倍。"
不同场景的验证方式:
- 后端API:运行测试套件
- 前端UI:浏览器预览
- 配置变更:重启服务验证
- 移动应用:模拟器测试
10. 实践建议与避坑指南
10.1 新手入门路径
-
第一周:
- 创建基础AGENTS.md
- 记录3-5个常见坑点
- 尝试完成简单任务
-
第一个月:
- 建立context/目录结构
- 开始使用process.txt跟踪进度
- 邀请1-2位同事加入
-
第三个月:
- 形成稳定的知识沉淀流程
- 开发几个高频使用的自定义命令
- 团队全员参与
10.2 常见陷阱与解决方案
| 陷阱 | 症状 | 解决方案 |
|---|---|---|
| 过度流程化 | PR审核变成形式主义 | 简化Review标准,快速合并 |
| 只有少数人参与 | 大部分人从不提PR | 降低门槛,鼓励"小"贡献 |
| context膨胀 | 文件太多找不到 | 定期清理过时文档 |
| 知识过时 | 老文档误导人 | 遇到问题时顺手更新 |
10.3 效果评估指标
虽然难以精确量化,但可以关注:
- 重复性问题发生率下降
- 新人上手时间缩短
- 相同类型需求处理时间减少
- 团队知识分享频率提高
11. 个人实践心得
在实际使用这套方法三个月后,我总结了以下几点心得:
-
从小处着手:不要试图一次性构建完美系统。我们从简单的数据库字段修改开始,逐步扩展到完整功能开发。
-
信任但要验证:虽然AI能理解自然语言指令,但关键操作还是要验证。我们建立了"修改-测试-确认"的循环。
-
团队习惯培养:最初几周需要刻意培养记录习惯,现在团队成员遇到问题会自然想到"这个应该记到context/"。
-
灵活调整:我们发现最初设计的context/目录结构不太合理,经过两次调整才找到最适合团队的方式。
-
持续优化:每月我们会Review一次AGENTS.md和context/,删除过时内容,合并重复条目。
这套方法最让我惊喜的是它的适应性——无论是后端API开发、前端页面调整,还是基础设施配置,都能通过适当的提示词和知识组织来高效完成。它可能不是AI工程化的终极答案,但确实是我们团队目前找到的最实用、最可持续的实践方式。