编码代理工作流与团队级 AI 开发规范

• 各编码代理的能力边界差异
• 代理型与补全型的区别
• 选型组合方法

当前主流编码代理的能力边界与差异主要体现在"使用模式"与"能力侧重"上：Claude Code、OpenAI Codex 等属于"命令行/自主代理型"，能处理多步任务、操作文件、执行命令、自主完成较完整的开发任务，适合"任务委派式"的开发；Cursor 侧重"IDE 内对话式开发"，在编辑器内提供强大的补全、重构与实时交互，适合"边写边改"的增强式开发；GitHub Copilot 定位是"补全 + 轻量辅助"，内嵌在编辑器与 IDE，低门槛、贴近日常编码。真实能力边界是：所有工具在"目标明确、上下文清晰、可验证"的任务上表现好，在模糊、跨模块、需要领域判断的任务上都需要人工介入。团队选型组合的真实方法是"按任务类型组合而非单选"：用 IDE 内工具（Cursor/Copilot）做日常开发增强，用自主代理（Claude Code/Codex）做批量、机械、可验证的任务，并建立统一的使用规范与评审门禁。关键是"先明确团队任务结构与期望，再选型"，而非追逐最新工具。

编码代理的差异在"使用模式"（IDE 增强 vs 自主执行），选型应按任务类型组合使用，并配套规范与门禁，而非单选某款。

• 完整闭环的环节
• 验收标准
• 人工介入点

从"AI 补全"（单点提示）到"代理执行"（自主完成任务）的转变，需要设计"任务委派-执行-验收-回滚"的完整闭环。设计的核心环节包括：一是任务委派——把任务定义为"目标明确、有验收标准、有边界"的委派，而非模糊指令，让代理知道"做什么、做到什么算好、不要碰什么"；二是执行——代理自主完成任务的实现，可能涉及改文件、跑命令、写测试；三是验收——用可自动化的验收（测试、lint、构建、契约校验）加人工确认来验证代理产出是否符合标准；四是回滚——代理的改动可通过版本控制/分支安全回退，防止坏改动影响主线。人工介入点的设计原则是"在关键决策与最终确认处设人工闸门"：任务定义由人设定、验收标准由人确认、代理产出需人工代码评审、合并前需人工最终确认。真实经验是"人工负责'定义与验收'，代理负责'执行'"，形成"人定标准、代理执行、人验证、可回滚"的闭环，避免无人把关的自主执行。

从补全到代理执行的关键是"人定标准、代理执行、人验收、可回滚"的闭环，人工介入点在任务定义、验收与最终合并处。

• Spec-first 工作流
• 规格粒度
• 验收标准与产出匹配

Spec-first（先写规格再让代理实现）工作流，是"先由人定义清晰的规格（需求/行为/接口），再让代理按规格实现"，以规格作为代理行为的约束与验收依据。真实定义要点包括：一是规格粒度——规格既要"足够明确"让代理理解目标，又不要"过于琐碎"束缚合理实现；通常粒度是"行为/接口/边界"层面（做什么、输入输出、边界、约束），而非"教代理怎么写每一行代码"；二是验收标准——规格要配套可验证的验收标准（测试、断言、契约），让代理产出能否被客观验证，而非"感觉对"；三是产出匹配——规格与产出要能"对得上"，即代理实现的行为/接口与规格一致，通过测试与评审验证。真实经验是：Spec-first 的价值在于"把模糊需求变成可验证的规格"，规格质量直接决定代理产出质量；规格应是"人写的、可验证的、聚焦行为"，代理负责"按规格实现"，这比"让代理边想边做"可靠得多。

Spec-first 的核心是"用可验证规格约束代理"，规格聚焦行为/接口/边界并配套验收标准，让产出可客观匹配与验证。

• 最小授权原则
• 沙箱与隔离
• 企业环境落地

