给 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 现实的鸿沟

✅ 理论上成立的地方

  1. 反馈闭环存在 — E2E 测试确实提供了反馈
  2. 探索空间可定义 — 代码变体的行动空间是离散且可枚举的
  3. 指标量化 — 业务指标(转化率、延迟、成本)可以量化
  4. 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. 场景挖掘 — 识别业务中的关键场景和边界情况

    例:优化搜索延迟
    - 核心场景:1 字、3 字、10 字查询
    - 边界场景:空查询、特殊字符、超长查询
    - 并发场景:100 并发、1000 并发
    - 冷启动场景:缓存清空后的首次查询
    
  2. 指标维度扩展 — 不只优化单一指标,考虑约束条件

    不只:延迟 < 100ms
    而是:延迟 < 100ms AND 内存占用 < 500MB AND 可维护性得分 > 7/10
    
  3. 反例构造 — 主动为 AI 设置”困难”的测试用例,迫使 AI 深度思考

    例:故意构造"最坏情况"的数据分布,让 AI 不得不考虑鲁棒性
    

实施建议

  • 定期审视 E2E 测试套件,补充新发现的场景
  • 使用”行为树”或”场景矩阵”系统地枚举测试维度
  • 优先覆盖”会影响用户体验”或”容易出 bug”的边界

第二层:目标函数层面(C)

目标:确保 AI 优化的方向与真实业务需求对齐,避免优化错方向。

人类的角色

  1. 指标定义审视 — 定期评估”我们真的在优化正确的东西吗?”

    例:推荐系统
    - 初期目标:最大化点击率
    - 发现问题:用户点击率高但复购率低(点击的是烂推荐)
    - 调整目标:同时优化复购率,或用"转化率"代替"点击率"
    
  2. 约束条件明确 — 在优化过程中引入显式约束

    不只说:"延迟越低越好"
    而是说:"延迟需要 < 100ms,同时内存不能超 500MB,代码复杂度不能增加"
    
  3. 权衡评估 — 在多个目标之间权衡,提示 AI 什么样的权衡是可接受的

    例:多目标优化
    - 能接受:延迟增加 10%,换取 memory 减少 30%
    - 不能接受:延迟增加 20% 来换任何东西
    

实施建议

  • 每个迭代周期(周、月)复盘一次指标,看是否还适用
  • 将约束条件显式写入 E2E 测试中(不只是通过/失败,还要返回各维度的数值)
  • 建立”指标委员会”,定期讨论目标是否需要调整

第三层:反馈诊断层面(B — AI 自我启发)

目标:让 AI 能够像人类一样,从 badcase 中自动推导出改进策略。

难点:这是最难的,因为需要 AI 学会”科学方法”。

人类的角色(赋能,而非直接干预):

  1. 提供诊断工具和数据

    当 E2E 测试失败时,自动收集和整理:
    - 详细日志(结构化,便于 AI 分析)
    - 性能分析(CPU、Memory、IO 时间分解)
    - 对比数据(失败 case vs 成功 case 的差异)
    - 代码覆盖率(哪些代码路径被执行了)
    
  2. 示范”科学的诊断过程”

    通过文档、代码注释、甚至示范代码,教会 AI:
    
    当延迟超时时,诊断流程:
    1. 检查是否是数据量问题(数据量 > X 时经常超时?)
    2. 如果是,尝试"分页处理"或"索引优化"
    3. 检查是否是算法问题(特定数据分布下超时?)
    4. 如果是,尝试"改进算法复杂度"
    5. 检查是否是 IO 问题(网络/DB 慢?)
    6. 如果是,尝试"缓存"或"批量操作"
    
  3. 反馈循环的显式化

    不只返回"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 中维护”最佳诊断实践”文档

关键洞察

为什么这个框架能工作?

  1. 降低人的工作量,但没有让 AI 完全自主

    • 人负责:战略层(测试设计、目标定义)
    • AI 负责:执行层(大量尝试、快速迭代)
  2. 避免盲目优化

    • 通过扩展 E2E 测试,确保 AI 看到真实问题
    • 通过明确约束,确保 AI 不走偏
    • 通过诊断赋能,确保 AI 能学会改进
  3. 利用 AI 的核心优势:速度和规模

    • 人类无法手工尝试 100 种方案
    • AI 可以,并在每次尝试中快速学习

这个框架的局限

  1. 启发式推理仍是瓶颈

    • 当问题涉及跨域知识时(算法 + 系统设计 + 业务逻辑),AI 的自主诊断能力有限
    • 需要人类持续投入来教会 AI「怎么思考」
  2. 测试覆盖的完整性有上限

    • 现实场景的复杂性远超任何本地测试
    • 总会有「线上才会暴露的问题」
  3. 多目标优化的困难

    • 当目标之间有冲突时(低延迟 vs 高准确度),AI 的权衡决策能力有限
    • 需要人类明确定义权衡规则

总结

在明确了需求指标、设计了全面的 E2E 测试、定义了优化约束的前提下,AI 可以在这个「人类设定的强化学习环境」中快速探索实现空间,找到接近最优的方案。 这个框架非常适合

  • 纯优化问题(指标驱动)> 需求不明确的问题
  • 有清晰指标可量化的领域 > 定性需求领域 其中AI 可能为了通过 E2E 测试而”作弊”(满足测试但不满足真实需求),需要额外的”泛化性检查”机制。

最终人类的角色从「写代码」转变为「设定游戏规则和指导策略」。