页集

AI 编码系统质量把控体系

返回文档库
工程治理 · 质量门禁 · AI Coding

Codex、Claude Code 等开发系统的质量把控体系

建立一套独立于模型能力的工程控制系统，让 AI 可以高效生成代码，但无法绕过需求、测试、安全、审核和发布门禁。

文档版本：1.0 适用对象：研发团队 / 独立开发者 更新：2026.07.28
核心原则：把 Codex、Claude Code 当作“高产但不可信的开发者”。允许它写代码，不允许它自行证明自己正确，更不允许直接合并和发布。
没有找到匹配内容，请尝试更换关键词。
01

整体思路

从需求到线上运行建立完整、独立、可追溯的质量链路。

⌄

Codex、Claude Code 等智能编码工具的质量控制，不能只依赖提示词，也不能只依赖模型的自我检查。真正有效的方式，是建立一套独立于模型的工程体系。

需求可验证
→
权限受约束
→
自动化检查
→
独立复核
→
人工批准
→
灰度发布
→
线上反馈
AI 可以写代码

但不能直接提交到主分支，也不能绕过 Pull Request。

AI 可以写测试

但不能仅凭自己编写的测试证明实现正确。

说明不是证据

以测试报告、扫描报告、构建结果和运行指标为准。

门禁不可自行修改

AI 不得降低覆盖率、关闭检查或修改审批规则。

02

需求门禁：先让任务可验证

质量控制的起点不是代码，而是清晰、可执行的验收标准。

⌄

不要直接向 AI 下达模糊任务，例如“做一个用户登录系统”。应使用结构化任务单：

任务规范示例 · Markdown 
# 任务目标
实现邮箱和密码登录。

# 不在本次范围
- 手机号登录
- 第三方 OAuth
- 找回密码

# 验收标准
1. 正确账号密码可以登录
2. 错误密码返回统一错误信息
3. 连续失败 5 次后限制登录
4. 密码不得写入日志
5. 登录接口 P95 响应时间低于 500ms