编码代理的权限与沙箱设计，核心是"最小授权"原则：代理只被授予完成其任务所需的最小权限，从而限制其造成破坏或泄露的风险。在文件写入上，应限制代理只能访问与任务相关的目录，禁止/限制写入敏感或非目标目录；在命令执行上，应限制代理可执行的命令（白名单/黑名单），禁止破坏性命令（如 rm、drop、强制部署），并审计命令执行；在网络访问上，应限制代理访问的域名/接口，禁止访问敏感内网或不可信外部地址。落地方式包括：本地用沙箱/容器隔离代理运行环境，限制其进程权限；企业环境用更严格的隔离（专用沙箱、网络策略、账号权限、审计日志），并对代理访问的代码库、依赖、外部资源做管控。真实经验是：权限设计要"默认最小、按需开放、全程审计"，且企业环境要强制合规（不能因代理方便而放开权限），防止"代理权限过大"引入安全与合规风险。

代理权限的核心是"最小授权 + 沙箱隔离 + 审计"，文件、命令、网络都按需最小化，企业环境更要强制合规不放开权限。

• 评审分工的调整
• 质量门禁强化
• 责任边界

当 AI 生成代码占比上升时，代码评审、质量门禁与责任边界需要系统性调整。评审分工上：AI 生成的代码中"机械性、模式化"部分审查负担降低，但评审重心要转向"意图核对、边界验证、架构符合性、潜在幻觉"——审查者要确认 AI 生成代码是否真正符合需求、是否引入无关变更、是否符合项目约束，而非只看语法。质量门禁上：需要强化自动化门禁（更严格的测试覆盖、lint、契约校验、静态分析、AI 检测），因为这些是"可自动验证"的部分，能弥补"人工审查 AI 代码"的疲劳；同时设置"AI 生成代码的额外检查点"（如依赖引入、安全、合规）。责任边界上：尽管代码由 AI 辅助生成，但提交并交付的工程师与团队对最终质量负责，不能以"AI 生成的"免责；要通过评审与门禁确保"AI 加速的同时不引入质量债"。真实经验是"AI 占比越高，越要靠自动化门禁兜底、靠人工聚焦判断、靠责任机制守住质量"。

AI 占比上升时，评审转向意图与边界核对、强化自动化门禁、责任归于提交者，用"自动化兜底 + 人工判断 + 责任机制"防质量债。

• 规范的内容构成
• 建立方法
• 演进维护

团队级 AI 编码规范是让团队"一致、合规、高质量"使用 AI 的规则集，真实内容通常包括：规则文件（明确规定哪些任务可用 AI、哪些必须人工、代码生成后的强制检查）、提示词模板（针对代码评审、测试生成、文档等场景的标准化 Prompt，保证输出质量与一致性）、禁止事项（红线，如禁止上传敏感数据、禁止依赖不可信开源、禁止 AI 直接触碰生产）、灰名单（需要人工确认的边界场景，如安全相关、高影响变更）。建立方法：规范应从团队真实实践与事故教训中提炼，而非凭空编写；先由有经验的成员示范，形成可复用的模板，再沉淀为规范。演进维护：规范要"随项目与技术演进"持续更新——定期评审哪些规则过时、哪些模板需要优化、哪些新风险需要加入，并让规范与代码库、工具配置绑定，保证"规范被实际执行而非摆设"。真实经验是"规范要活、可复用、有形成机制，并随实践迭代"。

团队 AI 规范由规则文件、模板、禁止事项、灰名单构成，建立靠实践提炼，维护靠随项目演进、定期评审、与工具绑定。

• 主动提问 vs 直接执行
• 澄清-确认环节设计
• 往返成本控制

代理工作流的需求澄清，核心是"代理执行前是主动提问还是直接执行"的取舍：主动提问能减少误解、避免返工，但会增加往返次数与延迟；直接执行效率高，但若需求模糊会导致错误方向与返工。真实的取舍是"按不确定性分情况"——当任务高风险、模糊、关键时，代理应主动提问澄清；当任务低风险、明确、可验证时，代理可直接执行。团队设计"澄清-确认"环节的方法包括：定义"哪些情况必须澄清"（如任务描述含歧义、涉及破坏性变更、跨模块影响、验收标准不明确）、在规格中预置澄清点、让代理在执行前用"确认清单"与人对齐。控制往返成本的关键是"把澄清前置、批量、结构化"——在委派时就尽量提供完整的上下文与验收标准，减少执行中的反复提问；把"澄清"做成一次性的"确认清单"而非零散多次提问。真实经验是"好规格好上下文能大幅减少澄清往返，澄清应聚焦高风险点而非琐碎细节"。

