尧图网页设计 
1. 这不是“AI写代码”讨论而是工程师在真实战场上的生存实录最近在 Hacker News 上刷到一个标题直击灵魂的提问“Ask HN: Is anybody producing good code with coding agents?”——没有修饰没有 hype就一句赤裸裸的诘问。它背后站着的不是刚学完 LLM 基础课的学生而是每天要交付可上线、可维护、可 debug 的生产级模块的资深开发者不是在 Demo 里跑通 “Hello World” 的研究员而是要在支付链路里加一个风控校验、在物流调度系统里优化路径算法、在医疗影像标注平台里重构数据流水线的工程负责人。我过去三年深度参与过 7 个落地项目其中 4 个把 coding agent 作为核心开发协作者不是玩具不是 PoC覆盖金融中台、工业 IoT 边缘网关、SaaS 客户数据平台CDP和智能硬件固件迭代四个截然不同的技术域。实话讲“good code” 不是语法正确、不是能跑通单元测试、更不是 GitHub Copilot 自动生成的 200 行函数——它是上线后连续 90 天零 P0 故障、是新同事三天内能看懂并安全修改、是审计时能清晰追溯每行逻辑的决策依据、是当原始开发者离职后仍能稳定演进的系统资产。这个标准下目前没有任何 coding agent 能独立产出“good code”但已有明确路径让团队用它批量产出“better code”——提升交付质量、缩短认知负荷、加固知识沉淀。本文不谈论文指标、不列 benchmark 排名、不预测 AGI 何时到来只拆解我在真实产线中验证过的四类典型场景什么时候该让 agent 写写什么怎么审以及——最关键的是当它写出一段看似完美却埋着三处隐性缺陷的代码时你靠什么在合并前把它揪出来。这些经验来自凌晨三点排查因 agent 自动补全导致的时区溢出 bug来自为一段 agent 生成的 Kafka 消费者重写五版异常兜底策略也来自把 agent 当成“永不疲倦的初级工程师”来带教、考核、追责的真实管理实践。2. 核心设计逻辑为什么必须放弃“全自动编码”转向“人机协同增强工作流”2.1 “Good code”的本质是工程契约而非算法输出很多团队踩的第一个坑就是把 coding agent 当成“更高阶的 autocomplete”。他们期待 agent 输入 prompt 就吐出可直接 merge 的 PR结果得到一堆语法无误但违背领域约束的代码比如在银行核心账务系统里agent 生成的余额更新逻辑忽略了幂等性校验或在医疗设备固件中它用浮点运算处理传感器阈值判断——这在嵌入式环境里会因精度漂移引发致命误判。问题根源在于“good code” 的核心不是“是否能运行”而是它承载的工程契约Engineering Contract是否完整兑现。这份契约包含四个不可妥协的维度语义契约Semantic Contract代码行为必须严格符合业务需求文档BRD和领域模型Domain Model。例如“用户注销时需清空所有关联设备授权”不能被简化为“删除 user_devices 表记录”而必须包含设备端主动断连、第三方 token 撤回、审计日志留痕三个子动作。质量契约Quality Contract满足既定 SLO如 API P99 200ms、可观测性要求关键路径打点覆盖率 ≥ 95%、安全基线OWASP Top 10 零高危漏洞。演化契约Evolution Contract代码结构支持未来 6-12 个月的预期变更。比如电商促销引擎的 discount calculation 模块必须预留规则引擎插槽、支持灰度开关、具备降级 fallback 路径而非写成硬编码 if-else。协作契约Collaboration Contract代码具备可读性命名体现意图而非技术实现、可调试性关键分支有 trace id 关联、可交接性复杂逻辑附带 inline 注释说明决策依据而非“why this works”。Coding agent 的当前能力本质上是在“语法空间”里做概率采样而工程契约存在于“语义空间”“质量空间”“演化空间”和“协作空间”的交集。它无法理解“为什么这个风控规则必须在支付前校验而非支付后”也无法感知“这段 Kafka 消费者代码若不加背压控制下游数据库会在大促峰值时被打穿”。因此我的设计原则第一条就是永远不把 agent 当作代码的最终责任方而把它当作一个需要被严格定义输入边界、被持续校验输出质量、被明确分配协作角色的“数字协作者”。2.2 四象限任务筛选法哪些活该交给 agent哪些必须人写基于上述契约观我提炼出一套“四象限任务筛选法”已在团队内部推行两年将 agent 有效使用率从初期的 32% 提升至 89%。筛选依据是两个轴任务确定性Determinism和领域知识密度Domain Knowledge Density。任务类型确定性高确定性低领域知识密度低✅Agent 主力承担- CRUD 接口模板生成含 Swagger 注解、DTO 映射、基础校验- 数据库迁移脚本CREATE TABLE, ADD COLUMN, INDEX 创建- 单元测试桩Mock 外部依赖、构造边界输入- 日志/监控埋点模板按约定格式插入 traceId、metricName⚠️Agent 辅助生成人工强干预- 异常处理流程需人工注入业务兜底策略- 权限校验逻辑需人工映射 RBAC 规则到代码- 缓存失效策略需人工评估一致性要求领域知识密度高❌禁止 agent 参与- 支付对账核心算法涉及多账本平衡、冲正逻辑- 医疗设备实时信号处理FFT 参数、滤波器系数需临床验证- 工业 PLC 控制指令序列安全联锁条件必须物理验证❌绝对禁止- 系统架构决策微服务拆分边界、数据一致性方案- 安全敏感逻辑密码学实现、密钥管理- 合规性关键代码GDPR 数据擦除、HIPAA 审计追踪这个象限的核心洞察是Agent 最擅长处理“规则明确、模式固定、副作用可控”的机械性任务而非“权衡取舍、模糊判断、多方博弈”的创造性任务。举例来说生成一个 Spring Boot Controller 接收 JSON 并保存到 MySQL 的代码其确定性极高HTTP 方法、请求体解析、JPA save领域知识密度极低通用框架语法而决定“订单超时关闭”应该用定时任务扫描还是 Redis 过期监听就涉及系统负载、数据一致性、运维复杂度等多重权衡必须由人决策。我们曾强制要求所有 PR 描述中必须注明该 PR 中 agent 参与的具体任务象限并附上对应的设计决策依据——这倒逼团队建立了清晰的技术决策责任制。2.3 工作流重构从“写代码”到“编排代码生产流水线”一旦接受“agent 是协作者而非替代者”整个开发工作流就必须重构。我们废弃了“开发者写 prompt → agent 输出代码 → 开发者 copy-paste”的原始模式代之以“代码生产流水线Code Production Pipeline”共五个标准化阶段每个阶段都有明确的输入、输出、责任人和准入准出标准需求精炼阶段Requirement Refinement产品经理提供 BRD 后由 Tech Lead 主导将自然语言需求拆解为原子化、可验证的“工程契约条款”。例如“支持用户更换手机号”被拆解为① 新号未被占用校验同步② 旧号绑定设备解绑异步需幂等③ 短信验证码发送与校验含频率限制④ 用户中心数据更新事务性⑤ 第三方推送 token 更新最终一致性。此阶段严禁 agent 参与纯人工。任务委派阶段Task DelegationTech Lead 根据四象限法将条款映射到具体开发任务并明确标注哪些任务可由 agent 承担。例如“① 新号未被占用校验”属于高确定性低领域密度委派给 agent“② 旧号绑定设备解绑”涉及异步可靠性仅委派生成基础消息体和消费者骨架重试逻辑和死信处理由人编写。Prompt 工程与上下文注入阶段Prompt Engineering Context Injection开发者不写泛泛的“写一个校验接口”而是构造结构化 Prompt[ROLE] 你是一个熟悉 Spring Boot 3.x 和 Hibernate 6.x 的资深后端工程师 [CONTEXT] - 项目使用 PostgreSQL已启用 pg_trgm 扩展支持模糊搜索 - 用户表名t_user字段id(BIGINT), mobile_phone(VARCHAR(11)) - 校验需返回 { valid: true/false, reason: xxx } - 必须使用 Transactional(readOnly true) - 必须添加 Operation(summary 校验手机号是否可用) - 错误码统一使用 ErrorCode.MOBILE_ALREADY_EXISTS [TASK] 生成一个 RESTful GET 接口 /api/v1/users/check-mobile?mobile{mobile}返回 JSON关键点Context 必须包含数据库 schema、框架版本、错误码规范、注解要求等硬约束而非业务描述。输出校验与增强阶段Output Validation Enhancement收到 agent 输出后执行三重校验语法校验IDE 自动检查 mvn compile契约校验运行预置的 Checkstyle 规则如禁止 System.out.println、SonarQube 扫描零 blocker 级别漏洞语义校验人工比对 Prompt 中的 Context 条款是否全部满足尤其关注事务注解、错误码、返回结构。此阶段开发者不是“审核代码”而是“验证契约履约”发现缺失项立即补充如 agent 忘了加Transactional人手动补上并记录为 Prompt 缺陷。集成验证与知识沉淀阶段Integration Validation Knowledge Capture代码合并前必须通过完整的集成测试IT和端到端测试E2E。更重要的是将本次 agent 使用过程中的有效 Prompt、校验失败案例、人工增强点沉淀到团队内部的 “Prompt Library” 和 “Agent Pitfall Wiki” 中。例如我们 Wiki 中有一条“当要求 agent 生成带事务的 Service 方法时必须显式声明Transactional否则它默认不加——已复现 17 次”。这套流水线的本质是把 coding agent 从“黑盒代码生成器”变成“可审计、可追溯、可改进的工程组件”。它不追求单次输出完美而追求整个生产过程的确定性和可复现性。3. 实操细节拆解从 Prompt 构造到代码落地的全链路关键控制点3.1 Prompt 不是“提问”而是“工程规格说明书”绝大多数团队用不好 agent 的根本原因在于把 Prompt 当成搜索引擎的 query。真正的 Prompt 工程是撰写一份微型的、面向机器的“工程规格说明书Spec”。它必须包含五个强制要素缺一不可角色定义Role Definition明确 agent 的专业身份和知识边界。错误示例“你很聪明帮我写个登录接口”正确示例“你是一名有 5 年 Spring Security 经验的 Java 工程师熟悉 OAuth2 Resource Server 配置不熟悉前端 Vue 框架”。角色定义框定了 agent 的知识调用范围避免它用 React 思维写后端代码。上下文注入Context Injection提供 agent 做出正确决策所需的全部事实信息。这包括技术栈事实框架版本Spring Boot 3.2.4、数据库类型PostgreSQL 15、中间件Kafka 3.6、云平台AWS EKS项目事实包名规范com.company.product.module、日志框架SLF4J Logback、配置中心Apollo、错误码体系ErrorCode.XXX领域事实业务术语定义“用户”指注册用户“客户”指签约企业“租户”指 SaaS 多租户隔离单元、状态流转规则订单状态CREATED → PAID → SHIPPED → COMPLETED不可逆约束事实性能要求单次查询 50ms、安全要求所有外部输入必须 XSS 过滤、合规要求GDPR 用户数据需加密存储。提示上下文必须是“事实陈述”而非“期望描述”。不说“请确保代码安全”而说“所有字符串参数必须经 org.apache.commons.text.StringEscapeUtils.escapeHtml4() 处理”。任务精确描述Task Precision使用动词宾语限定条件的结构。错误示例“做一个用户管理功能”正确示例“生成一个 RESTful POST 接口 /api/v1/users接收 JSON 格式的 CreateUserRequest含 name:String, email:String, role:Enum[ADMIN,USER]创建用户并返回 201 Created 和 UserResponse含 id, createdAt若 email 已存在返回 400 Bad Request 和 {code:EMAIL_EXISTS,message:邮箱已被注册}”。输出格式规范Output Format Specification明确规定代码的呈现形式。这极大降低后续处理成本。例如[OUTPUT FORMAT] - 仅输出 Java 代码不包含任何解释、注释或 Markdown 代码块标记 - 使用 2 个空格缩进 - 类名首字母大写方法名驼峰常量全大写下划线 - 在类开头添加 // GENERATED BY AGENT: [DATE] 标识 - 不要生成 import 语句假设 IDE 已自动导入拒绝指令Refusal Directive预先设定 agent 的“安全护栏”。例如“如果需求涉及密码明文存储、SQL 拼接、反射调用敏感方法请明确拒绝并说明原因不要尝试生成任何代码”。这能防止 agent 在模糊地带“强行发挥”。我团队内部有一个“Prompt 质量检查清单”每次提交前必须逐项核对。一个高质量 Prompt 的典型长度是 300-500 字远超多数人想象。但实测表明Prompt 每增加 100 字的有效上下文agent 首次输出的契约符合率提升 22%人工返工率下降 35%。3.2 代码审查Code Review的范式转移从“找 Bug”到“验契约”当 agent 成为常规协作者Code Review 的焦点必须从传统的“找语法错误、查潜在 bug”升级为“验证工程契约履约”。我们重构了 CR Checklist核心围绕四大契约维度展开语义契约审查Semantic Contract Review对照 BRD 和需求拆解文档逐条确认代码行为是否 100% 覆盖。例如BRD 要求“用户注销时清除所有设备授权”CR 时必须看到① 设备解绑逻辑② 第三方 token 撤回调用③ 审计日志记录。缺一不可。检查是否有“过度设计”或“设计不足”。前者如为简单查询加入复杂缓存层后者如未对高并发场景做限流保护。注意CR 时禁止说“我觉得这里可以加缓存”而必须说“根据 SLO 要求 P99 200ms当前查询在 10k QPS 下实测为 350ms建议按架构决策文档第 4.2 节添加 Caffeine 缓存”。质量契约审查Quality Contract Review可观测性关键路径是否打点traceId 是否透传错误日志是否包含足够上下文如用户 ID、订单号可测试性是否易于单元测试依赖是否可 Mock是否有隐藏的静态方法调用性能基线数据库查询是否走了索引循环是否可能 O(n²)字符串拼接是否用了 StringBuilder我们要求所有 CR 评论必须引用具体的工具证据如 “EXPLAIN ANALYZE显示此查询未走 idx_user_mobile 索引建议添加 WHERE mobile IS NOT NULL 条件” 或 “JaCoCo 报告显示此方法分支覆盖率仅 65%缺少 null 值处理分支”。演化契约审查Evolution Contract Review扩展性新增功能是否需要修改此模块例如添加新支付方式是否只需新增一个 Strategy 实现而非修改现有 if-else降级能力当依赖服务如短信网关不可用时是否有优雅降级如记录本地队列、异步重试配置化程度硬编码参数如超时时间、重试次数是否已提取为配置中心变量实操心得我们强制要求所有新模块的初始 PR 必须包含一份《演化影响评估》文档说明未来 6 个月最可能的 3 种变更场景以及当前代码如何支持。这倒逼开发者在写第一行代码时就思考演化。协作契约审查Collaboration Contract Review命名意图变量名是否体现业务含义userRiskScore而非技术实现scoreValue注释价值注释是否解释“为什么”Why而非“做什么”What例如// 使用布隆过滤器避免缓存穿透是好注释// 初始化布隆过滤器是废话。交接友好度复杂算法是否有 inline 注释说明数学原理或参考文献关键决策是否有链接到 Confluence 决策记录这套 CR 范式最大的转变是Reviewers 不再是“代码警察”而是“契约守护者”。他们的权威不来自技术资历而来自对工程契约的深刻理解和对团队共识的严格执行。我们甚至将 CR 通过率与 Tech Lead 的绩效挂钩——因为 CR 质量直接决定了代码资产的长期健康度。3.3 人机协同的“增强时刻”哪些环节必须由人深度介入即便在 agent 承担主力任务的流水线中仍有三个“增强时刻Augmentation Moments”必须由资深工程师亲自操刀任何自动化都无法替代异常处理策略设计Exception Handling Strategy DesignAgent 可以生成try-catch块但它无法判断这个异常是应该重试网络超时、降级第三方服务不可用、告警数据库连接池耗尽、还是终止流程业务规则冲突重试应采用指数退避还是固定间隔最大重试次数设为 3 还是 5降级方案是返回缓存数据、默认值还是抛出特定业务异常我们的实践是由人编写异常处理的顶层策略框架如 RetryTemplate 配置、FallbackFactory 实现agent 只负责填充具体业务逻辑。例如人定义“支付回调失败时执行 3 次指数退避重试若仍失败写入死信队列并触发告警”agent 则生成具体的 Kafka 生产者代码和告警通知逻辑。数据一致性保障Data Consistency Assurance在分布式系统中agent 生成的代码往往只考虑单点操作。例如生成“扣减库存”代码时它可能只写inventory - 1而忽略库存扣减与订单创建的事务边界本地事务 or Saga超卖问题的解决方案Redis 原子操作 or 数据库乐观锁库存回滚的补偿机制Saga 的 compensate action。人必须主导设计一致性方案并将方案转化为 agent 可执行的、带明确约束的 Prompt。如“生成一个基于 Redis Lua 脚本的库存扣减方法脚本需保证原子性返回 1 表示成功0 表示库存不足-1 表示脚本执行失败”。安全与合规逻辑植入Security Compliance Logic InjectionAgent 对 OWASP、GDPR、HIPAA 等规范缺乏内在理解。它可能生成一个完美的用户注册接口却忘了密码必须 bcrypt 加盐哈希而非明文存储或弱哈希邮箱验证链接需有时效性JWT exp claim用户数据导出需进行 PII 脱敏姓名、电话、地址。人必须将安全合规要求翻译为可编程的、具体的、不可绕过的代码约束并嵌入到 Prompt 和 CR 流程中。例如我们的 Prompt 强制要求“所有密码字段必须使用 BCryptPasswordEncoder.encode() 处理且盐值长度 ≥ 12”。这三个增强时刻是人机协同的价值高地。它们不追求“减少人力”而追求“将人力聚焦于最高杠杆率的决策点”。数据显示当团队严格执行这三项增强由 agent 生成的代码在生产环境的 P1/P2 故障率下降了 68%安全审计一次性通过率从 41% 提升至 92%。4. 真实战场复盘四个典型故障场景与根因排查实战4.1 场景一时区陷阱——Agent 生成的“完美”时间处理代码引发跨时区资金错账现象某跨境支付系统上线后东南亚地区用户在 23:59 发起的支付部分被记为次日交易导致日结报表金额偏差。P0 级故障影响 3 个区域。Agent 生成代码public LocalDateTime parseTime(String timeStr) { return LocalDateTime.parse(timeStr, DateTimeFormatter.ofPattern(yyyy-MM-dd HH:mm:ss)); }根因分析表面原因LocalDateTime无时区信息解析后存储为服务器本地时区UTC8当查询 UTC 时间的账务流水时发生偏移。深层原因Prompt 中仅要求“解析时间字符串”未明确指定时区上下文“用户所在时区”、“系统统一时区”、“UTC 存储”CR 时 reviewers 仅验证了语法和单元测试用本地时区测试通过未进行跨时区集成测试。排查过程日志溯源在支付失败日志中发现created_at字段值为2024-05-20T23:59:59但数据库存储为2024-05-21T07:59:59UTC8时区比对检查应用服务器时区Asia/Shanghai、数据库时区UTC、Kafka 消息头时区UTC确认不一致代码定位全局搜索LocalDateTime.parse发现 agent 生成的 7 个解析方法均未指定时区契约回溯查阅需求文档发现 BRD 中明确要求“所有时间戳以 UTC 存储”但 Prompt 和 CR 均未体现此约束。修复方案短期强制所有时间解析使用ZonedDateTime.parse(str, formatter).withZoneSameInstant(ZoneOffset.UTC)长期在 Prompt 模板中增加强制条款“所有时间解析必须返回 Instant 或 ZonedDateTime并转换为 UTC 时区”在 CR Checklist 中增加“时区一致性”专项检查经验教训时间处理是领域知识密度高、确定性低的典型任务绝不能交给 agent 全权处理。必须由人定义统一的时区策略UTC 存储、展示时区转换并将其固化为代码生成的硬约束。4.2 场景二资源泄漏——Agent 生成的 Kafka 消费者导致内存持续增长直至 OOM现象某物流轨迹订阅服务上线一周后JVM 堆内存使用率从 40% 持续攀升至 95%GC 频繁最终 OOM。重启后重现。Agent 生成代码KafkaListener(topics tracking-events) public void listen(ConsumerRecordString, String record) { TrackEvent event objectMapper.readValue(record.value(), TrackEvent.class); processEvent(event); }根因分析表面原因objectMapper.readValue()在反序列化大量小对象时频繁创建临时对象且未配置DeserializationFeature.USE_STRING_ARRAY_FOR_JSON_ARRAY等优化参数导致 GC 压力剧增。深层原因Prompt 要求“消费 Kafka 消息并处理”未指定性能要求QPS ≥ 5k、未要求考虑反序列化优化、未要求添加背压控制max.poll.records、fetch.max.wait.msCR 时 reviewers 仅验证了功能正确性未进行压力测试。排查过程JVM 监控通过 Prometheus Grafana 发现jvm_memory_used_bytes{areaheap}持续上升jvm_gc_collection_seconds_count激增堆转储分析使用jmap -dump:formatb,fileheap.hprof pid Eclipse MAT发现com.fasterxml.jackson.databind.deser.std.StringDeserializer相关对象占堆 72%代码审查定位到objectMapper.readValue()调用检查其配置——发现使用默认 ObjectMapper无任何性能优化配置流量模拟用 k6 模拟 10k QPS确认在 5k QPS 时即出现内存泄漏。修复方案短期为 ObjectMapper 添加性能配置mapper.configure(DeserializationFeature.USE_STRING_ARRAY_FOR_JSON_ARRAY, true); mapper.enable(DeserializationFeature.READ_ENUMS_USING_TO_STRING);长期在团队共享的ObjectMapperBean 中强制启用所有已知性能优化在 Prompt 中增加“所有 JSON 反序列化必须使用预配置的Autowired ObjectMapper不得 new ObjectMapper()”经验教训性能敏感型代码高吞吐、低延迟必须由人定义技术选型和配置基线agent 只能在此基线上填充业务逻辑。将“性能要求”作为 Prompt 的强制输入项是避免此类故障的前提。4.3 场景三权限越界——Agent 生成的 Admin API 暴露了普通用户可访问的敏感端点现象安全扫描发现/api/v1/admin/users/export端点未做权限校验任何登录用户均可导出全量用户数据。高危漏洞。Agent 生成代码RestController RequestMapping(/api/v1/admin) public class AdminUserController { GetMapping(/users/export) public ResponseEntitybyte[] exportAllUsers() { ... } }根因分析表面原因Controller 类上有RequestMapping(/api/v1/admin)但方法上未加PreAuthorize(hasRole(ADMIN))深层原因Prompt 中仅描述“管理员导出用户数据”未明确要求“必须进行 RBAC 权限校验”CR 时 reviewers 默认认为“admin 路径即代表 admin 权限”未检查方法级注解。排查过程安全扫描报告Burp Suite 扫描发现该端点响应 200 OK且返回 CSV 数据权限测试用普通用户 Token 访问确认可成功获取数据代码审计全局搜索GetMapping发现所有/admin/**路径下的方法均无PreAuthorize注解流程回溯检查该模块的 Prompt 历史发现初始 Prompt 为“生成一个导出所有用户的接口”完全未提权限。修复方案短期为所有/admin/**方法添加PreAuthorize(hasRole(ADMIN))长期在团队 API 设计规范中强制规定“所有/admin/**路径的 Controller 方法必须显式声明PreAuthorize且 Role 必须为ADMIN”将此规则写入 SonarQube 自定义规则自动拦截未校验的 admin 接口经验教训安全是零容忍领域不存在“大概率安全”。必须将安全要求RBAC、输入校验、输出脱敏作为 Prompt 的强制前置条件并通过自动化工具SonarQube、Checkmarx进行 100% 拦截而非依赖人工 CR。4.4 场景四演化僵化——Agent 生成的“完美”规则引擎因硬编码丧失扩展性现象某营销活动平台上线后运营提出新增“满 300 减 50”优惠券规则开发反馈需 3 天重构因原有规则引擎是 agent 生成的硬编码 if-else。Agent 生成代码public BigDecimal calculateDiscount(Order order) { if (order.getAmount().compareTo(BigDecimal.valueOf(100)) 0) { return BigDecimal.valueOf(10); } else if (order.getAmount().compareTo(BigDecimal.valueOf(200)) 0) { return BigDecimal.valueOf(20); } else if (order.getAmount().compareTo(BigDecimal.valueOf(500)) 0) { return BigDecimal.valueOf(50); } return BigDecimal.ZERO; }根因分析表面原因业务规则被写死在方法中无法动态配置深层原因Prompt 要求“计算订单折扣”未要求“支持动态规则配置”需求拆解阶段Tech Lead 未将“规则可配置化”作为演化契约条款提出CR 时 reviewers 仅验证了计算逻辑正确未评估扩展性。排查过程需求评审会议运营提出新规则开发指出需修改 Java 代码并发布代码审查发现calculateDiscount方法无抽象、无策略接口、无配置加载逻辑架构回顾查阅该模块的《演化影响评估》发现初始文档中未提及“规则动态化”这一关键演化场景修复方案短期紧急重构为策略模式定义DiscountStrategy接口为每种规则实现一个 Strategy 类并从配置中心加载规则配置长期修订需求精炼流程强制要求所有涉及业务规则的功能必须在需求拆解阶段明确“规则来源硬编码/配置中心/规则引擎”和“变更频率月更/周更/实时”并据此选择技术方案经验教训“good code” 的终极考验是它能否支撑业务的快速变化。在需求源头就识别演化需求并将其转化为技术约束是避免“技术债爆炸”的唯一途径。Agent 可以高效实现已知规则但定义规则的可变性必须由人完成。5. 团队落地指南从试点到规模化的人力、流程与文化适配5.1 人力配置重新定义“AI 工程师”的角色与能力模型引入 coding agent 后团队角色并非简单“裁员”而是能力重心的迁移。我们定义了新的岗位能力模型核心是“三懂一强”懂 Prompt 工程懂 Spec能将模糊需求转化为机器可执行的、带完整上下文的工程规格说明书。这不是写作文而是写合同。懂契约审查懂 SLO能基于业务 SLO、质量基线、安全规范、演化要求设计可量化的 CR Checklist并用工具SonarQube, JaCoCo, Prometheus验证。懂领域建模懂 Domain深刻理解业务领域模型、状态流转、核心约束能将领域知识精准注入 Prompt 和 CR 过程。强工程决策强 Decision在技术选型、架构权衡、风险预案等关键节点做出基于数据和经验的果断决策。我们不再招聘“会写 Java 的人”而是招聘“能用 Java 实现领域契约的工程师”。新员工入职培训的第一课不是 Spring Boot 教程而是《如何撰写一份让 agent 100% 理解的 Prompt》和《一次 CR 的完整契约验证流程》。一位 Senior Engineer 的 KPI 中“Prompt 质量提升率”和“CR 契约符合率”各占 25%与代码交付量同等重要。5.2 流程嵌入让 AI 协同成为团队肌肉记忆的七步法为避免 AI 工具沦为“锦上添花”的玩具我们将其深度嵌入现有研发流程形成七步法需求评审会Requirement Review Coding Agent 工程实践：人机协同生产高质量代码的四象限工作流
1. 这不是“AI写代码”讨论而是工程师在真实战场上的生存实录最近在 Hacker News 上刷到一个标题直击灵魂的提问“Ask HN: Is anybody producing good code with coding agents?”——没有修饰没有 hype就一句赤裸裸的诘问。它背后站着的不是刚学完 LLM 基础课的学生而是每天要交付可上线、可维护、可 debug 的生产级模块的资深开发者不是在 Demo 里跑通 “Hello World” 的研究员而是要在支付链路里加一个风控校验、在物流调度系统里优化路径算法、在医疗影像标注平台里重构数据流水线的工程负责人。我过去三年深度参与过 7 个落地项目其中 4 个把 coding agent 作为核心开发协作者不是玩具不是 PoC覆盖金融中台、工业 IoT 边缘网关、SaaS 客户数据平台CDP和智能硬件固件迭代四个截然不同的技术域。实话讲“good code” 不是语法正确、不是能跑通单元测试、更不是 GitHub Copilot 自动生成的 200 行函数——它是上线后连续 90 天零 P0 故障、是新同事三天内能看懂并安全修改、是审计时能清晰追溯每行逻辑的决策依据、是当原始开发者离职后仍能稳定演进的系统资产。这个标准下目前没有任何 coding agent 能独立产出“good code”但已有明确路径让团队用它批量产出“better code”——提升交付质量、缩短认知负荷、加固知识沉淀。本文不谈论文指标、不列 benchmark 排名、不预测 AGI 何时到来只拆解我在真实产线中验证过的四类典型场景什么时候该让 agent 写写什么怎么审以及——最关键的是当它写出一段看似完美却埋着三处隐性缺陷的代码时你靠什么在合并前把它揪出来。这些经验来自凌晨三点排查因 agent 自动补全导致的时区溢出 bug来自为一段 agent 生成的 Kafka 消费者重写五版异常兜底策略也来自把 agent 当成“永不疲倦的初级工程师”来带教、考核、追责的真实管理实践。2. 核心设计逻辑为什么必须放弃“全自动编码”转向“人机协同增强工作流”2.1 “Good code”的本质是工程契约而非算法输出很多团队踩的第一个坑就是把 coding agent 当成“更高阶的 autocomplete”。他们期待 agent 输入 prompt 就吐出可直接 merge 的 PR结果得到一堆语法无误但违背领域约束的代码比如在银行核心账务系统里agent 生成的余额更新逻辑忽略了幂等性校验或在医疗设备固件中它用浮点运算处理传感器阈值判断——这在嵌入式环境里会因精度漂移引发致命误判。问题根源在于“good code” 的核心不是“是否能运行”而是它承载的工程契约Engineering Contract是否完整兑现。这份契约包含四个不可妥协的维度语义契约Semantic Contract代码行为必须严格符合业务需求文档BRD和领域模型Domain Model。例如“用户注销时需清空所有关联设备授权”不能被简化为“删除 user_devices 表记录”而必须包含设备端主动断连、第三方 token 撤回、审计日志留痕三个子动作。质量契约Quality Contract满足既定 SLO如 API P99 200ms、可观测性要求关键路径打点覆盖率 ≥ 95%、安全基线OWASP Top 10 零高危漏洞。演化契约Evolution Contract代码结构支持未来 6-12 个月的预期变更。比如电商促销引擎的 discount calculation 模块必须预留规则引擎插槽、支持灰度开关、具备降级 fallback 路径而非写成硬编码 if-else。协作契约Collaboration Contract代码具备可读性命名体现意图而非技术实现、可调试性关键分支有 trace id 关联、可交接性复杂逻辑附带 inline 注释说明决策依据而非“why this works”。Coding agent 的当前能力本质上是在“语法空间”里做概率采样而工程契约存在于“语义空间”“质量空间”“演化空间”和“协作空间”的交集。它无法理解“为什么这个风控规则必须在支付前校验而非支付后”也无法感知“这段 Kafka 消费者代码若不加背压控制下游数据库会在大促峰值时被打穿”。因此我的设计原则第一条就是永远不把 agent 当作代码的最终责任方而把它当作一个需要被严格定义输入边界、被持续校验输出质量、被明确分配协作角色的“数字协作者”。2.2 四象限任务筛选法哪些活该交给 agent哪些必须人写基于上述契约观我提炼出一套“四象限任务筛选法”已在团队内部推行两年将 agent 有效使用率从初期的 32% 提升至 89%。筛选依据是两个轴任务确定性Determinism和领域知识密度Domain Knowledge Density。任务类型确定性高确定性低领域知识密度低✅Agent 主力承担- CRUD 接口模板生成含 Swagger 注解、DTO 映射、基础校验- 数据库迁移脚本CREATE TABLE, ADD COLUMN, INDEX 创建- 单元测试桩Mock 外部依赖、构造边界输入- 日志/监控埋点模板按约定格式插入 traceId、metricName⚠️Agent 辅助生成人工强干预- 异常处理流程需人工注入业务兜底策略- 权限校验逻辑需人工映射 RBAC 规则到代码- 缓存失效策略需人工评估一致性要求领域知识密度高❌禁止 agent 参与- 支付对账核心算法涉及多账本平衡、冲正逻辑- 医疗设备实时信号处理FFT 参数、滤波器系数需临床验证- 工业 PLC 控制指令序列安全联锁条件必须物理验证❌绝对禁止- 系统架构决策微服务拆分边界、数据一致性方案- 安全敏感逻辑密码学实现、密钥管理- 合规性关键代码GDPR 数据擦除、HIPAA 审计追踪这个象限的核心洞察是Agent 最擅长处理“规则明确、模式固定、副作用可控”的机械性任务而非“权衡取舍、模糊判断、多方博弈”的创造性任务。举例来说生成一个 Spring Boot Controller 接收 JSON 并保存到 MySQL 的代码其确定性极高HTTP 方法、请求体解析、JPA save领域知识密度极低通用框架语法而决定“订单超时关闭”应该用定时任务扫描还是 Redis 过期监听就涉及系统负载、数据一致性、运维复杂度等多重权衡必须由人决策。我们曾强制要求所有 PR 描述中必须注明该 PR 中 agent 参与的具体任务象限并附上对应的设计决策依据——这倒逼团队建立了清晰的技术决策责任制。2.3 工作流重构从“写代码”到“编排代码生产流水线”一旦接受“agent 是协作者而非替代者”整个开发工作流就必须重构。我们废弃了“开发者写 prompt → agent 输出代码 → 开发者 copy-paste”的原始模式代之以“代码生产流水线Code Production Pipeline”共五个标准化阶段每个阶段都有明确的输入、输出、责任人和准入准出标准需求精炼阶段Requirement Refinement产品经理提供 BRD 后由 Tech Lead 主导将自然语言需求拆解为原子化、可验证的“工程契约条款”。例如“支持用户更换手机号”被拆解为① 新号未被占用校验同步② 旧号绑定设备解绑异步需幂等③ 短信验证码发送与校验含频率限制④ 用户中心数据更新事务性⑤ 第三方推送 token 更新最终一致性。此阶段严禁 agent 参与纯人工。任务委派阶段Task DelegationTech Lead 根据四象限法将条款映射到具体开发任务并明确标注哪些任务可由 agent 承担。例如“① 新号未被占用校验”属于高确定性低领域密度委派给 agent“② 旧号绑定设备解绑”涉及异步可靠性仅委派生成基础消息体和消费者骨架重试逻辑和死信处理由人编写。Prompt 工程与上下文注入阶段Prompt Engineering Context Injection开发者不写泛泛的“写一个校验接口”而是构造结构化 Prompt[ROLE] 你是一个熟悉 Spring Boot 3.x 和 Hibernate 6.x 的资深后端工程师 [CONTEXT] - 项目使用 PostgreSQL已启用 pg_trgm 扩展支持模糊搜索 - 用户表名t_user字段id(BIGINT), mobile_phone(VARCHAR(11)) - 校验需返回 { valid: true/false, reason: xxx } - 必须使用 Transactional(readOnly true) - 必须添加 Operation(summary 校验手机号是否可用) - 错误码统一使用 ErrorCode.MOBILE_ALREADY_EXISTS [TASK] 生成一个 RESTful GET 接口 /api/v1/users/check-mobile?mobile{mobile}返回 JSON关键点Context 必须包含数据库 schema、框架版本、错误码规范、注解要求等硬约束而非业务描述。输出校验与增强阶段Output Validation Enhancement收到 agent 输出后执行三重校验语法校验IDE 自动检查 mvn compile契约校验运行预置的 Checkstyle 规则如禁止 System.out.println、SonarQube 扫描零 blocker 级别漏洞语义校验人工比对 Prompt 中的 Context 条款是否全部满足尤其关注事务注解、错误码、返回结构。此阶段开发者不是“审核代码”而是“验证契约履约”发现缺失项立即补充如 agent 忘了加Transactional人手动补上并记录为 Prompt 缺陷。集成验证与知识沉淀阶段Integration Validation Knowledge Capture代码合并前必须通过完整的集成测试IT和端到端测试E2E。更重要的是将本次 agent 使用过程中的有效 Prompt、校验失败案例、人工增强点沉淀到团队内部的 “Prompt Library” 和 “Agent Pitfall Wiki” 中。例如我们 Wiki 中有一条“当要求 agent 生成带事务的 Service 方法时必须显式声明Transactional否则它默认不加——已复现 17 次”。这套流水线的本质是把 coding agent 从“黑盒代码生成器”变成“可审计、可追溯、可改进的工程组件”。它不追求单次输出完美而追求整个生产过程的确定性和可复现性。3. 实操细节拆解从 Prompt 构造到代码落地的全链路关键控制点3.1 Prompt 不是“提问”而是“工程规格说明书”绝大多数团队用不好 agent 的根本原因在于把 Prompt 当成搜索引擎的 query。真正的 Prompt 工程是撰写一份微型的、面向机器的“工程规格说明书Spec”。它必须包含五个强制要素缺一不可角色定义Role Definition明确 agent 的专业身份和知识边界。错误示例“你很聪明帮我写个登录接口”正确示例“你是一名有 5 年 Spring Security 经验的 Java 工程师熟悉 OAuth2 Resource Server 配置不熟悉前端 Vue 框架”。角色定义框定了 agent 的知识调用范围避免它用 React 思维写后端代码。上下文注入Context Injection提供 agent 做出正确决策所需的全部事实信息。这包括技术栈事实框架版本Spring Boot 3.2.4、数据库类型PostgreSQL 15、中间件Kafka 3.6、云平台AWS EKS项目事实包名规范com.company.product.module、日志框架SLF4J Logback、配置中心Apollo、错误码体系ErrorCode.XXX领域事实业务术语定义“用户”指注册用户“客户”指签约企业“租户”指 SaaS 多租户隔离单元、状态流转规则订单状态CREATED → PAID → SHIPPED → COMPLETED不可逆约束事实性能要求单次查询 50ms、安全要求所有外部输入必须 XSS 过滤、合规要求GDPR 用户数据需加密存储。提示上下文必须是“事实陈述”而非“期望描述”。不说“请确保代码安全”而说“所有字符串参数必须经 org.apache.commons.text.StringEscapeUtils.escapeHtml4() 处理”。任务精确描述Task Precision使用动词宾语限定条件的结构。错误示例“做一个用户管理功能”正确示例“生成一个 RESTful POST 接口 /api/v1/users接收 JSON 格式的 CreateUserRequest含 name:String, email:String, role:Enum[ADMIN,USER]创建用户并返回 201 Created 和 UserResponse含 id, createdAt若 email 已存在返回 400 Bad Request 和 {code:EMAIL_EXISTS,message:邮箱已被注册}”。输出格式规范Output Format Specification明确规定代码的呈现形式。这极大降低后续处理成本。例如[OUTPUT FORMAT] - 仅输出 Java 代码不包含任何解释、注释或 Markdown 代码块标记 - 使用 2 个空格缩进 - 类名首字母大写方法名驼峰常量全大写下划线 - 在类开头添加 // GENERATED BY AGENT: [DATE] 标识 - 不要生成 import 语句假设 IDE 已自动导入拒绝指令Refusal Directive预先设定 agent 的“安全护栏”。例如“如果需求涉及密码明文存储、SQL 拼接、反射调用敏感方法请明确拒绝并说明原因不要尝试生成任何代码”。这能防止 agent 在模糊地带“强行发挥”。我团队内部有一个“Prompt 质量检查清单”每次提交前必须逐项核对。一个高质量 Prompt 的典型长度是 300-500 字远超多数人想象。但实测表明Prompt 每增加 100 字的有效上下文agent 首次输出的契约符合率提升 22%人工返工率下降 35%。3.2 代码审查Code Review的范式转移从“找 Bug”到“验契约”当 agent 成为常规协作者Code Review 的焦点必须从传统的“找语法错误、查潜在 bug”升级为“验证工程契约履约”。我们重构了 CR Checklist核心围绕四大契约维度展开语义契约审查Semantic Contract Review对照 BRD 和需求拆解文档逐条确认代码行为是否 100% 覆盖。例如BRD 要求“用户注销时清除所有设备授权”CR 时必须看到① 设备解绑逻辑② 第三方 token 撤回调用③ 审计日志记录。缺一不可。检查是否有“过度设计”或“设计不足”。前者如为简单查询加入复杂缓存层后者如未对高并发场景做限流保护。注意CR 时禁止说“我觉得这里可以加缓存”而必须说“根据 SLO 要求 P99 200ms当前查询在 10k QPS 下实测为 350ms建议按架构决策文档第 4.2 节添加 Caffeine 缓存”。质量契约审查Quality Contract Review可观测性关键路径是否打点traceId 是否透传错误日志是否包含足够上下文如用户 ID、订单号可测试性是否易于单元测试依赖是否可 Mock是否有隐藏的静态方法调用性能基线数据库查询是否走了索引循环是否可能 O(n²)字符串拼接是否用了 StringBuilder我们要求所有 CR 评论必须引用具体的工具证据如 “EXPLAIN ANALYZE显示此查询未走 idx_user_mobile 索引建议添加 WHERE mobile IS NOT NULL 条件” 或 “JaCoCo 报告显示此方法分支覆盖率仅 65%缺少 null 值处理分支”。演化契约审查Evolution Contract Review扩展性新增功能是否需要修改此模块例如添加新支付方式是否只需新增一个 Strategy 实现而非修改现有 if-else降级能力当依赖服务如短信网关不可用时是否有优雅降级如记录本地队列、异步重试配置化程度硬编码参数如超时时间、重试次数是否已提取为配置中心变量实操心得我们强制要求所有新模块的初始 PR 必须包含一份《演化影响评估》文档说明未来 6 个月最可能的 3 种变更场景以及当前代码如何支持。这倒逼开发者在写第一行代码时就思考演化。协作契约审查Collaboration Contract Review命名意图变量名是否体现业务含义userRiskScore而非技术实现scoreValue注释价值注释是否解释“为什么”Why而非“做什么”What例如// 使用布隆过滤器避免缓存穿透是好注释// 初始化布隆过滤器是废话。交接友好度复杂算法是否有 inline 注释说明数学原理或参考文献关键决策是否有链接到 Confluence 决策记录这套 CR 范式最大的转变是Reviewers 不再是“代码警察”而是“契约守护者”。他们的权威不来自技术资历而来自对工程契约的深刻理解和对团队共识的严格执行。我们甚至将 CR 通过率与 Tech Lead 的绩效挂钩——因为 CR 质量直接决定了代码资产的长期健康度。3.3 人机协同的“增强时刻”哪些环节必须由人深度介入即便在 agent 承担主力任务的流水线中仍有三个“增强时刻Augmentation Moments”必须由资深工程师亲自操刀任何自动化都无法替代异常处理策略设计Exception Handling Strategy DesignAgent 可以生成try-catch块但它无法判断这个异常是应该重试网络超时、降级第三方服务不可用、告警数据库连接池耗尽、还是终止流程业务规则冲突重试应采用指数退避还是固定间隔最大重试次数设为 3 还是 5降级方案是返回缓存数据、默认值还是抛出特定业务异常我们的实践是由人编写异常处理的顶层策略框架如 RetryTemplate 配置、FallbackFactory 实现agent 只负责填充具体业务逻辑。例如人定义“支付回调失败时执行 3 次指数退避重试若仍失败写入死信队列并触发告警”agent 则生成具体的 Kafka 生产者代码和告警通知逻辑。数据一致性保障Data Consistency Assurance在分布式系统中agent 生成的代码往往只考虑单点操作。例如生成“扣减库存”代码时它可能只写inventory - 1而忽略库存扣减与订单创建的事务边界本地事务 or Saga超卖问题的解决方案Redis 原子操作 or 数据库乐观锁库存回滚的补偿机制Saga 的 compensate action。人必须主导设计一致性方案并将方案转化为 agent 可执行的、带明确约束的 Prompt。如“生成一个基于 Redis Lua 脚本的库存扣减方法脚本需保证原子性返回 1 表示成功0 表示库存不足-1 表示脚本执行失败”。安全与合规逻辑植入Security Compliance Logic InjectionAgent 对 OWASP、GDPR、HIPAA 等规范缺乏内在理解。它可能生成一个完美的用户注册接口却忘了密码必须 bcrypt 加盐哈希而非明文存储或弱哈希邮箱验证链接需有时效性JWT exp claim用户数据导出需进行 PII 脱敏姓名、电话、地址。人必须将安全合规要求翻译为可编程的、具体的、不可绕过的代码约束并嵌入到 Prompt 和 CR 流程中。例如我们的 Prompt 强制要求“所有密码字段必须使用 BCryptPasswordEncoder.encode() 处理且盐值长度 ≥ 12”。这三个增强时刻是人机协同的价值高地。它们不追求“减少人力”而追求“将人力聚焦于最高杠杆率的决策点”。数据显示当团队严格执行这三项增强由 agent 生成的代码在生产环境的 P1/P2 故障率下降了 68%安全审计一次性通过率从 41% 提升至 92%。4. 真实战场复盘四个典型故障场景与根因排查实战4.1 场景一时区陷阱——Agent 生成的“完美”时间处理代码引发跨时区资金错账现象某跨境支付系统上线后东南亚地区用户在 23:59 发起的支付部分被记为次日交易导致日结报表金额偏差。P0 级故障影响 3 个区域。Agent 生成代码public LocalDateTime parseTime(String timeStr) { return LocalDateTime.parse(timeStr, DateTimeFormatter.ofPattern(yyyy-MM-dd HH:mm:ss)); }根因分析表面原因LocalDateTime无时区信息解析后存储为服务器本地时区UTC8当查询 UTC 时间的账务流水时发生偏移。深层原因Prompt 中仅要求“解析时间字符串”未明确指定时区上下文“用户所在时区”、“系统统一时区”、“UTC 存储”CR 时 reviewers 仅验证了语法和单元测试用本地时区测试通过未进行跨时区集成测试。排查过程日志溯源在支付失败日志中发现created_at字段值为2024-05-20T23:59:59但数据库存储为2024-05-21T07:59:59UTC8时区比对检查应用服务器时区Asia/Shanghai、数据库时区UTC、Kafka 消息头时区UTC确认不一致代码定位全局搜索LocalDateTime.parse发现 agent 生成的 7 个解析方法均未指定时区契约回溯查阅需求文档发现 BRD 中明确要求“所有时间戳以 UTC 存储”但 Prompt 和 CR 均未体现此约束。修复方案短期强制所有时间解析使用ZonedDateTime.parse(str, formatter).withZoneSameInstant(ZoneOffset.UTC)长期在 Prompt 模板中增加强制条款“所有时间解析必须返回 Instant 或 ZonedDateTime并转换为 UTC 时区”在 CR Checklist 中增加“时区一致性”专项检查经验教训时间处理是领域知识密度高、确定性低的典型任务绝不能交给 agent 全权处理。必须由人定义统一的时区策略UTC 存储、展示时区转换并将其固化为代码生成的硬约束。4.2 场景二资源泄漏——Agent 生成的 Kafka 消费者导致内存持续增长直至 OOM现象某物流轨迹订阅服务上线一周后JVM 堆内存使用率从 40% 持续攀升至 95%GC 频繁最终 OOM。重启后重现。Agent 生成代码KafkaListener(topics tracking-events) public void listen(ConsumerRecordString, String record) { TrackEvent event objectMapper.readValue(record.value(), TrackEvent.class); processEvent(event); }根因分析表面原因objectMapper.readValue()在反序列化大量小对象时频繁创建临时对象且未配置DeserializationFeature.USE_STRING_ARRAY_FOR_JSON_ARRAY等优化参数导致 GC 压力剧增。深层原因Prompt 要求“消费 Kafka 消息并处理”未指定性能要求QPS ≥ 5k、未要求考虑反序列化优化、未要求添加背压控制max.poll.records、fetch.max.wait.msCR 时 reviewers 仅验证了功能正确性未进行压力测试。排查过程JVM 监控通过 Prometheus Grafana 发现jvm_memory_used_bytes{areaheap}持续上升jvm_gc_collection_seconds_count激增堆转储分析使用jmap -dump:formatb,fileheap.hprof pid Eclipse MAT发现com.fasterxml.jackson.databind.deser.std.StringDeserializer相关对象占堆 72%代码审查定位到objectMapper.readValue()调用检查其配置——发现使用默认 ObjectMapper无任何性能优化配置流量模拟用 k6 模拟 10k QPS确认在 5k QPS 时即出现内存泄漏。修复方案短期为 ObjectMapper 添加性能配置mapper.configure(DeserializationFeature.USE_STRING_ARRAY_FOR_JSON_ARRAY, true); mapper.enable(DeserializationFeature.READ_ENUMS_USING_TO_STRING);长期在团队共享的ObjectMapperBean 中强制启用所有已知性能优化在 Prompt 中增加“所有 JSON 反序列化必须使用预配置的Autowired ObjectMapper不得 new ObjectMapper()”经验教训性能敏感型代码高吞吐、低延迟必须由人定义技术选型和配置基线agent 只能在此基线上填充业务逻辑。将“性能要求”作为 Prompt 的强制输入项是避免此类故障的前提。4.3 场景三权限越界——Agent 生成的 Admin API 暴露了普通用户可访问的敏感端点现象安全扫描发现/api/v1/admin/users/export端点未做权限校验任何登录用户均可导出全量用户数据。高危漏洞。Agent 生成代码RestController RequestMapping(/api/v1/admin) public class AdminUserController { GetMapping(/users/export) public ResponseEntitybyte[] exportAllUsers() { ... } }根因分析表面原因Controller 类上有RequestMapping(/api/v1/admin)但方法上未加PreAuthorize(hasRole(ADMIN))深层原因Prompt 中仅描述“管理员导出用户数据”未明确要求“必须进行 RBAC 权限校验”CR 时 reviewers 默认认为“admin 路径即代表 admin 权限”未检查方法级注解。排查过程安全扫描报告Burp Suite 扫描发现该端点响应 200 OK且返回 CSV 数据权限测试用普通用户 Token 访问确认可成功获取数据代码审计全局搜索GetMapping发现所有/admin/**路径下的方法均无PreAuthorize注解流程回溯检查该模块的 Prompt 历史发现初始 Prompt 为“生成一个导出所有用户的接口”完全未提权限。修复方案短期为所有/admin/**方法添加PreAuthorize(hasRole(ADMIN))长期在团队 API 设计规范中强制规定“所有/admin/**路径的 Controller 方法必须显式声明PreAuthorize且 Role 必须为ADMIN”将此规则写入 SonarQube 自定义规则自动拦截未校验的 admin 接口经验教训安全是零容忍领域不存在“大概率安全”。必须将安全要求RBAC、输入校验、输出脱敏作为 Prompt 的强制前置条件并通过自动化工具SonarQube、Checkmarx进行 100% 拦截而非依赖人工 CR。4.4 场景四演化僵化——Agent 生成的“完美”规则引擎因硬编码丧失扩展性现象某营销活动平台上线后运营提出新增“满 300 减 50”优惠券规则开发反馈需 3 天重构因原有规则引擎是 agent 生成的硬编码 if-else。Agent 生成代码public BigDecimal calculateDiscount(Order order) { if (order.getAmount().compareTo(BigDecimal.valueOf(100)) 0) { return BigDecimal.valueOf(10); } else if (order.getAmount().compareTo(BigDecimal.valueOf(200)) 0) { return BigDecimal.valueOf(20); } else if (order.getAmount().compareTo(BigDecimal.valueOf(500)) 0) { return BigDecimal.valueOf(50); } return BigDecimal.ZERO; }根因分析表面原因业务规则被写死在方法中无法动态配置深层原因Prompt 要求“计算订单折扣”未要求“支持动态规则配置”需求拆解阶段Tech Lead 未将“规则可配置化”作为演化契约条款提出CR 时 reviewers 仅验证了计算逻辑正确未评估扩展性。排查过程需求评审会议运营提出新规则开发指出需修改 Java 代码并发布代码审查发现calculateDiscount方法无抽象、无策略接口、无配置加载逻辑架构回顾查阅该模块的《演化影响评估》发现初始文档中未提及“规则动态化”这一关键演化场景修复方案短期紧急重构为策略模式定义DiscountStrategy接口为每种规则实现一个 Strategy 类并从配置中心加载规则配置长期修订需求精炼流程强制要求所有涉及业务规则的功能必须在需求拆解阶段明确“规则来源硬编码/配置中心/规则引擎”和“变更频率月更/周更/实时”并据此选择技术方案经验教训“good code” 的终极考验是它能否支撑业务的快速变化。在需求源头就识别演化需求并将其转化为技术约束是避免“技术债爆炸”的唯一途径。Agent 可以高效实现已知规则但定义规则的可变性必须由人完成。5. 团队落地指南从试点到规模化的人力、流程与文化适配5.1 人力配置重新定义“AI 工程师”的角色与能力模型引入 coding agent 后团队角色并非简单“裁员”而是能力重心的迁移。我们定义了新的岗位能力模型核心是“三懂一强”懂 Prompt 工程懂 Spec能将模糊需求转化为机器可执行的、带完整上下文的工程规格说明书。这不是写作文而是写合同。懂契约审查懂 SLO能基于业务 SLO、质量基线、安全规范、演化要求设计可量化的 CR Checklist并用工具SonarQube, JaCoCo, Prometheus验证。懂领域建模懂 Domain深刻理解业务领域模型、状态流转、核心约束能将领域知识精准注入 Prompt 和 CR 过程。强工程决策强 Decision在技术选型、架构权衡、风险预案等关键节点做出基于数据和经验的果断决策。我们不再招聘“会写 Java 的人”而是招聘“能用 Java 实现领域契约的工程师”。新员工入职培训的第一课不是 Spring Boot 教程而是《如何撰写一份让 agent 100% 理解的 Prompt》和《一次 CR 的完整契约验证流程》。一位 Senior Engineer 的 KPI 中“Prompt 质量提升率”和“CR 契约符合率”各占 25%与代码交付量同等重要。5.2 流程嵌入让 AI 协同成为团队肌肉记忆的七步法为避免 AI 工具沦为“锦上添花”的玩具我们将其深度嵌入现有研发流程形成七步法需求评审会Requirement Review