# 允许修改范围
- src/auth/**
- tests/auth/**

# 禁止修改范围
- 数据库公共配置
- CI 配置
- 权限中间件
- 生产环境变量

# 必须执行
- 单元测试
- 接口集成测试
- 类型检查
- 安全扫描

每个任务至少应包含

  • 任务目标与业务价值
  • 明确的不在范围内容
  • 可执行的验收条件
  • 允许和禁止修改的目录
  • 风险等级与审批人
  • 测试、部署和回滚要求
03

规则门禁：统一 AI 开发规范

让不同编码代理遵循一致的项目约束和交付格式。

⌄

建议在项目根目录同时维护以下规则文件：

项目规则文件 
AGENTS.md
CLAUDE.md
规则内容示例 · Markdown 
# 开发流程

1. 修改代码前先输出实施计划。
2. 未明确验收标准时，不得开始实现。
3. 每次任务只解决一个问题。
4. 禁止直接修改 main 分支。
5. 禁止使用 --force、reset --hard 和跳过检查参数。
6. 禁止读取或输出 .env、密钥和生产凭据。
7. 不得删除现有测试来让 CI 通过。
8. 不得降低覆盖率阈值。
9. 新增生产依赖必须说明原因。
10. 修改完成后必须执行：
   - lint
   - typecheck
   - unit test
   - integration test
   - build

# 输出要求

完成任务后必须提供：
- 修改文件列表
- 实现内容
- 测试命令和结果
- 未解决风险
- 回滚方式
注意： AGENTS.md 和 CLAUDE.md 是行为指导，不是绝对安全边界。无法违反的规则必须放在 CI、Hook、分支保护、文件权限和审批系统中。
04

权限门禁：限制 AI 能做什么

使用最小权限、临时凭据和隔离环境控制 AI 的操作边界。

⌄
操作 默认权限 控制建议
读取项目代码 允许 排除密钥、生产配置和敏感数据目录
修改当前任务目录 允许 通过路径白名单控制
修改其他目录 需要审批 触发 Hook 或 CI 阻断
安装生产依赖 人工审批 记录原因、许可证和漏洞信息
读取 .env 禁止 使用临时测试凭据
修改 CI / CODEOWNERS 禁止 指定专门负责人审核
直接修改主分支 禁止 强制通过分支和 PR
发布生产环境 禁止 使用独立部署身份和人工批准

需要拦截的危险命令

命令黑名单示例 
rm -rf
git push --force
git reset --hard
DROP DATABASE
TRUNCATE TABLE
kubectl delete
terraform destroy
chmod 777
curl ... | bash
凭据隔离

AI 只获得短期、低权限、可撤销的测试凭据。

环境隔离

开发、测试、预发布、生产使用独立账户和资源。

分支隔离

每个任务使用独立分支或 Git worktree。

网络白名单

仅开放包管理、代码托管和必要文档域名。

05

自动化门禁：CI 才是最终裁判

把质量规则转化为不可绕过的自动检查和状态门禁。

⌄

基础质量检查

代码质量

格式检查、Lint、类型检查、未使用代码、循环依赖。

构建验证

完整构建、依赖锁文件一致性、制品可复现。

测试验证

单元、集成、契约、端到端、迁移和回归测试。

安全验证

密钥、依赖漏洞、SAST、容器、IaC 和许可证扫描。

变更约束检查

  • 是否修改禁止目录。
  • 是否删除或弱化已有测试。
  • 覆盖率是否下降。
  • 是否新增生产依赖。
  • 是否改变公共 API。
  • 是否包含破坏性数据库迁移。
  • 是否修改认证、权限或密钥逻辑。
CI 质量门禁示例 · YAML 
quality-gates:
  - format
  - lint
  - typecheck
  - unit-test
  - integration-test
  - build
  - secret-scan
  - dependency-scan
  - sast
  - migration-check
  - acceptance-test
保护范围： 不建议允许 AI 自行修改 .github/workflows/**、quality/**、CODEOWNERS、覆盖率阈值和安全扫描配置。
06

独立复核门禁：生成者不能兼任唯一审核者

使用独立上下文、不同角色和人类审核形成制衡。

⌄
需求说明
→
AI 开发代理
→
自动化测试
→
独立 AI 审核
→
人类审核
→
合并

独立 AI 审核要求

  • 使用新的会话和上下文。
  • 不读取开发代理的推理过程。
  • 只读取原始需求、Git diff 和验证报告。
  • 最好使用另一个模型或不同配置。
  • 审核代理只报告问题，不直接修改代码。
独立审核提示词 · Markdown 
你是独立代码审核员。

只根据以下内容进行审核：
1. 原始需求
2. 验收标准
3. Git diff
4. 测试报告

重点检查：
- 是否完整实现验收标准
- 是否修改了范围外文件
- 是否存在逻辑漏洞
- 是否遗漏边界条件
- 是否存在并发、权限或数据一致性问题
- 测试是否真正覆盖实现
- 是否通过修改测试掩盖问题
- 是否新增安全风险
- 是否具备回滚能力

不要修改代码。

按以下格式输出：
- 阻断问题
- 高风险问题
- 一般问题
- 测试缺口
- 是否建议合并
07

风险分级门禁

根据代码影响范围决定测试、审核和发布强度。

⌄
等级 典型修改 最低要求
L1 低风险 文档、样式、文案 自动检查 + 普通审核
L2 一般风险 页面功能、普通业务逻辑 单元测试 + 集成测试 + 人工审核
L3 高风险 公共 API、数据库结构、文件处理 CODEOWNER + 完整回归 + 预发布验证
L4 极高风险 登录、权限、支付、密钥、基础设施 双人审核 + 安全审核 + 灰度 + 人工发布
风险规则示例 · YAML 
risk_rules:
  critical:
    paths:
      - src/auth/**
      - src/payment/**
      - infrastructure/**
      - migrations/**
    required:
      - 2_human_approvals
      - security_review
      - staging_deployment
      - rollback_validation
不建议全自动合并的模块： 身份认证、用户权限、支付和资金、数据删除、数据库迁移、加密算法、CI/CD、云基础设施、生产配置、合规和隐私逻辑。
08

发布与线上质量门禁

测试通过不代表可以直接全量上线，仍需灰度、观察和回滚能力。

⌄
PR 合并
→
测试环境
→
验收测试
→
预发布
→
人工批准
→
5% 灰度
→
逐步扩容

至少监控的指标

  • HTTP 5xx 错误率和异常日志数量。
  • 接口 P95 / P99 延迟。
  • CPU、内存、数据库连接和消息积压。
  • 登录、支付等核心业务成功率。
  • 新版本与旧版本的指标差异。
  • 回滚次数、用户投诉和异常工单。
自动回滚条件示例 · YAML 
rollback:
  error_rate: "> 2%"
  p95_latency_increase: "> 30%"
  core_business_success_drop: "> 5%"
  critical_alerts: ">= 1"
09

推荐的项目目录

将需求、规则、质量脚本、工作流和测试分层管理。

⌄
目录结构 
project/
├── AGENTS.md
├── CLAUDE.md
├── docs/
│   ├── architecture/
│   ├── decisions/
│   └── specs/
│       └── TASK-001.md
├── quality/
│   ├── policy.yaml
│   ├── risk-rules.yaml
│   ├── acceptance/
│   ├── regression/
│   └── scripts/
│       ├── check-scope.sh
│       ├── check-test-deletion.sh
│       └── check-coverage.sh
├── .github/
│   ├── CODEOWNERS
│   ├── pull_request_template.md
│   └── workflows/
│       ├── quality.yml
│       ├── security.yml
│       └── deploy.yml
└── tests/
    ├── unit/
    ├── integration/
    ├── contract/
    └── e2e/
10

PR 必须提交的质量证据

用可验证结果替代“已经完成”“应该正常”等主观描述。

⌄
Pull Request 模板 · Markdown 
## 需求编号
TASK-001

## 风险等级
L2

## 修改范围
- src/auth/login.ts
- tests/auth/login.test.ts

## 验收标准
- [x] 正确账号可以登录
- [x] 错误密码返回统一错误
- [x] 连续失败触发限制
- [x] 密码不写入日志

## 验证证据
- Lint：通过
- Typecheck：通过
- Unit test：128/128
- Integration test：24/24
- Build：通过
- Secret scan：通过
- SAST：无高危问题

## 风险
登录限制状态依赖 Redis。

## 回滚方案
回滚当前提交，不涉及数据库结构变化。
不合格说明： “已完成开发，代码质量良好，所有功能应该可以正常工作。”这类描述不构成质量证据。
11

质量指标体系

用缺陷、返工和线上表现衡量质量，而不是仅统计代码产量。

⌄
指标 含义
AI PR 首次通过率 AI 一次提交通过所有质量门禁的比例
平均返工轮数 一个任务从首次提交到合并所需修改次数
审核缺陷密度 每千行变更发现的问题数量
线上逃逸缺陷率 进入生产后才被发现的缺陷比例
变更失败率 引起回滚、故障或事故的发布比例
覆盖率变化 新增代码是否获得足够测试覆盖
越权修改次数 AI 修改任务范围外代码的次数
测试删除率 通过删除测试规避失败的风险信号
回滚成功率 出现问题时是否能够快速恢复
不要作为核心质量指标： AI 写了多少行代码、每天完成多少 PR、消耗多少 Token、AI 自己声称的完成度。这些反映产量，不等于质量。
12

最小可用实施方案

先建立不可绕过的基础门禁，再逐步增加审核、灰度和数据看板。

⌄

第一批必须落实的八项措施

  1. 主分支禁止直接推送。
  2. 所有 AI 修改必须通过独立分支和 Pull Request。
  3. 建立 AGENTS.md 和 CLAUDE.md。
  4. 每个任务必须具备可执行的验收标准。
  5. CI 强制执行 Lint、类型检查、测试和构建。
  6. 禁止 AI 修改 CI、质量阈值和 CODEOWNERS。
  7. 每个 PR 至少进行一次独立审核。
  8. 高风险模块必须人工审批后发布。

分阶段建设路线

第一阶段

规则文件、CI、分支保护、PR 模板。

第二阶段

风险分级、CODEOWNERS、安全扫描。

第三阶段

独立 AI 审核、质量数据看板。

第四阶段

灰度发布、自动回滚、事故复盘。

理想状态不是让 AI 完全不犯错，而是即使 AI 犯错，错误也无法越过自动测试、权限边界、独立审核、人工审批和发布监控进入生产环境。