澄清与直接执行的取舍按不确定性分情况，用"确认清单"设计澄清环节，并通过前置完整规格控制往返成本。

• DORA 悖论的成因
• 稳定性的度量指标
• 用指标防质量债

DORA 报告揭示的悖论是：AI 提升了部署/交付吞吐（更快的代码产出与交付），但可能同时增加不稳定性（如变更失败率升高、回滚增多），因为 AI 加速了"产出"却没同步加速"质量保障"。真实成因是"AI 提升的是产出速度，而稳定性取决于质量与验证"，若门禁与评审没跟上，AI 产出的低质量代码会加速引入质量债。团队用指标防止质量债的方法包括：一是持续监控稳定性指标——变更失败率（Change Failure Rate）、回滚率/回滚频率、恢复时间（MTTR）、部署频率，把它们与 AI 使用量关联观察；二是"吞吐与稳定并重"——不仅看"AI 提升了多少交付"，还要看"变更失败率是否上升、回滚是否增多"，若 AI 加速的同时稳定性下降，说明质量债在累积；三是建立质量门禁——用测试、审查、CI 验证保证 AI 产出质量，让"吞吐提升"不以"稳定性下降"为代价。真实经验是"用稳定性指标作为 AI 收益的校验"，防止被"吞吐提升"的表面数字掩盖质量债。

DORA 悖论的本质是"吞吐提升≠质量提升"，用变更失败率、回滚率等稳定性指标监控并与 AI 使用关联，防止 AI 加速引入质量债。

• 并行代理的成本结构
• 值得并行的任务
• 必须人工把关的任务

并行代理（多任务并发）与串行人工审查的成本结构权衡，核心是"哪些任务放给代理并行能省成本、哪些必须人工把关"。值得并行的任务特征：互相独立、目标明确、可自动验证、低风险、彼此无共享写冲突——如为多个独立模块生成测试、批量修复同类问题、生成文档、分析多个独立文件，这类任务并行能显著提升吞吐、降低等待成本。必须人工把关的任务特征：高风险、跨模块耦合、模糊、涉及架构与业务判断、破坏性变更、影响生产——如生产部署、关键接口变更、架构决策、安全相关改动，这些必须人工审查与决策，不能并行放权。真实成本结构是"并行代理的边际成本低（多任务几乎同时完成），但人工审查是瓶颈且昂贵"，因此应"把可并行的机械化任务交给代理并行，把高价值判断保留给人工串行把关"，形成"代理并行干活 + 人工聚焦关键审核"的组合。

并行代理适合"独立、明确、可验证、低风险"任务，人工把关适合"高风险、跨模块、需判断"任务，按任务性质分配成本结构。

• 测试优先原则
• 代理的测试约束
• CI 门禁验收

代理开发中的测试策略，是要求代理"先写测试（作为规格）再实现"，并用 CI 门禁验收，从而用可执行测试约束代理产出、防止幻觉。真实执行方法包括：一是"测试优先"——在委派任务时要求代理先基于规格编写测试（定义行为的预期），再实现功能让测试通过，让测试成为可验证的验收标准；二是"测试先行 + CI 门禁"——把代理产出的测试与实现纳入 CI，设置"测试必须通过、覆盖达标"的门禁，未通过则不能合并，从而自动验收代理产出；三是"防止假测试"——评审代理写的测试是否真的验证了行为（而非"为覆盖而覆盖"），确保测试断言有效。真实经验是：测试优先对代理尤其有效，因为"可运行测试"是代理最可靠的行为约束，比文字规格更能防止离题；但需要人工评审测试质量，避免代理生成"空测试"或"假通过"测试。落地是"委派时要求测试优先、CI 门禁强制验收、人工评审测试有效性"。

代理测试策略的核心是"测试优先约束 + CI 门禁验收 + 人工评审测试质量"，用可执行测试防止代理幻觉与假通过。

• 长任务的上下文限制
• 分段委派与检查点
• 进度可视化与续跑

