从任务分级到知识沉淀，一套可复用的 AI 辅助研发标准化体系
随着 AI 编程工具的普及，"用 AI 写代码"早已不是难题，但如何让 AI 稳定地产出符合团队规范、边界可控、质量可验收的代码，如何平衡效率与风险，却是绝大多数团队正在面对的共性痛点。
我们团队在 iOS 业务迭代中，围绕"人做决策、AI 做执行"的核心思路，搭建了一套完整的人机协作工作流。从任务分级、输入规范，到实现自检、验证闸门，再到代码审查、知识沉淀，形成了完整的闭环。本文将完整拆解这套工作流的设计逻辑与落地细节，供同类团队参考。
一、核心原则：先划清人与 AI 的权责边界
所有流程设计的前提，是先明确人和 AI 各自的定位，避免权责模糊带来的质量失控。我们定下三条总原则：
- 人负责「定义 + 验收 + 合入」，AI 负责「调研 + 实现 + 自检」 需求的业务意图、改动边界、最终是否合入代码库，必须由人来决策；所有 commit 与 push 操作永远由人触发，AI 不获得代码库的直接写入权限。这是守住代码库安全的底线。
- 规范是唯一真源 AI 犯下的、具备复用性的错误，必须当周沉淀回团队开发规范文档，而不是散落在聊天记录里。只有写进规范的规则，才是 AI 可以稳定遵守的规则；反复在对话里纠正，本质是低效的重复劳动。
- 证据优先于结论 "应该没问题""自测过了"不视为完成。所有交付必须附带可复现的证据：构建命令输出、真机/模拟器截图、产物 plist 校验结果、接口返回样本等。无实证的交付，直接打回。
二、任务分级：按复杂度匹配流程，平衡效率与风险
不是所有任务都要走完整的重型流程。我们按改动范围、风险等级将任务分为 4 级，不同级别对应不同的流程链路与交付产物，兼顾小改动的效率和大改动的质量。
| 任务级别 | 典型场景 | 执行流程 | 必备交付产物 |
|---|---|---|---|
| S 级（小改） | 文案修正、色值/间距调整、单文件简单 Bug 修复 | 对话内直接修改 + Debug 环境构建验证 | 无，人工自查 diff 即可 |
| M 级（常规） | 单页面功能开发、组件样式重构、单一模块逻辑迭代 | 方案计划 → 代码实现 → 独立 AI 审查（1~2 轮） | plan.md、verification.md、review.json |
| L 级（重型） | 跨模块重构、三方库替换、缓存/网络链路改造 | 技术调研 → 方案评审 → 开发计划 → 实现+审查循环 → 验证门 | 新增 report.md（调研报告）、技术方案/设计稿 |
| 只读型 | 接口字段核对、问题根因定位、兼容性调研 | 只读调查（investigate） | report.md |
强制提级规则：拿不准级别就往上提一级。凡是涉及工程配置（pbxproj/xcconfig）、依赖管理（Podfile）、签名配置、Info.plist 权限变更的改动，一律至少按 M 级处理，且实施前必须先由人确认。
三、标准化任务载体：固定目录与产物约定
所有 AI 执行的任务，统一放在 .agents/tasks/<任务名>/ 目录下管理，用统一的文件结构承载全流程产出，避免信息散落在各处。
1. 目录命名规则
采用「模块-意图」的短横线命名法，例如 shelf-edit-nomore、home-auto-retry-once。同一主题的迭代优化，在同一目录下新增前缀文件，不随意新建目录，保证上下文的连续性。
2. 固定文件职责
每个任务的产物文件职责严格固定，AI 必须按模板输出，审查者无需额外理解成本：
- plan.md：任务目标、改动文件清单、明确不做的范围、可量化的验收标准、需验证的环境
- report.md：调研结论、接口实测结果、踩坑点（同时同步回代码注释）
- verification.md：构建命令与结果、截图路径、功能开启/关闭双方向的实测记录
- review.md + review.json：结构化审查结果，包含结论（通过/驳回）与问题清单
3. 关键细节约定
- 非阻断性问题（如"其余关联页面未进行目测验证"）必须明确写入交付说明，不能被"审查通过"的结论掩盖，保证信息透明。
- 接口样本 JSON、测试截图、临时取样代码，全部放在任务目录内（已加入 gitignore），任务完成后取样代码必须清理干净，不流入主分支。
四、高质量输入：给 AI 的任务简报怎么写
AI 产出的质量上限，由输入的质量决定。一份模糊的"优化一下"，只会得到一份敷衍的结果。我们要求所有给 AI 的任务简报，必须包含以下要素：
- 可判定的完成标准 用可量化、无歧义的语言描述目标。例如"阅读页空态推荐卡片的宽高与设计稿完全一致"，而不是"优化一下空态样式"。
- 明确的代码起点与参考实现 给出改动文件的绝对路径，以及团队内的同类参考实现（如某指定页面控制器、某通用 Cell），让 AI 直接对标现有代码风格，减少风格不一致的问题。
- 指定适用的规范章节 明确标注需要遵守的规范编号（如"遵守失败分支处理规范、稀疏目录规范"），让 AI 先读取对应章节再开始编码，避免事后返工。
- 清晰写出「不做什么」 明确边界：不顺手重构无关代码、不新增三方依赖、不改动 Pods 与无关工程配置。这是防止 AI"过度发挥"、改动越界的最有效手段。
- 完整的参考素材 有设计稿就附高清设计图，有接口就附解密后的真实返回 JSON，禁止让 AI 按接口文档猜测字段结构。
- 功能开关约定 新功能必须明确开关名称，默认值为关闭，遵循"灰度先行"的迭代原则。
五、实现自检：把编码规范变成 AI 可执行的核对项
我们将团队沉淀的 iOS 编码规范，提炼成 AI 实现后必须逐条自检的清单，从源头减少低级错误，降低后续审查成本。
基础规范类
- 统一前缀：新增 Swift 文件与主类型使用统一业务前缀，资源文件使用统一前缀，避免符号与资源冲突。
- 零字面量原则：颜色、字体、间距、尺寸、文案、图片，全部调用团队设计系统封装的统一类，业务代码中禁止出现硬编码色值、字号、数字与文案。
- 布局规范：自动布局统一使用语义化属性，禁止使用绝对左右边距与全屏边距简写，保障 RTL 语言适配一致性。
功能完整性类
- 页面三态齐全：所有列表与内容页必须覆盖加载态、空态、失败态；上拉加载失败统一调用全局封装方法；过期缓存数据按版本号自动丢弃。
- 安全编码约束 ：禁止强制解包、禁止
try!；异步闭包统一添加弱引用；禁止裸print调试语句，日志统一走埋点框架。 - 分层架构遵守：页面跳转统一走路由层，面板数据统一走仓储层，禁止业务侧直接跨模块跳转、直接读写本地存储。
专项校验类
- 带功能开关的功能，必须附带"关闭态零行为变化"核对清单，确保开关关闭时对现有逻辑无任何侵入。
- 涉及排版度量改动的任务，必须提交分页指纹对照结果，验证分页逻辑未发生非预期变化。
六、验证闸门：机械校验前置，节省人工审查成本
代码提交审查前，必须先通过"验证门"检查。把机械、可自动化的校验全部前置，没过验证门的任务不进入审查环节，把人的精力从重复核对中解放出来。
-
构建环境校验 先确认 Xcode 命令行工具路径正确，环境异常则先修正开发环境，再执行构建。
-
构建产物校验 默认使用 Debug 开发环境构建，要求 0 error，且新增代码 0 warning。
- 若改动了调试宏、环境分支逻辑，必须追加 Release 生产环境构建验证；
- 若改动了构建配置、Bundle ID、应用显示名、依赖配置、Scheme 模板，必须四个环境全部构建通过，并通过
plutil工具核对产物 Info.plist 的关键值。
-
UI 变更验证 涉及 UI 改动的任务，必须提供模拟器截图并存入任务目录，与设计稿进行对比；未进行目测验证的页面，必须明确标注"未目测"，不隐瞒验证范围。
-
干净态断言 通过 grep 等命令做配置合规性检查：例如工程文件中禁止出现某类冗余配置、Info.plist 中禁止硬编码界面风格与状态栏样式等，确保工程配置的干净与统一。
七、双轮审查：AI 独立交叉审查 + 人工终审
我们采用"AI 初审 + 人终审"的审查模式，既利用 AI 提升审查效率，又守住最终质量底线。
AI 独立审查规则
- 审查 AI 与实现 AI 使用不同的会话、优先使用不同的模型，审查方只读 diff、计划文档与团队规范，不读取实现方的自评内容，保证审查视角的独立性。
- 审查迭代上限为 2 轮。若 2 轮后仍存在阻断性问题，停止 AI 迭代，转由人工决策处理，避免无意义的反复修改消耗资源。
人工终审的三个核心关注点
人不做机械的规则检查（这部分交给 AI 与钩子），只做三件最有价值的判断：
- 改动是否符合需求的业务原意；
- 是否存在越界改动、超出任务范围的修改；
- 交付的验证证据是否真实、可复现。
高风险域强制人工兜底：网络请求、加解密逻辑、缓存删除逻辑、账号级数据存储、工程配置文件，人必须逐行审查，不将核心安全风险交给 AI 判断。
八、提交合入：守住代码库的最后一道关
- 合入操作流程 只有人发出"push"指令后，才按标准流程执行：暂存本地改动 → 拉取最新代码并变基 → 执行构建验证 → 推送分支 → 恢复本地暂存。
- Commit 规范 采用
type(scope): 中文描述的格式，一个 commit 只做一件事，精确git add指定文件，禁止无脑git add .。 - 前置钩子约束 团队统一启用 pre-commit 钩子，提交前自动执行静态检查，不符合规范的代码在本地就被拦截。
- MR 模板自动生成 合并请求的四项核心内容（改动内容、影响范围、测试方法、回滚方案），直接从 plan.md 与 verification.md 中提取生成，保证信息完整且格式统一。
九、知识沉淀：让 AI 协作的效率持续复利
AI 协作的长期价值，不在于单次任务省了多少时间，而在于通过持续沉淀，让整个团队的规范越来越完善，AI 犯重复错误的概率越来越低。
- 踩坑即时反哺规范 每个任务收尾时，必须复盘：本次有没有"规范没写明、AI 踩了坑"的问题？如果有，就提交一条规范更新 PR。我们很多实用的边界规则（如某些系统 API 的闪退坑、容器控制器的添加时机问题），都是通过这种方式沉淀下来的。
- 定期归档与提炼 每月清理一次任务目录：已合入且无复用价值的任务归档处理；高频被参考的结论与方案，直接提炼进规范文档，避免 AI 去读取过时的历史报告。
- 规范的迭代原则 规范只补充、不乱改，每条新规则必须写清"为什么"和"实测依据"。AI 更愿意遵守有明确理由的规则，无理由的禁令只会被频繁突破。
十、未来方向：从"流程化"到"自动化"
目前这套流程仍以"人引导、AI 执行"为主，我们正在推进进一步的自动化升级：
- 静态扫描前置：在 pre-commit 与 AI 工具调用前置阶段，自动扫描 diff 中的违规写法（如直接调用系统图片方法、硬编码色值、禁用布局属性、调试语句等），实时拦截。
- 自检规则内置化：把实现自检、验证门的规则，写入 AI 代理的 steering 配置，实现类任务自动加载校验规则，无需人工反复提醒。
- 工作流配方封装：把常用流程封装成标准化工作流配方，例如「功能开发流」「问题调研流」，一键启动即可按步骤执行，进一步降低流程使用成本。
十一、写在最后
团队节奏：
- 早上人集中写/审当天的任务简报，把问题定义清楚；
- 白天并行推进 2~3 个 M 级任务，人在固定时段批量做审查与决策；
- 下班前完成合入与当日的规范沉淀。
我们度量产出的标准，是交付质量与线上事故率，而不是 PR 数量、代码行数。
AI 时代的研发效能提升，核心从来不是"AI 有多能写代码"，而是团队能否把自己的隐性经验、质量标准、工程约束，显性化、标准化、流程化，最终通过工具固化下来。
好的人机协作，从来不是用 AI 替代人，而是把人从重复、机械的劳动里解放出来，让人更专注于决策、设计与创造------这才是技术人最核心的价值。