软件技术部AI Coding落地手册

AI Coding最容易演示的场景，是从零写一个页面或接口。

输入需求，几分钟后代码能跑，现场效果很好。

软件团队真正花时间的地方却不是这个。更多时候，开发人员面对的是一个运行了几年的仓库：历史封装很多，数据库不能随便动，接口有人依赖，测试不完整，线上问题还要能追。

这时真正需要验证的，不是Agent会不会写代码。

而是它能不能在边界内改代码，能不能说清影响，能不能跑完检查，出错以后团队能不能接得住。

先用同一个任务比较工具

国际工具可以评估Claude Code、Codex、Cursor和GitHub Copilot。国内团队可以测试通义灵码、百度 Comate和Trae。

不要让每个人各自选一个Demo比较感受。

准备同一个真实但低风险的任务，例如：给现有查询接口增加一个过滤条件，补齐参数校验和单元测试。让候选工具都完成：

阅读Issue和相关代码；
输出影响范围；
给出修改计划；
修改分支；
运行现有测试；
补充缺失测试；
生成变更说明。

比较计划准确度、无关改动、测试通过率、人工修正时间、中文体验、国内访问、代码数据政策和账号成本。

工具选型不是一次决定。先批准一到两种主工具，避免仓库规则、账号和支持被切得太散。

仓库要先学会“自我介绍”

一个Agent进入陌生仓库，最缺的不是更多代码，而是项目里没有写下来的规矩。

Codex可以读取AGENTS.md，Claude Code可以使用CLAUDE.md。其他工具也可以参考同一份仓库说明。

最小内容可以这样写：

Repository Guide

## Build and test
- Restore: dotnet restore
- Build: dotnet build --no-restore
- Unit tests: dotnet test tests/UnitTests
- Integration tests require the local compose profile.

## Boundaries
- Do not edit generated clients under src/Generated.
- Do not add NuGet packages without approval.
- Database changes must use the existing migration project.
- Never modify production configuration or secrets.

## Completion
- Explain affected modules.
- Run relevant tests.
- Add tests for changed behavior.
- Report unresolved risks and commands executed.

不要把几十页编码规范全塞进去。

先写构建命令、目录边界、现有封装、迁移方式和完成标准。规则太长时，拆成Agent按需读取的项目文档。

把任务分成三个风险等级

不是所有任务都应该给Agent同样权限。

低风险

补测试；
改文档；
小范围重命名；
生成重复映射；
分析日志和调用链。

可以允许Agent在独立分支修改并运行测试。

中风险

修改业务逻辑；
增加接口；
调整数据库查询；
更新依赖；
修改CI配置。

要求先提交计划，开发人员确认后再改。必须通过Review和自动测试。

高风险

数据库破坏性迁移；
权限和身份认证；
支付、合同或安全逻辑；
生产配置；
基础设施删除和生产发布。

Agent只做分析、草稿和验证建议，不直接执行。

任务分级比“允许使用AI”或“禁止使用AI”更容易执行。

一张能交给Agent的任务单

目标：用户连续登录失败5次后锁定30分钟。

范围：身份认证服务和对应测试；不修改前端。

背景：失败次数保存在现有Redis中，日志使用项目封装。

约束：不增加新包，不改变已有Token格式，不修改生产配置。

验收：成功、失败、锁定、过期解锁、并发请求都有测试。

执行：先只读分析；确认计划后创建分支修改；最后列出命令、测试和未解决风险。

任务说不清楚时，Agent通常会替你补一个看起来合理的版本。

所以AI Coding也会反过来暴露团队的需求质量。

Code Review不能只找语法问题

AI适合做第一轮审查，但审查任务要具体。

可以让它检查：

改动是否超出Issue范围；
异常、取消、超时和重试；
并发和幂等；
权限与数据泄露；
日志能否定位失败；
数据库查询和索引影响；
测试是否覆盖改变的行为；
是否绕开项目现有封装。

每条意见需要位置、影响和理由。不要把“建议优化命名”与“可能导致越权”放在同一优先级。

GitHub团队可以测试Copilot的Review能力，也可以使用其他审查工具。无论谁给意见，最终阻止合并的责任仍在代码Owner和Reviewer。

自动发布只能走现有流水线

Agent可以生成或修改GitHub Actions、GitLab CI或Jenkins配置，但不能绕过组织现有审批。

推荐边界：

Agent可以创建分支、提交代码和触发测试环境构建；
CI账号只拥有当前仓库和目标环境需要的最小权限；
数据库迁移先在测试环境验证并备份；
生产发布需要人工批准；
发布后由Sentry、Grafana或现有监控确认错误率和关键指标；
失败时走已有回滚流程，而不是让Agent临时发明一个。

自动发布的价值是减少重复操作，不是取消发布责任。

一开始不要考核生成代码量

两周试点可以选3到5名开发人员、10个低中风险任务，记录：

从领取任务到PR的周期；
人工阅读和修正时间；
测试增加数量及有效性；
Review发现的高风险问题；
无关改动和返工；
CI失败、上线缺陷和回滚；
每人账号和模型成本；
哪些任务类型最适合。

生成行数和聊天次数没有太大意义。

如果PR更快，但Reviewer要花两倍时间清理，团队并没有变快。

最容易踩的几个坑

Agent一次改太多。解决办法是缩小任务、先计划、限制目录。

测试命令写错。把真实命令放进仓库规则，并让CI做最终判断。

把日志、数据库快照或客户代码提交给未经批准的外部服务。上线前明确工具、账号和数据边界。

开发人员不再理解代码，只负责接受。要求任务Owner解释关键改动和失败路径。

每个人保存一套个人规则。把稳定规则放回仓库，跟代码一起Review。

真正值得沉淀的不是某个工具

Claude Code、Codex、Cursor、Copilot和国内编码工具还会继续变化。

更稳定的能力是：仓库有清楚边界，任务能说明目标和验收，测试可以自动执行，Review有风险重点，发布有审批和回滚。

这些东西原本就应该存在。

AI只是让它们的重要性更早暴露出来。

先从一个仓库、几名开发、十个任务开始。工具可以换，工程纪律不要跟着一起换。