长任务代理的上下文管理，解决的是"大型重构/迁移超出一轮代理上下文容量"的问题。真实方法包括：一是"分段委派"——把大型任务拆成多个小任务分段交给代理，每段有独立目标与验收，避免一次塞入过多上下文导致代理"顾此失彼"或丢失早期信息；二是"设置检查点"——每个分段完成后作为检查点，记录进度、验证成果、保存状态，可在此处暂停、续跑或回退，防止"一错到底"；三是"续跑机制"——通过保存的任务上下文/进度清单，让代理在分段之间能继承之前的结果继续推进，而不是每次从头开始；四是"进度可视化"——用任务清单、检查点状态、变更记录让团队/代理看到"进行到哪、还剩什么、哪些已完成"，便于监控与干预。真实经验是"长任务要分段化、检查点化、可续跑、可可视化"，用"小步快跑"降低单次上下文的承载压力，避免长任务的质量失控。

长任务代理管理的核心是"分段委派 + 检查点 + 续跑 + 可视化"，用小步快跑与可恢复机制应对上下文容量限制。

• 代理的供应链风险
• 依赖与规则文件风险
• 供应链安全检查

编码代理引入的供应链风险，指代理在运行中可能拉取依赖、规则文件、第三方工具与代码，这些来源若不可信，会引入恶意代码、漏洞、许可证或合规风险。真实风险点包括：代理自动安装的依赖（可能来自恶意包）、代理参考/生成的规则文件与模板（可能被投毒）、代理调用的第三方工具与 API（可能泄露或不可信）。纳入供应链安全检查的方法包括：一是依赖扫描——对代理引入的依赖做 SCA（软件成分分析）扫描漏洞与许可证，纳入供应链安全审查；二是来源管控——约束代理可拉取的依赖源与规则文件来源（白名单私有源、可信仓库），禁止从不可信来源拉取；三是规则与模板审查——对代理使用的规则文件、提示词模板做版本管理与评审，防止被篡改；四是隔离与审计——把代理运行在受控环境，审计其网络访问与拉取行为，发现异常。真实经验是"把代理当作供应链的一环，纳入依赖、来源、规则、审计的管控"，而不是信任代理拉取的一切。

代理供应链风险源于"拉取内容不可信"，需用依赖扫描、来源管控、规则审查与运行审计纳入供应链安全体系。

• 度量指标的含义
• 组合评估 ROI
• 防作弊

代理工具的度量，需要组合多种指标才能真实评估 ROI，单一指标易被误导。核心指标含义：采纳率（团队多少人/多少场景使用 AI）、接受率（AI 建议被接受的比例，反映建议质量）、任务完成率（代理自主完成任务的比例，反映代理能力）、人工修正率（AI 产出中需要人工修改的比例，反映产出质量）。真实 ROI 评估方法：要把这些指标"组合"着看——高接受率+低修正率说明产出质量高，高完成率+低返工说明代理真实有效；反之"高产出但高修正率/高返工"说明是"虚假生产力"。指标防作弊的方法包括：避免只看"生成量/接受率"这类可被刷的指标，关注"最终被采纳、被保留、带来真实交付"的成果；用"人工修正率、返工率、上线后缺陷率"来校正"AI 用了多少"与"AI 带来多少价值"的差距；对"完成率"要区分"真完成"与"假完成"（是否通过验收、是否被采纳）。真实经验是"用成果指标（修正率、返工、缺陷）校正活动指标（采纳、接受），组合评估 ROI 并防作弊"。

代理 ROI 评估要"组合活动指标与成果指标"，用修正率、返工、缺陷校正采纳/接受率，防止用表面数字虚报收益。

• AI 依赖的风险
• 基础能力建设
• 练习与委托的比例

新手工程师在代理时代面临的核心风险是"AI 依赖"——过度依赖 AI 导致失去基础能力（读代码、写算法、调试、理解系统、设计）。真实学习路径建议包括：一是"先练后托"——在成为熟练者之前，先通过无 AI 的刻意练习建立基础能力（手写解决典型问题、手动调试、手动理解代码），再逐步引入 AI 辅助；二是"用 AI 验证而非替代"——用 AI 生成后要能理解、验证、修正，把 AI 当作"检查者"而非"代写者"，确保自己能独立理解产出；三是"控制比例"——练习与委托的比例没有固定数，但原则是"基础能力成形前多练习、少委托"，能力成形后可按需委托，同时保留"脱离 AI 也能交付"的能力兜底。四是"攻坚不代写"——新手在遇到难题时先自己尝试，再让 AI 辅助对照，避免"直接让 AI 做完"而跳过思考。真实经验是"防止 AI 依赖要主动练习、用 AI 验证而非替代、先练后托、保底能力"，比例随能力成长动态调整。

