给 Agent 的代码规范
我的 Claude.md 最后就保留了如下 Prompt:
同时沉淀了大量的历史设计、系分文档以及最佳实践。
确保架构设计没有问题
对于重要的需求文档、架构文档、数据结构设计,需要反反复复让LLM. 反复确认,可能需要打开多个窗口、使用不同的模型(Claude Opus、GPT5.2 hign 等)十几轮优化、确认原文档没有问题。
为什么说这是「大型强化学习场景」?
1. Reward Signal:E2E 测试中的业务指标
E2E 测试不仅仅是 PASS/FAIL,而是提供量化的反馈信号:
示例:推荐系统转化率优化
- 目标指标:转化率 > 15%
- E2E 测试运行:完整用户链路(搜索 → 浏览 → 点击 → 下单)
- Reward:实际转化率数值(14.2% → 14.8% → 15.3%)
相比单纯的 PASS/FAIL 二元反馈,连续型的量化指标 让 AI 能够:
- 判断某个改进是否有效(哪怕不完全满足要求)
- 评估改进幅度(改进 0.1% vs 1% 是不同的)
- 在有限的探索空间内找到最优解
2. Action Space:AI 能尝试的实现变体
在探索性问题中,AI 的行动空间是代码实现方案的组合:
目标:降低查询延迟
可能的 Action:
- 改进算法(线性搜索 → 二分搜索 → 哈希表)
- 优化数据结构(List → Set → Tree)
- 加缓存策略(无 → LRU → LFU)
- 调参数(缓存大小、过期时间)
- 并行化部分逻辑
- ...
传统开发中,这些方案需要人脑枚举和决策,速度慢且容易遗漏。
AI 的优势是可以大批量、系统地探索这个空间,每次尝试都有 E2E 测试的反馈。
3. State Observation:Badcase 分析
AI 获得的不仅是指标数值,还需要诊断信息来指导下一步探索:
FAIL case: 用户搜索超时(>5s)
诊断信息应包括:
- 哪类数据会超时?(数据量大小、数据特征)
- 代码哪个环节是瓶颈?(网络、算法、IO)
- 性能分析数据(CPU、内存、IO 时间分布)
这些信息构成 AI 的「状态观察」,用来调整策略。
理论 vs 现实的鸿沟
✅ 理论上成立的地方
- 反馈闭环存在 — E2E 测试确实提供了反馈
- 探索空间可定义 — 代码变体的行动空间是离散且可枚举的
- 指标量化 — 业务指标(转化率、延迟、成本)可以量化
- AI 能快速迭代 — 相比人类,AI 尝试速度快得多
❌ 实践中的主要瓶颈
瓶颈 1:局部最优陷阱
问题:AI 可能陷入某个局部最优方案,无法跳出来探索更好的全局最优。
示例:缓存优化
- 方案 A:LRU 缓存,命中率 70%,延迟 100ms
- 方案 B:智能预热 + LFU,命中率 85%,延迟 60ms
如果 AI 先尝试 A 并取得不错效果,它可能会在 A 的微调上花太多时间,
错过「完全不同思路 B」的机会。
原因:
- AI 缺乏启发式洞察 — 「这个方向到头了,该换思路了」
- 贪心策略 — AI 自然倾向于改进当前最好的方案,而不是探索新方向
- 反馈信号不足 — E2E 测试只告诉你「这个方案好不好」,不告诉你「还有更好的方向吗」
瓶颈 2:反馈信息不完整
问题:AI 很难像人类一样从 badcase 中自动推导出启发式改进方向。
例子:某个查询超时
- 人类的思路:
1. 看日志找出具体瓶颈(数据库查询慢?网络慢?算法复杂度高?)
2. 基于瓶颈提出有针对性的改进(加索引?改算法?)
3. 评估改进的可行性和副作用
- AI 目前的做法:
1. 知道"这个 case 失败了"
2. 生成一些代码变体
3. 重新测试
缺少从「失败现象」到「改进策略」的自动推导。
根本原因:
- 系统环境复杂(日志、监控、代码、业务数据分散)
- 需要跨域知识(算法、系统设计、业务逻辑)
- AI 需要被教会「科学的诊断方法」,而不是靠自己领悟
瓶颈 3:测试覆盖不足导致盲点
问题:E2E 测试的设计质量直接决定了 AI 探索的有效性。
例子:推荐系统
- 差的 E2E 测试:只测试"主流用户操作" → AI 优化的方案对小众场景无效
- 好的 E2E 测试:覆盖边界情况(新用户、冷启动、异常操作)→ AI 优化考虑全面
影响:
- 测试设计的盲点 = AI 探索的盲点
- 人类需要持续扩充和优化测试用例,帮助 AI 发现隐藏的需求
实践落地框架:三层干预机制
基于上述分析,AI 的强化学习过程需要人类在三个层面的干预:
第一层:测试设计层面(A)
目标:扩大 AI 的探索空间,让 E2E 测试覆盖足够多的场景维度。
人类的角色:
-
场景挖掘 — 识别业务中的关键场景和边界情况
例:优化搜索延迟 - 核心场景:1 字、3 字、10 字查询 - 边界场景:空查询、特殊字符、超长查询 - 并发场景:100 并发、1000 并发 - 冷启动场景:缓存清空后的首次查询 -
指标维度扩展 — 不只优化单一指标,考虑约束条件
不只:延迟 < 100ms 而是:延迟 < 100ms AND 内存占用 < 500MB AND 可维护性得分 > 7/10 -
反例构造 — 主动为 AI 设置”困难”的测试用例,迫使 AI 深度思考
例:故意构造"最坏情况"的数据分布,让 AI 不得不考虑鲁棒性
实施建议:
- 定期审视 E2E 测试套件,补充新发现的场景
- 使用”行为树”或”场景矩阵”系统地枚举测试维度
- 优先覆盖”会影响用户体验”或”容易出 bug”的边界
第二层:目标函数层面(C)
目标:确保 AI 优化的方向与真实业务需求对齐,避免优化错方向。
人类的角色:
-
指标定义审视 — 定期评估”我们真的在优化正确的东西吗?”
例:推荐系统 - 初期目标:最大化点击率 - 发现问题:用户点击率高但复购率低(点击的是烂推荐) - 调整目标:同时优化复购率,或用"转化率"代替"点击率" -
约束条件明确 — 在优化过程中引入显式约束
不只说:"延迟越低越好" 而是说:"延迟需要 < 100ms,同时内存不能超 500MB,代码复杂度不能增加" -
权衡评估 — 在多个目标之间权衡,提示 AI 什么样的权衡是可接受的
例:多目标优化 - 能接受:延迟增加 10%,换取 memory 减少 30% - 不能接受:延迟增加 20% 来换任何东西
实施建议:
- 每个迭代周期(周、月)复盘一次指标,看是否还适用
- 将约束条件显式写入 E2E 测试中(不只是通过/失败,还要返回各维度的数值)
- 建立”指标委员会”,定期讨论目标是否需要调整
第三层:反馈诊断层面(B — AI 自我启发)
目标:让 AI 能够像人类一样,从 badcase 中自动推导出改进策略。
难点:这是最难的,因为需要 AI 学会”科学方法”。
人类的角色(赋能,而非直接干预):
-
提供诊断工具和数据
当 E2E 测试失败时,自动收集和整理: - 详细日志(结构化,便于 AI 分析) - 性能分析(CPU、Memory、IO 时间分解) - 对比数据(失败 case vs 成功 case 的差异) - 代码覆盖率(哪些代码路径被执行了) -
示范”科学的诊断过程”
通过文档、代码注释、甚至示范代码,教会 AI: 当延迟超时时,诊断流程: 1. 检查是否是数据量问题(数据量 > X 时经常超时?) 2. 如果是,尝试"分页处理"或"索引优化" 3. 检查是否是算法问题(特定数据分布下超时?) 4. 如果是,尝试"改进算法复杂度" 5. 检查是否是 IO 问题(网络/DB 慢?) 6. 如果是,尝试"缓存"或"批量操作" -
反馈循环的显式化
不只返回"Fail"或数值,而是: { status: "fail", metric: 120ms, // 超过 100ms 限制 diagnosis: { bottleneck: "database_query", // 瓶颈分析 suggestion: "consider_index_on_user_id", // 启发式建议 evidence: "95% of time spent in db_query" } }
实施建议:
- 构建一个”诊断 Engine”,能够自动分析失败 case,生成诊断报告
- 在项目的
.claude/skills中维护”最佳诊断实践”文档
关键洞察
为什么这个框架能工作?
-
降低人的工作量,但没有让 AI 完全自主
- 人负责:战略层(测试设计、目标定义)
- AI 负责:执行层(大量尝试、快速迭代)
-
避免盲目优化
- 通过扩展 E2E 测试,确保 AI 看到真实问题
- 通过明确约束,确保 AI 不走偏
- 通过诊断赋能,确保 AI 能学会改进
-
利用 AI 的核心优势:速度和规模
- 人类无法手工尝试 100 种方案
- AI 可以,并在每次尝试中快速学习
这个框架的局限
-
启发式推理仍是瓶颈
- 当问题涉及跨域知识时(算法 + 系统设计 + 业务逻辑),AI 的自主诊断能力有限
- 需要人类持续投入来教会 AI「怎么思考」
-
测试覆盖的完整性有上限
- 现实场景的复杂性远超任何本地测试
- 总会有「线上才会暴露的问题」
-
多目标优化的困难
- 当目标之间有冲突时(低延迟 vs 高准确度),AI 的权衡决策能力有限
- 需要人类明确定义权衡规则
总结
在明确了需求指标、设计了全面的 E2E 测试、定义了优化约束的前提下,AI 可以在这个「人类设定的强化学习环境」中快速探索实现空间,找到接近最优的方案。 这个框架非常适合
- 纯优化问题(指标驱动)> 需求不明确的问题
- 有清晰指标可量化的领域 > 定性需求领域 其中AI 可能为了通过 E2E 测试而”作弊”(满足测试但不满足真实需求),需要额外的”泛化性检查”机制。
最终人类的角色从「写代码」转变为「设定游戏规则和指导策略」。