防止 AI 依赖的核心是"先练后托、用 AI 验证而非替代、保住脱离 AI 的基础能力"，比例随能力成长动态调整。

• 代理的常见失败模式
• 失败模式的记录
• 沉淀为团队经验

编码代理的失败模式库，是"把代理常见的错误类型记录、归类、沉淀为团队可复用的经验"，帮助团队识别、预防与快速处理代理失败。常见的代理失败模式包括：幻觉 API（调用不存在的接口/方法）、破坏性命令（执行删除、强制部署等危险命令）、过度重构（把不该改的代码也改了）、越界修改（改动超出任务范围的文件）、上下文丢失（长任务中途偏离目标）、假完成（看似完成但实际未通过验收）。沉淀为团队经验的方法包括：一是"记录案例"——把每次代理失败（现象、成因、如何发现、如何修复）记录到失败模式库；二是"归类与模式化"——把相似失败归纳为可识别的模式，并给出"识别信号 + 预防措施 + 处理方式"；三是"反馈到规范"——把高频失败模式转化为禁止事项、检查清单或门禁规则（如禁止破坏性命令、检查幻觉 API），在规范与工具层面预防；四是"培训与分享"——让团队共享失败案例，提高每个人的识别能力。真实经验是"失败模式库要'记录、归类、反馈到规范、培训共享'，让代理的失败变成团队的资产而非个别教训"。

失败模式库通过"记录案例、归类模式、反馈到规范、培训共享"沉淀经验，把代理的常见失败转化为可预防的团队资产。

• 索引与检索的机制
• 索引质量对任务的影响
• 维护"代理可读"代码库

代码库索引与语义检索，是让代理能"找到相关代码"的关键机制，其质量直接影响代理任务成功率。索引配置与忽略规则的影响：索引配置（哪些文件被索引、语义切分粒度）决定了代理能看到什么；忽略规则（哪些文件被排除，如构建产物、第三方、敏感文件）决定了代理不会看到什么；若索引不完整或忽略规则不当，代理会"找不到相关代码"或"看到无关/敏感内容"，导致任务失败或越界。真实维护"代理可读"代码库的方法包括：一是"配置合理的索引与忽略规则"——明确索引范围、排除无关/敏感文件，让代理聚焦真实代码；二是"保持代码结构清晰"——良好命名、明确模块边界、减少重复与死代码，让语义检索更准；三是"维护项目级上下文"——提供 README、架构说明、接口文档，帮助代理理解整体；四是"监控检索质量"——观察代理是否总是找不到相关代码，据此调优索引与忽略规则。真实经验是"代理可读的代码库 = 清晰的结构 + 合理的索引/忽略规则 + 足够的上下文文档"，团队要像维护"人可读"一样维护"代理可读"。

代理任务成功率依赖索引与检索质量，维护"代理可读"代码库需配置索引/忽略规则、保持结构清晰、提供上下文并监控检索质量。

• 生成代码的溯源
• 许可证检查
• 合规红线设定

AI 生成代码的溯源合规，针对的是"模型输出可能包含训练自开源代码的片段，且来源不明"的合规风险。真实做法包括：一是来源追溯——通过工具的溯源能力（部分模型/工具能标注输出中与已知代码相似的部分）、相似度扫描、人工比对，识别生成代码中可能来自开源项目的片段；二是许可证检查——对识别出的来源做许可证合规评估，判断是否引入 copyleft 等强义务，并对生成代码做依赖/许可证扫描；三是合规红线设定——企业建立"生成物的合规红线"，例如：禁止生成强 copyleft（如 GPL）代码进入核心产品、禁止使用无法溯源且可能含专有代码的生成物、对高风险生成代码强制人工审查与许可证评估、规定敏感项目禁止上传源代码给外部 AI。真实经验是"生成物的溯源与许可证检查要纳入评审门禁，并设明确红线，避免'用起来才知道有合规风险'"。核心是"承认生成物可能有未标注来源，用溯源+检查+红线主动管控"。

生成代码溯源合规靠"来源追溯 + 许可证检查 + 合规红线"主动管控，承认输出可能携带未标注来源，用门禁与红线预防风险。

• 本地与云端的数据安全
• 成本构成
• 能力差异

本地模型代理（私有化）与云端代理的选型边界，核心是"数据安全、成本与能力"三者的权衡。数据安全上：本地模型数据不出域，能严格满足敏感数据、合规与保密要求，适合处理私有代码、PII、金融/医疗等敏感领域；云端代理需要把数据上传到厂商，存在数据外泄与合规风险，但自有模型规模大、能力更强。成本上：本地模型需要自建/租用算力基础设施，前期投入高、运维成本高，但可控制长期成本与数据隐私；云端代理按使用付费、起步成本低、免运维，但长期高频使用成本可能累积，且受厂商定价影响。能力上：云端大模型通常能力更强（理解、代码生成质量更高），本地模型能力受限于自建模型规模与算力，但通过与私有代码库训练可增强领域适配。真实选型边界是：敏感数据/合规要求高 → 本地模型；追求能力与低运维、数据不敏感 → 云端；需在"本地模型的能力与成本/云端的数据安全"之间做混合与权衡，常见做法是"按数据敏感度分层，敏感数据走本地、非敏感走云端"。

本地 vs 云端的选型是"数据安全、成本、能力"的三角权衡，敏感数据走本地、追求能力与低运维走云端，可按数据敏感度分层混合。

• 技能重点的迁移
• 考核标准变化
• 晋升依据变化

代理时代的岗位技能迁移，指工程师的核心竞争力从"写代码"向"审代码 + 定义任务 + 理解系统"迁移。变化体现在：一是技能重点——"手写代码"的机械性要求下降，而"定义任务（把需求转化为清晰可委派的规格）、审查 AI 产出（识别幻觉、验证正确性）、理解系统与业务（判断设计与架构）"的价值上升；二是考核标准——从"你写了多少/多好"转向"你定义的任务是否准确、你审查的产出是否可靠、你能否把控 AI 产出的质量与边界"，度量从"产出量"转向"决策质量与交付可靠性"；三是晋升依据——更看重"能否驾驭 AI 提升团队交付质量、能否设计高质量任务与验收、能否守住架构与质量底线"，而非单纯"个人编码速度"。真实经验是"代理时代，会定义任务、会审查、懂系统与业务的人更有价值"，考核与晋升要转向这些高阶能力，同时避免"AI 依赖"导致基础能力缺失的反向风险。

代理时代技能迁移的核心是"从写代码到定义任务、审查产出、理解系统"，考核与晋升依据转向决策质量与交付可靠性。

• 代理与 CI/CD 集成闭环
• 自修复机制
• 人工闸门保留

代理与 CI/CD 集成，是让代理"自动提交 PR、根据流水线反馈自修复"的闭环，设计核心是"自动化执行 + 人工闸门把关"。闭环设计包括：一是"自动提交 PR"——代理完成改动后自动创建 PR，关联任务与描述；二是"流水线反馈自修复"——CI 跑测试/lint/构建，若失败，代理基于失败反馈自动定位并修复，再重新提交，形成"提交-反馈-修复"循环；三是"质量门禁"——CI 中设置测试、覆盖、lint、安全等门禁，未通过不能合并。必须保留人工闸门的环节包括：PR 代码评审（人工确认意图、架构与质量，尤其是高影响/高风险变更）、合并决策（最终合并须人工确认，不能自动合并）、涉及生产/数据/架构的关键变更（必须人工把关）、以及"自修复"的边界（防止代理无限循环修复或强行绕过门禁）。真实经验是"自动化负责效率，人工负责关键判断"，闭环要"能自动提交修复、但关键门禁人工把关"，避免无人监控的"全自动合代码"带来风险。

代理与 CI/CD 闭环是"自动提交-反馈-自修复 + 人工闸门"，自动化提升效率，但 PR 评审、合并、关键变更必须保留人工把关。