AI 辅助编码时代的产研测全链路 Harness 规范系统
范围 : 产品 → 研发 → 测试 → 部署 → 运维 → 运营 全生命周期
核心理念: 建立 AI 自主开发的闭环系统，实现规范驱动开发 (Spec-Driven Development)
目录
- 核心概念与架构升级
- 全链路目录结构规范
- [产品域 (Product) 规范模板](#产品域 (Product) 规范模板)
- [研发域 (Development) 规范模板](#研发域 (Development) 规范模板)
- [测试域 (Testing) 规范模板](#测试域 (Testing) 规范模板)
- [部署域 (Deployment) 规范模板](#部署域 (Deployment) 规范模板)
- [运维域 (Operations) 规范模板](#运维域 (Operations) 规范模板)
- [运营域 (Business) 规范模板](#运营域 (Business) 规范模板)
- [Harness 平台 YAML 模板库](#Harness 平台 YAML 模板库)
- 全链路质量门禁体系
- [AI 工作流 SOP 与闭环机制](#AI 工作流 SOP 与闭环机制)
- 度量体系与持续改进
- 实施路线图与行动清单
1. 核心概念与架构升级
1.1 从"最小可行 Harness"到"全链路 Harness"
| 维度 | 基础版 (v1.0) | 扩展版 (v2.0) |
|---|---|---|
| 覆盖范围 | 前后端代码开发 | 产品 → 研发 → 测试 → 部署 → 运维 → 运营 |
| AI 角色 | 编码助手 | 全流程自主代理 (Agent) |
| 约束文件 | CLAUDE.md / AGENTS.md |
分层约束：PRODUCT.md → CLAUDE.md → TEST.md → DEPLOY.md |
| 质量门禁 | 代码 Lint + 单元测试 | 全链路门禁：需求评审 → 代码评审 → 测试覆盖 → 安全扫描 → 部署验证 |
| 闭环机制 | 写代码 → 跑测试 → 修 bug | 需求拆解 → 规范生成 → 编码 → 测试 → 部署 → 监控 → 回滚/迭代 |
| 度量指标 | 构建成功率 | DORA 四指标 + 价值流效率 + AI 辅助效能 |
1.2 规范驱动开发 (Spec-Driven Development)
在 AI 辅助编码时代，规范即代码 。业界实践表明，将规范转化为 AI 的 always 级别执行约束，并前置到预 CR 环节，是保障大型项目成功的关键。参考美团 31 万行代码 AI 重构实践，团队沉淀出 AI 友好的工程约束，包括工程分层规范、业务域模型规约和仓储层规约，关键一步是将规范落地为 AI Rule。
核心原则:
- 需求前置: 开发人员与智能体在实施前共享一份明确的契约，需求范围无歧义
- 架构前置: 分层逻辑、模块边界与 API 签名必须预先锁定
- 全流程可追溯: 每项功能对应一条编号需求，代码审查标准从"这段代码看起来对吗？"转变为"这段代码是否符合我们事先达成的共识？"
- 变更时保留既定行为: 修复缺陷或重构时，明确记录不可变更的行为
1.3 五阶段生命周期 (Cortex Code 规范驱动技能)
┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ 1.需求分析 │ → │ 2.规范制定 │ → │ 3.任务分解 │ → │ 4.编码实现 │ → │ 5.验证交付 │
│ (EARS标注) │ │ (requirements│ │ (tasks.md) │ │ (遵循约束) │ │ (质量门禁) │
│ │ │ design.md) │ │ │ │ │ │ │
└─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘
↑ │
└────────────────── 反馈迭代 ← 监控告警 ← 运维数据 ─────────────────────┘2. 全链路目录结构规范
text
my-harness-project/
│
├── 📋 产品域 (Product)
│ ├── PRODUCT.md # 产品需求规范与 PRD 模板
│ ├── docs/prd/ # 需求文档目录
│ │ ├── YYYYMMDD_feature_name.md
│ │ └── api_contracts/ # OpenAPI/Swagger 契约文件
│ └── docs/adr/ # 架构决策记录 (Architecture Decision Records)
│
├── 🤖 研发域 (Development)
│ ├── CLAUDE.md # AI 核心约束：行为准则与边界
│ ├── AGENTS.md # 多 Agent 协作规范 (可选)
│ ├── .cursorrules # Cursor IDE 规则 (可选)
│ ├── src/ # 业务代码
│ │ ├── frontend/ # 前端项目 (Vue/React)
│ │ └── backend/ # 后端项目 (Spring/Node/Go)
│ └── scripts/ # 自定义校验脚本
│
├── 🧪 测试域 (Testing)
│ ├── TEST.md # 测试策略与规范
│ ├── tests/
│ │ ├── unit/ # 单元测试
│ │ ├── integration/ # 集成测试
│ │ ├── e2e/ # 端到端测试
│ │ ├── contract/ # 契约测试 (Pact)
│ │ ├── performance/ # 性能测试
│ │ └── security/ # 安全测试
│ └── test-reports/ # 测试报告归档
│
├── 🚀 部署域 (Deployment)
│ ├── DEPLOY.md # 部署规范与环境管理
│ ├── .github/workflows/ # CI/CD 流水线 (GitHub Actions)
│ ├── harness/ # Harness 平台配置
│ │ ├── pipelines/ # Pipeline Templates
│ │ ├── services/ # Service Definitions
│ │ └── environments/ # Environment Configs
│ ├── k8s-manifests/ # Kubernetes 部署清单
│ │ ├── base/
│ │ └── overlays/
│ │ ├── dev/
│ │ ├── staging/
│ │ └── prod/
│ └── terraform/ # 基础设施即代码 (IaC)
│
├── 🔧 运维域 (Operations)
│ ├── OPS.md # 运维规范与 SOP
│ ├── monitoring/ # 监控配置
│ │ ├── prometheus-rules/
│ │ ├── grafana-dashboards/
│ │ └── alertmanager/
│ ├── logging/ # 日志聚合配置
│ └── runbooks/ # 故障处理手册
│
├── 📊 运营域 (Business)
│ ├── BUSINESS.md # 业务指标与运营规范
│ ├── analytics/ # 数据分析脚本
│ └── feature-flags/ # 特性开关配置
│
├── ⚙️ 工程底座
│ ├── .pre-commit-config.yaml # 本地提交前校验
│ ├── Makefile # 统一命令入口
│ ├── docker-compose.yml # 本地开发环境
│ └── README.md # 项目总览
│
└── 📈 度量与改进
├── METRICS.md # 效能度量指标定义
└── .harness/ # Harness SEI 配置3. 产品域 (Product) 规范模板
3.1 核心约束 (PRODUCT.md)
markdown
## 1. 产品需求规范 (PRD)
### 1.1 需求格式标准 (EARS 标注法)
所有需求必须使用 EARS (Easy Approach to Requirements Syntax) 格式：
- **格式**: `当 [触发条件] 时，系统应 [系统响应]，以便 [业务价值]`
- **示例**: `当用户输入错误密码超过 5 次时，系统应锁定账户 30 分钟，以便防止暴力破解攻击`
- **编号**: 每条需求必须有唯一编号，如 `REQ-001`、`REQ-002`
### 1.2 PRD 文档结构PRD-YYYYMMDD_功能名称
1. 背景与目标
- 业务背景:
- 成功指标 (OKR/KPI):
2. 需求清单 (EARS格式)
| 编号 | 优先级 | 需求描述 | 验收标准 |
|---|---|---|---|
| REQ-001 | P0 | 当...时，系统应... | 可测试的验收条件 |
3. 用户旅程 (User Journey)
- 流程图或时序图
4. API 契约 (OpenAPI)
- 引用
docs/api_contracts/xxx.yaml
5. 非功能性需求
- 性能:
- 安全:
- 兼容性:
6. 风险评估
-
技术风险:
-
业务风险:
1.3 需求评审门禁
- 必须: 所有 P0/P1 需求必须通过产品 + 技术 + 测试三方评审
- 必须: API 契约必须在编码前完成并评审通过
- 禁止: 无 PRD 文档直接开始编码
- 禁止: 需求变更不更新 PRD 文档和编号
2. 架构决策记录 (ADR)
2.1 ADR 格式
markdown# ADR-XXX: 决策标题 ## 状态 - 提议 / 已通过 / 已废弃 / 已替代 ## 背景 - 需要解决的问题 ## 决策 - 选择的方案及理由 ## 后果 - 正面影响: - 负面影响: - 风险:
2.2 必须记录 ADR 的场景
- 引入新的技术栈或框架
- 修改核心架构或数据模型
- 变更安全策略或认证机制
- 修改部署架构或基础设施
3. AI 工作流规则 (产品域)
-
规划阶段 : AI 必须基于 PRD 生成
requirements.md和design.md -
契约先行 : API 契约必须在
tasks.md生成前锁定 -
变更控制: 任何需求变更必须更新 PRD 并重新触发 AI 规划流程
3.2 需求与代码关联规范
text# Git Commit 规范 (必须关联需求) <类型>(<范围>): <描述> [REQ-XXX] 类型: feat: 新功能 fix: 修复 docs: 文档 style: 格式 refactor: 重构 test: 测试 chore: 构建/工具 示例: feat(auth): add OAuth2 login support [REQ-042] fix(api): resolve null pointer in user query [REQ-015]
4. 研发域 (Development) 规范模板
4.1 前端项目 (Vue 3 / React) - 升级版
markdown
## 1. 项目概览
- **目标**: 构建基于 Vue 3 + TypeScript + Vite 的现代化 Web 应用
- **技术栈**: Vue 3 (`<script setup lang="ts">`), Vue Router 4, Pinia, Vite, Tailwind CSS
- **AI 辅助规范**: 所有组件必须由 AI 遵循本规范生成，禁止偏离
## 2. 编码规范与命名约定
- **Vue 组件**: 强制使用 `<script setup lang="ts">`，文件名 PascalCase
- **组合式函数**: `use` 前缀，如 `useWindowSize.ts`
- **TypeScript**: 严禁 `any`，所有 Props/Emits 必须定义接口
- **样式**: Scoped CSS 优先，Tailwind 工具类次之
- **AI 生成要求**: 每个组件文件必须包含 JSDoc 注释，说明组件用途和 Props
## 3. 质量门禁 (Quality Gates)
| 门禁项 | 命令 | 阈值 | 阻断级别 |
|--------|------|------|----------|
| 代码规范 | `pnpm lint` | 零错误零警告 | 阻断 |
| 类型检查 | `pnpm type-check` | 通过 | 阻断 |
| 单元测试 | `pnpm test:unit` | 覆盖率 ≥ 80% | 阻断 |
| 构建成功 | `pnpm build` | 成功且 gzipped < 500KB | 阻断 |
| 依赖审计 | `pnpm audit` | 无高危漏洞 | 警告 |
## 4. 测试策略
- **单元测试**: Vitest，覆盖 composables、utils、关键组件
- **集成测试**: 用户关键流程 (登录 → 主页 → 核心功能)
- **视觉回归**: 使用 Playwright 或 Chromatic 进行 UI 快照比对
- **AI 测试辅助**: AI 生成测试用例时，必须遵循 Human-in-the-loop 模式------人工界定测试范围和风险级别，AI 负责代码扫描和用例步骤填充
## 5. AI 工作流规则
1. **规划**: 明确功能需求，确定影响文件清单
2. **契约检查**: 确认 API 契约已存在且已评审
3. **实现**: 遵循规范编写代码，生成 JSDoc
4. **自测闭环**: 运行 `pnpm lint` → `pnpm type-check` → `pnpm test:unit` → 修复 → 重测
5. **提交**: 规范 commit 信息，关联需求编号
## 6. 禁止行为 (Forbidden Actions)
- **禁止**: 直接修改 `node_modules` 或 `.git`
- **禁止**: 生成大段被注释的代码 (调试用除外)
- **禁止**: 硬编码密钥、密码、Token
- **禁止**: 绕过 TypeScript 类型检查使用 `// @ts-ignore`
- **禁止**: 在组件中直接调用 API，必须通过 `api/` 层封装4.2 后端项目 (Spring Boot / Node.js / Go) - 升级版
markdown
## 1. 项目概览
- **目标**: 构建高可用、安全的 RESTful API 服务
- **技术栈**: Spring Boot 3.x + Java 21 / Node.js 20 + TypeScript / Go 1.22
- **架构**: Controller → Service → Repository 三层分离
## 2. 编码规范
- **Java**: 标准命名，类 PascalCase，方法/变量 camelCase
- **API 设计**: RESTful 规范，正确 HTTP 方法和状态码
- **DTO 强制**: 禁止直接返回 Entity，必须使用 DTO
- **异常处理**: 统一异常处理器，禁止在 Controller/Service 中捕获后吞掉异常
## 3. 质量门禁
| 门禁项 | 命令/工具 | 阈值 | 阻断级别 |
|--------|-----------|------|----------|
| 单元测试 | JUnit 5 / Vitest | 行覆盖率 ≥ 80%，核心 ≥ 90% | 阻断 |
| 集成测试 | @SpringBootTest / Supertest | 通过 | 阻断 |
| 代码分析 | SonarQube | 无阻断性问题 | 阻断 |
| 安全扫描 | SAST/SCA | 无高危漏洞 | 阻断 |
| 构建 | `mvn verify` / `npm run build` | 成功 | 阻断 |
## 4. 安全红线 (不可触碰)
- **SQL 注入**: 严禁字符串拼接 SQL，必须使用 ORM/参数化查询
- **密码存储**: 必须使用 BCrypt/Argon2 强哈希，禁止明文或弱哈希
- **输入校验**: 所有外部输入必须使用 Bean Validation / Zod / Validator
- **敏感信息**: 严禁代码中提交密码、密钥，必须使用环境变量 + 密钥管理服务
- **XSS/CSRF**: 输出必须转义，敏感操作必须校验 CSRF Token
## 5. AI 工作流规则
- **TDD 优先**: 新功能必须先写失败单元测试，再写实现代码
- **契约先行**: API 设计先定义 OpenAPI 规范，再生成 Controller
- **安全自检**: AI 生成代码后，必须自检是否触碰安全红线
- **文档同步**: 代码变更必须同步更新 API 文档 (Swagger/OpenAPI)
## 6. 禁止行为
- **禁止**: Controller 层编写业务逻辑
- **禁止**: 直接返回 Entity 给前端
- **禁止**: 在日志中打印敏感信息 (密码、Token、身份证号)
- **禁止**: 使用 `System.out.println` 或 `console.log` 生产代码 (必须使用结构化日志)
- **禁止**: 捕获异常后不做任何处理或仅打印日志4.3 数据库脚本项目 (SQL) - 升级版
markdown
## 1. 数据库变更规范
- **变更即代码**: 所有 DDL/DML 纳入版本控制
- **幂等性**: 脚本必须幂等，多次执行结果一致
- **不可变性**: 已发布脚本禁止修改，变更通过追加新脚本实现
- **回滚支持**: 每条变更脚本必须提供对应回滚脚本
- **事务安全**: 所有 DDL 必须在事务内执行
## 2. 命名规范
| 类型 | 格式 | 示例 |
|------|------|------|
| 变更脚本 | `YYYYMMDD_HHMM_<描述>_apply.sql` | `20250519_1400_add_user_email_apply.sql` |
| 回滚脚本 | `YYYYMMDD_HHMM_<描述>_rollback.sql` | `20250519_1400_add_user_email_rollback.sql` |
| 数据修复 | `YYYYMMDD_HHMM_<描述>_fix.sql` | `20250519_1400_correct_order_status_fix.sql` |
## 3. 质量门禁
- **语法检查**: `sqlfluff lint` 或类似工具
- **迁移测试**: 在沙盒环境执行 apply → 验证 → rollback → 验证
- **性能审查**: 新增索引/大表变更必须通过 DBA 评审
## 4. 禁止行为
- **禁止**: 生产环境直接执行未评审脚本
- **禁止**: 事务外执行 DDL
- **禁止**: 使用 `#` 单行注释 (必须用 `--` 或 `/* */`)
- **禁止**: 无 WHERE 条件的 UPDATE/DELETE
- **禁止**: 在生产环境执行 TRUNCATE5. 测试域 (Testing) 规范模板
5.1 核心约束 (TEST.md)
markdown
## 1. 测试策略金字塔 /\
/ \
/ E2E \ ← 端到端测试 (10%)
/─────────\
/ Integration \ ← 集成测试 (20%)/─────────────────
/ Unit Tests \ ← 单元测试 (70%)
/─────────────────────────\
## 2. 测试分层规范
### 2.1 单元测试 (Unit Tests)
- **目标**: 验证单个函数/组件的正确性
- **工具**: Vitest / Jest / JUnit 5
- **规范**:
- 每个公共函数必须有对应测试
- 测试名必须描述行为和预期结果: `should return user when id exists`
- 使用 AAA 模式: Arrange → Act → Assert
- Mock 外部依赖 (API、数据库、时钟)
- **覆盖率要求**:
- 行覆盖率: ≥ 80%
- 分支覆盖率: ≥ 70%
- 核心业务流程: ≥ 90%
### 2.2 集成测试 (Integration Tests)
- **目标**: 验证模块间协作和数据流
- **范围**: API 端点、数据库交互、消息队列
- **规范**:
- 使用测试数据库 (TestContainers / H2 / SQLite)
- 每个 API 端点至少一个 happy path 和一个 error path
- 测试数据隔离，测试后清理
### 2.3 端到端测试 (E2E Tests)
- **目标**: 验证完整用户旅程
- **工具**: Playwright / Cypress
- **规范**:
- 覆盖核心业务流程: 注册 → 登录 → 核心功能 → 支付 → 退出
- 每个测试必须独立，不依赖其他测试状态
- 使用 Page Object 模式组织测试代码
- 运行时间: 单个测试 < 30 秒
### 2.4 契约测试 (Contract Tests)
- **目标**: 验证前后端 API 契约一致性
- **工具**: Pact / Spring Cloud Contract
- **规范**:
- 消费者驱动契约 (CDC)
- API 变更必须同步更新契约测试
- CI 中契约测试失败阻断部署
### 2.5 性能测试 (Performance Tests)
- **目标**: 验证系统在高负载下的表现
- **工具**: k6 / JMeter / Gatling
- **规范**:
- 基准测试: 单接口响应时间 P99 < 200ms
- 负载测试: 模拟预期峰值流量
- 压力测试: 找到系统瓶颈和崩溃点
- 稳定性测试: 持续运行 24 小时无内存泄漏
### 2.6 安全测试 (Security Tests)
- **目标**: 发现安全漏洞
- **工具**: OWASP ZAP / Burp Suite / Snyk
- **规范**:
- 每次部署前自动扫描
- 高危漏洞必须修复后才能上线
- 定期渗透测试 (季度)
## 3. AI 辅助测试规范
### 3.1 Human-in-the-loop 模式
基于业界实践，AI 辅助测试必须遵循以下模式：
- **人工主导**: 人界定测试范围、风险级别、边界场景
- **AI 辅助**: AI 负责代码扫描、用例步骤填充、边界值生成
- **禁止全自动**: AI 不得独立生成完整测试方案而不经过人工范围界定
### 3.2 AI 生成测试用例规范-
人工输入: 功能描述 + 风险级别 (高/中/低) + 特殊边界条件
-
AI 输出: 测试用例草稿 (包含前置条件、步骤、预期结果)
-
人工 Review: 检查是否覆盖隐性关联场景、高危场景
-
AI 修正: 根据 Review 意见修正用例
-
人工确认: 最终确认并纳入测试库
4. 质量门禁 (测试域)
门禁项 阶段 阈值 阻断 单元测试通过率 CI Build 100% 是 单元测试覆盖率 CI Build ≥ 80% 是 集成测试通过率 CI Build 100% 是 契约测试通过 CI Build 100% 是 E2E 测试通过率 Pre-Deploy 100% 是 性能测试基线 Pre-Deploy P99 < 阈值 是 安全扫描 Pre-Deploy 无高危漏洞 是 5. 禁止行为
- 禁止: 无测试代码提交 (测试与代码同行)
- 禁止: 跳过失败测试直接提交 (必须修复或标记为跳过并说明原因)
- 禁止: 测试中使用生产环境数据
- 禁止: 测试代码中硬编码敏感信息
6. 部署域 (Deployment) 规范模板
6.1 核心约束 (DEPLOY.md)
markdown
## 1. 部署策略规范
### 1.1 环境定义
| 环境 | 用途 | 部署触发条件 | 审批要求 |
|------|------|--------------|----------|
| Dev | 开发自测 | 代码推送自动 | 无 |
| Test | 集成测试 | CI 通过后自动 | 无 |
| Staging | 预发布验证 | 手动触发 | 测试负责人 |
| Prod | 生产环境 | 手动触发 | 技术负责人 + 产品负责人 |
| Hotfix | 紧急修复 | 紧急流程 | 值班负责人 |
### 1.2 部署策略
- **蓝绿部署 (Blue/Green)**: 适用于无状态服务，零停机切换
- **金丝雀部署 (Canary)**: 适用于有状态服务，渐进式流量切换 (5% → 25% → 50% → 100%)
- **滚动部署 (Rolling)**: 适用于可容忍短暂不一致的场景
- **禁止**: 直接在生产环境手动修改配置或代码
### 1.3 回滚策略
- **自动回滚触发条件**:
- 错误率 > 阈值 (如 1%)
- P99 延迟 > 阈值 (如 2 秒)
- 健康检查失败持续 > 2 分钟
- **回滚 SLA**: 5 分钟内完成回滚
- **回滚验证**: 回滚后必须验证核心功能正常
## 2. 制品管理规范
- **制品晋级**: Dev → Test → Staging → Prod，逐级晋级
- **不可变性**: 晋级过程中制品内容不变，仅元数据变化
- **签名验证**: 生产部署必须验证制品签名
- **保留策略**: 保留最近 30 个版本，超出自动清理
## 3. 配置管理规范
- **配置分离**: 代码与配置分离，配置通过配置中心管理 (Consul / Nacos / AWS Parameter Store)
- **环境隔离**: 每个环境独立配置，禁止共享
- **敏感配置**: 密码、密钥必须通过密钥管理服务 (Vault / AWS Secrets Manager)
- **配置审计**: 所有配置变更必须记录审计日志
## 4. 数据库部署规范
- **变更窗口**: 大表变更必须在低峰期执行，提前通知
- **灰度 DDL**: 使用 pt-online-schema-change 或类似工具，避免锁表
- **数据备份**: 部署前必须完成数据库备份
- **回滚脚本**: 必须预先准备回滚脚本并验证
## 5. AI 工作流规则 (部署域)
- **部署前检查**: AI 必须确认所有质量门禁已通过
- **自动验证**: 部署后 AI 自动运行健康检查和 smoke test
- **监控对接**: 部署后自动关联监控告警
- **回滚决策**: AI 可根据监控指标建议回滚，但回滚执行必须人工确认
## 6. 禁止行为
- **禁止**: 未经审批直接部署生产环境
- **禁止**: 使用 `latest` 标签部署生产环境
- **禁止**: 部署未通过安全扫描的制品
- **禁止**: 在部署过程中修改流水线配置
- **禁止**: 跳过 Staging 环境直接部署 Prod7. 运维域 (Operations) 规范模板
7.1 核心约束 (OPS.md)
markdown
## 1. 监控体系规范
### 1.1 监控分层
| 层级 | 指标类型 | 工具示例 | 采集频率 |
|------|----------|----------|----------|
| 基础设施 | CPU/内存/磁盘/网络 | Prometheus + Node Exporter | 15s |
| 应用性能 | 响应时间/吞吐量/错误率 | APM (SkyWalking / Jaeger) | 实时 |
| 业务指标 | 订单量/用户数/转化率 | 自定义 Metrics | 1min |
| 日志 | 结构化日志 | ELK / Loki | 实时 |
| 链路追踪 | 分布式追踪 | OpenTelemetry + Jaeger | 采样 |
### 1.2 告警规范
- **告警分级**:
- P0 (紧急): 服务不可用、数据丢失，立即响应 (5min)
- P1 (高): 核心功能受损、性能严重下降，15min 内响应
- P2 (中): 非核心功能异常，1h 内响应
- P3 (低): 优化建议，工作日响应
- **告警原则**: 可观测性三大支柱------指标、日志、链路追踪缺一不可
- **告警抑制**: 避免告警风暴，同类告警合并，升级策略明确
## 2. 故障处理 SOP
### 2.1 故障响应流程-
发现 (Monitoring Alert / 用户反馈)
↓ -
确认 (On-call 工程师确认影响范围)
↓ -
止损 (立即止损措施: 回滚 / 限流 / 降级)
↓ -
定位 (日志分析 / 链路追踪 / 复现)
↓ -
修复 (实施修复方案)
↓ -
验证 (确认修复有效)
↓ -
复盘 (Post-mortem，24h 内完成)
2.2 Runbook 规范
- 每个核心服务必须有对应的 Runbook
- Runbook 必须包含: 服务架构图、依赖关系、常见故障场景、处理步骤、升级路径
- Runbook 定期演练 (季度)，确保有效性
3. 容量管理规范
- 容量规划: 基于业务增长预测，提前 3 个月规划扩容
- 自动扩缩容: HPA/VPA 配置，峰值自动扩容，低峰自动缩容
- 资源限额: 每个服务必须设置 CPU/Memory Request 和 Limit
- 成本优化: 定期审查资源利用率，清理闲置资源
4. 安全运维规范
- 访问控制: 生产环境访问必须通过堡垒机，操作审计留痕
- 变更窗口: 生产变更必须在变更窗口内执行，紧急变更事后补审批
- 备份策略:
- 数据库: 每日全量 + 实时增量
- 文件存储: 跨区域冗余
- 配置: 版本控制 + 定期备份
- 灾难恢复: RPO < 1h，RTO < 4h，定期演练
5. AI 辅助运维规范
- 智能告警: AI 分析告警模式，抑制误报，关联根因
- 自动修复: 对于已知故障模式，AI 可执行预设修复脚本 (如重启、扩容)
- 预测性维护: AI 分析趋势，预测资源瓶颈和潜在故障
- 知识库: AI 辅助生成和更新 Runbook，基于历史故障案例
6. 禁止行为
- 禁止: 无监控覆盖的服务上线
- 禁止: 生产环境直接调试 (必须通过日志和追踪)
- 禁止: 未经授权访问生产数据库
- 禁止: 删除或修改审计日志
- 禁止: 故障发生后 24h 内未完成复盘文档
8. 运营域 (Business) 规范模板
8.1 核心约束 (BUSINESS.md)
markdown
## 1. 业务指标规范
### 1.1 指标分层
| 层级 | 指标类型 | 示例 | 采集方式 |
|------|----------|------|----------|
| 北极星指标 | 核心业务目标 | GMV、DAU、留存率 | 数据仓库 |
| 过程指标 | 转化漏斗 | 注册率、激活率、付费率 | 埋点系统 |
| 健康指标 | 系统稳定性 | 可用性、错误率、响应时间 | 监控系统 |
| 效能指标 | 研发效率 | 部署频率、前置时间、恢复时间 | DevOps 平台 |
### 1.2 埋点规范
- **埋点文档**: 每个埋点必须有文档说明 (事件名、触发时机、属性字段)
- **命名规范**: `模块_页面_动作`，如 `order_checkout_click`
- **属性标准**: 统一用户 ID、时间戳、设备信息、来源渠道
- **质量校验**: 埋点上线前必须验证数据准确性
## 2. 特性开关 (Feature Flags) 规范
- **开关分级**:
- 发布开关: 控制功能是否对用户可见
- 实验开关: A/B 测试分组控制
- 运维开关: 降级、限流等运维操作
- **生命周期**: 开关必须有创建时间、计划下线时间、负责人
- **清理策略**: 功能稳定后 2 周内必须清理开关代码
## 3. 数据安全规范
- **数据分类**: 公开、内部、敏感、机密四级
- **脱敏规则**: 敏感数据展示必须脱敏 (手机号、身份证号、银行卡)
- **权限控制**: 数据访问遵循最小权限原则
- **审计追踪**: 敏感数据访问必须记录审计日志
## 4. AI 辅助运营规范
- **智能分析**: AI 辅助分析业务数据，识别异常和机会
- **自动化报告**: 定期自动生成运营报告
- **预测模型**: AI 预测业务趋势，辅助决策9. Harness 平台 YAML 模板库
9.1 前端 CD Stage 模板 (增强版)
yaml
template:
name: "Frontend CD Stage Template v2"
type: "Stage"
spec:
stage:
name: "deploy_frontend"
type: "Deployment"
spec:
service:
name: "frontend_service"
identifier: "frontend_service"
serviceDefinition:
type: "Kubernetes"
spec:
manifests:
- manifest:
identifier: "frontend_manifest"
type: "K8sManifest"
spec:
store:
type: "Git"
spec:
connectorRef: "YOUR_GIT_CONNECTOR"
gitFetchType: "Branch"
paths:
- "k8s-manifests/frontend/*.yaml"
artifacts:
primary:
type: "DockerRegistry"
spec:
connectorRef: "YOUR_DOCKER_CONNECTOR"
imagePath: "<+service.imagePath>"
tag: "<+pipeline.variables.IMAGE_TAG>"
execution:
steps:
# 步骤 1: 健康检查 (前置验证)
- step:
name: "Pre-Deploy Health Check"
identifier: "pre_health_check"
type: "Run"
spec:
command: |-
echo "Running pre-deployment validations..."
# 验证制品签名
# 验证配置完整性
# 步骤 2: 金丝雀部署 (5% 流量)
- step:
name: "Canary Deployment 5%"
identifier: "canary_5"
type: "K8sCanaryDeploy"
timeout: "10m"
spec:
instanceSelection:
type: "Percentage"
spec:
percentage: 5
# 步骤 3: 自动化验证 (Smoke Test)
- step:
name: "Smoke Test"
identifier: "smoke_test"
type: "Run"
spec:
command: |-
curl -f http://canary-endpoint/health || exit 1
curl -f http://canary-endpoint/api/smoke || exit 1
# 步骤 4: 渐进式流量切换 (25% → 50% → 100%)
- step:
name: "Canary Deployment 25%"
identifier: "canary_25"
type: "K8sCanaryDeploy"
spec:
instanceSelection:
type: "Percentage"
spec:
percentage: 25
- step:
name: "Canary Deployment 50%"
identifier: "canary_50"
type: "K8sCanaryDeploy"
spec:
instanceSelection:
type: "Percentage"
spec:
percentage: 50
# 步骤 5: 全量部署
- step:
name: "Rollout Deployment 100%"
identifier: "rollout_100"
type: "K8sRollingDeploy"
timeout: "10m"
spec:
skipDryRun: false
rollbackSteps:
- step:
name: "Rollback Deployment"
identifier: "rollback_deployment"
type: "K8sRollingRollback"
timeout: "10m"
spec: {}
infrastructure:
infrastructureDefinition:
type: "KubernetesDirect"
spec:
connectorRef: "YOUR_K8S_CONNECTOR"
namespace: "<+pipeline.variables.NAMESPACE>"
releaseName: "release-<+INFRA_KEY>"
variables:
- name: "IMAGE_TAG"
type: "String"
description: "Docker image tag to deploy"
- name: "NAMESPACE"
type: "String"
description: "Kubernetes namespace"9.2 Java CI Pipeline 模板 (增强版)
yaml
template:
name: "Java CI Pipeline Template v2"
type: "Pipeline"
spec:
stages:
- stage:
name: "build_and_test"
type: "CI"
spec:
infrastructure:
type: "KubernetesDirect"
spec:
connectorRef: "YOUR_K8S_CONNECTOR"
namespace: "harness-ci"
caching:
enabled: true
execution:
steps:
- step:
name: "Checkout Code"
identifier: "checkout"
type: "GitClone"
spec:
connectorRef: "YOUR_GIT_CONNECTOR"
build: "<+trigger.build>"
# 步骤 1: 依赖安全扫描
- step:
name: "Dependency Security Scan"
identifier: "dependency_scan"
type: "Run"
spec:
image: "maven:3.8-openjdk-18"
command: |-
mvn org.owasp:dependency-check-maven:check
# 步骤 2: 代码质量分析
- step:
name: "SonarQube Analysis"
identifier: "sonar_analysis"
type: "Run"
spec:
image: "maven:3.8-openjdk-18"
command: |-
mvn sonar:sonar -Dsonar.projectKey=<+pipeline.variables.PROJECT_KEY>
# 步骤 3: 构建与测试
- step:
name: "Maven Build and Test"
identifier: "maven_build"
type: "Run"
spec:
image: "maven:3.8-openjdk-18"
shell: "Sh"
command: |-
mvn clean test package
reports:
- type: "JUnit"
spec:
paths:
- "target/surefire-reports/*.xml"
- type: "Jacoco"
spec:
paths:
- "target/site/jacoco/jacoco.xml"
# 步骤 4: 安全扫描 (SAST)
- step:
name: "SAST Security Scan"
identifier: "sast_scan"
type: "Run"
spec:
command: |-
# 运行 SAST 工具扫描源码
echo "Running SAST scan..."
# 步骤 5: 制品晋级 (保存并签名)
- step:
name: "Save and Sign JAR Artifact"
identifier: "save_jar"
type: "SaveArtifacts"
spec:
connectorRef: "YOUR_ARTIFACT_STORAGE_CONNECTOR"
artifacts:
- path: "target/*.jar"
tag: "<+pipeline.variables.JAR_VERSION>"
# 步骤 6: 质量门禁检查
- step:
name: "Quality Gate Check"
identifier: "quality_gate"
type: "Run"
spec:
command: |-
# 检查 SonarQube 质量门禁
# 检查测试覆盖率阈值
# 检查安全扫描结果
echo "Quality gate passed"9.3 全栈 CI Pipeline 模板 (Matrix 并行构建 + 安全扫描)
yaml
template:
name: "FullStack CI Pipeline Template v2"
type: "Pipeline"
spec:
stages:
# 阶段 1: 并行构建与测试
- stage:
name: "parallel_build_and_test"
type: "CI"
spec:
execution:
strategy:
matrix:
project:
- "frontend"
- "backend"
node_version:
- "20"
java_version:
- "21"
steps:
- step:
name: "Build and Test <+matrix.project>"
identifier: "build_<+matrix.project>"
type: "Run"
spec:
command: |-
if [ "<+matrix.project>" = "frontend" ]; then
cd frontend
npm ci
npm run lint
npm run type-check
npm run test:unit -- --coverage
npm run build
else
cd backend
mvn clean verify
fi
# 阶段 2: 集成测试 (前后端联调)
- stage:
name: "integration_test"
type: "CI"
spec:
execution:
steps:
- step:
name: "Start Services"
identifier: "start_services"
type: "Run"
spec:
command: |-
docker-compose -f docker-compose.test.yml up -d
sleep 30 # 等待服务启动
- step:
name: "Run E2E Tests"
identifier: "e2e_tests"
type: "Run"
spec:
command: |-
cd tests/e2e
npx playwright test
- step:
name: "Run Contract Tests"
identifier: "contract_tests"
type: "Run"
spec:
command: |-
cd tests/contract
npm run test:contract
- step:
name: "Run Performance Tests"
identifier: "perf_tests"
type: "Run"
spec:
command: |-
cd tests/performance
k6 run load-test.js
# 阶段 3: 安全与合规扫描
- stage:
name: "security_scan"
type: "CI"
spec:
execution:
steps:
- step:
name: "Container Image Scan"
identifier: "container_scan"
type: "Run"
spec:
command: |-
# 扫描前端和后端 Docker 镜像
trivy image frontend:latest
trivy image backend:latest
- step:
name: "Secrets Detection"
identifier: "secrets_scan"
type: "Run"
spec:
command: |-
# 检测代码中是否泄露密钥
gitleaks detect --source . --verbose
# 阶段 4: 制品晋级与部署准备
- stage:
name: "artifact_promotion"
type: "CI"
spec:
execution:
steps:
- step:
name: "Sign Artifacts"
identifier: "sign_artifacts"
type: "Run"
spec:
command: |-
# 对制品进行签名
cosign sign --key env://COSIGN_PRIVATE_KEY frontend.tar
cosign sign --key env://COSIGN_PRIVATE_KEY backend.jar
- step:
name: "Generate SBOM"
identifier: "generate_sbom"
type: "Run"
spec:
command: |-
# 生成软件物料清单
syft frontend.tar -o spdx-json=frontend-sbom.json
syft backend.jar -o spdx-json=backend-sbom.json9.4 数据库迁移 Pipeline 模板 (增强版)
yaml
template:
name: "Database Migration Pipeline Template v2"
type: "Pipeline"
spec:
stages:
- stage:
name: "db_migration_validation"
type: "CI"
spec:
execution:
steps:
# 步骤 1: SQL 语法检查
- step:
name: "SQL Lint Check"
identifier: "sql_lint"
type: "Run"
spec:
image: "sqlfluff/sqlfluff:latest"
command: |-
sqlfluff lint migrations/*.sql
# 步骤 2: 迁移脚本验证 (沙盒环境)
- step:
name: "Validate Migration in Sandbox"
identifier: "validate_sandbox"
type: "Run"
spec:
image: "postgres:15"
command: |-
# 在临时数据库执行 apply → 验证 → rollback → 验证
psql -h sandbox-db -U testuser -d testdb -f migrations/apply.sql
# 运行验证查询
psql -h sandbox-db -U testuser -d testdb -f tests/validation.sql
# 执行回滚
psql -h sandbox-db -U testuser -d testdb -f migrations/rollback.sql
# 再次验证
psql -h sandbox-db -U testuser -d testdb -f tests/post_rollback.sql
- stage:
name: "db_migration_deploy"
type: "Deployment"
spec:
service:
name: "db_migration_service"
identifier: "db_migration_service"
execution:
steps:
# 步骤 1: 备份生产数据库
- step:
name: "Backup Production DB"
identifier: "backup_prod"
type: "Run"
spec:
command: |-
pg_dump -h prod-db -U admin -Fc production_db > backup_$(date +%Y%m%d_%H%M).dump
# 步骤 2: 执行迁移 (事务内)
- step:
name: "Execute Migration"
identifier: "run_migration"
type: "Run"
spec:
command: |-
# 使用 Flyway 在事务内执行
flyway -url=jdbc:postgresql://prod-db:5432/production_db -user=$DB_USER -password=$DB_PASS -locations=filesystem:migrations migrate
# 步骤 3: 迁移后验证
- step:
name: "Post-Migration Validation"
identifier: "post_validation"
type: "Run"
spec:
command: |-
# 运行核心业务流程验证
psql -h prod-db -U admin -d production_db -f tests/post_migration.sql
# 步骤 4: 人工审批 (失败时回滚)
- step:
name: "Approval for Rollback"
identifier: "rollback_approval"
type: "Approval"
spec:
approval:
type: "Manual"
spec:
timeout: "1h"
# 步骤 5: 执行回滚 (条件执行)
- step:
name: "Execute Rollback"
identifier: "run_rollback"
type: "Run"
when:
stageStatus: "Failed"
spec:
command: |-
flyway -url=jdbc:postgresql://prod-db:5432/production_db -user=$DB_USER -password=$DB_PASS undo10. 全链路质量门禁体系
10.1 质量门禁总览
┌─────────────────────────────────────────────────────────────────────────────┐
│ 全链路质量门禁体系 (Quality Gates) │
├─────────────┬─────────────┬─────────────┬─────────────┬─────────────────────┤
│ 产品域 │ 研发域 │ 测试域 │ 部署域 │ 运维域 │
├─────────────┼─────────────┼─────────────┼─────────────┼─────────────────────┤
│ PRD 评审通过 │ Lint 零警告 │ 单元测试 100%│ 制品签名验证 │ 监控覆盖率 100% │
│ ADR 记录完整 │ 类型检查通过 │ 覆盖率 ≥ 80% │ 安全扫描通过 │ 告警配置完整 │
│ API 契约锁定 │ 构建成功 │ 集成测试 100%│ 配置分离验证 │ Runbook 完备 │
│ 需求编号关联 │ 安全红线自检 │ E2E 测试 100%│ 数据库备份完成│ 容量规划就绪 │
│ 三方评审通过 │ 核心逻辑覆盖 │ 性能测试通过 │ 回滚脚本就绪 │ 灾备演练通过 │
│ │ ≥ 90% │ 安全测试通过 │ 审批流程完成 │ │
└─────────────┴─────────────┴─────────────┴─────────────┴─────────────────────┘10.2 门禁执行矩阵
| 阶段 | 门禁项 | 检查方式 | 阻断级别 | 责任人 |
|---|---|---|---|---|
| 需求 | PRD 格式合规 (EARS) | 自动化检查 + 人工评审 | 阻断 | 产品经理 |
| 需求 | API 契约已定义 | 文件存在性检查 | 阻断 | 架构师 |
| 需求 | ADR 已记录 (架构变更) | 文件存在性检查 | 阻断 | 技术负责人 |
| 编码 | Commit 关联需求编号 | Git Hook 检查 | 阻断 | 开发者 |
| 编码 | 代码规范 (Lint) | CI 自动执行 | 阻断 | 开发者 |
| 编码 | 类型检查通过 | CI 自动执行 | 阻断 | 开发者 |
| 编码 | 安全红线自检 | AI 辅助 + 人工 Review | 阻断 | 开发者 |
| 测试 | 单元测试通过率 | CI 自动执行 | 阻断 | 开发者 |
| 测试 | 单元测试覆盖率 | CI 自动执行 | 阻断 | 开发者 |
| 测试 | 集成测试通过率 | CI 自动执行 | 阻断 | 开发者 |
| 测试 | 契约测试通过率 | CI 自动执行 | 阻断 | 前后端 |
| 测试 | E2E 测试通过率 | CI 自动执行 | 阻断 | QA |
| 测试 | 性能测试基线 | CI 自动执行 | 阻断 | QA |
| 测试 | 安全扫描 (SAST/SCA) | CI 自动执行 | 阻断 | 安全团队 |
| 部署 | 制品签名验证 | CD 自动执行 | 阻断 | DevOps |
| 部署 | 配置分离验证 | CD 自动执行 | 阻断 | DevOps |
| 部署 | 数据库备份完成 | CD 自动执行 | 阻断 | DBA |
| 部署 | 回滚脚本就绪 | 文件存在性检查 | 阻断 | DevOps |
| 部署 | 生产审批完成 | 人工审批 | 阻断 | 技术负责人 |
| 运维 | 监控覆盖率 | 自动化巡检 | 阻断 | SRE |
| 运维 | 告警配置 | 自动化巡检 | 阻断 | SRE |
| 运维 | Runbook 完备 | 人工检查 | 警告 | SRE |
11. AI 工作流 SOP 与闭环机制
11.1 全链路 AI 工作流
┌──────────────────────────────────────────────────────────────────────────────┐
│ AI 自主开发闭环系统 │
├──────────────────────────────────────────────────────────────────────────────┤
│ │
│ ① 需求输入 ──→ ② AI 规划 ──→ ③ 规范生成 ──→ ④ 编码实现 ──→ ⑤ 自测闭环 │
│ │ │ │ │ │ │
│ │ │ │ │ │ │
│ ↓ ↓ ↓ ↓ ↓ │
│ PRD 文档 requirements.md tasks.md 代码文件 测试报告 │
│ EARS格式 design.md + JSDoc + Lint报告 │
│ API契约锁定 + 覆盖率报告 │
│ + 安全自检 │
│ │
│ ⑥ 人工 Review ──→ ⑦ CI 验证 ──→ ⑧ 部署发布 ──→ ⑨ 监控验证 ──→ ⑩ 反馈迭代 │
│ │ │ │ │ │ │
│ │ │ │ │ │ │
│ ↓ ↓ ↓ ↓ ↓ │
│ 代码审查 全门禁通过 金丝雀发布 健康检查 业务指标 │
│ + 架构审查 + 制品晋级 + 自动回滚 + 告警验证 + 用户反馈 │
│ │
│ ◄─────────────────────────────────────────────────────────────────────── │
│ 异常时触发回滚，数据驱动持续改进 │
└──────────────────────────────────────────────────────────────────────────────┘11.2 AI 工作流详细 SOP
SOP-001: 新功能开发
markdown
## 触发条件
收到新功能需求 (PRD 已评审通过)
## 执行步骤
### Phase 1: 规划 (Planning)
1. AI 读取 `PRODUCT.md` 和对应 PRD 文档
2. AI 确认 API 契约已存在于 `docs/api_contracts/`
3. AI 生成 `requirements.md` (需求拆解)
4. AI 生成 `design.md` (技术设计)
5. AI 生成 `tasks.md` (任务分解，含文件清单)
6. **人工审批**: 开发者 Review 并批准 tasks.md
### Phase 2: 编码 (Implementation)
1. AI 按照 tasks.md 逐文件实现
2. 每个文件必须包含 JSDoc/文档注释
3. 实现过程中遵循 `CLAUDE.md` 约束
4. 实现完成后执行自测闭环:
- 运行 Lint: `pnpm lint` 或 `mvn spotless:check`
- 运行类型检查: `pnpm type-check` 或编译检查
- 运行单元测试: `pnpm test:unit` 或 `mvn test`
- 如失败，AI 自动修复并重新测试，最多 3 轮
5. **安全自检**: AI 检查是否触碰安全红线
### Phase 3: 提交 (Commit)
1. AI 生成规范 Commit Message，关联需求编号
2. AI 生成 PR 描述，包含变更摘要和测试报告
3. **人工审批**: 提交 PR 等待 Code Review
### Phase 4: 验证 (Validation)
1. CI 自动执行全链路门禁
2. 人工 Code Review (架构审查 + 业务逻辑审查)
3. 通过后合并到主分支
### Phase 5: 部署 (Deployment)
1. CD 自动触发 Staging 部署
2. 运行 Smoke Test 和 E2E Test
3. 人工审批生产部署
4. 金丝雀发布 → 监控验证 → 全量发布
### Phase 6: 监控 (Monitoring)
1. 部署后 30 分钟内密切监控错误率和延迟
2. 对比部署前后业务指标
3. 异常时自动回滚或人工介入SOP-002: 缺陷修复
markdown
## 触发条件
收到缺陷报告 (Bug Ticket)
## 执行步骤
### Phase 1: 分析 (Analysis)
1. AI 读取缺陷描述和复现步骤
2. AI 分析日志和链路追踪数据
3. AI 定位根因，生成分析报告
### Phase 2: 修复 (Fix)
1. AI 编写回归测试 (先失败，后通过)
2. AI 实施修复
3. AI 执行自测闭环
4. AI 检查是否引入新的回归风险
### Phase 3: 验证 (Validation)
1. 回归测试通过
2. 相关集成测试通过
3. Code Review 通过
4. 部署到 Staging 验证
### Phase 4: 复盘 (Post-mortem)
1. 记录缺陷根因
2. 更新 Runbook 或测试用例
3. 如为系统性问题，更新 `CLAUDE.md` 防止复发SOP-003: 重构
markdown
## 触发条件
技术债务清理或架构升级
## 执行步骤
### Phase 1: 评估 (Assessment)
1. AI 分析重构范围和影响面
2. AI 生成重构计划，明确保留行为清单
3. AI 确认测试覆盖率基线
### Phase 2: 实施 (Implementation)
1. AI 编写行为保留测试 (确保重构前后行为一致)
2. AI 逐步重构，小步提交
3. 每步执行全量测试验证
### Phase 3: 验证 (Validation)
1. 全量测试通过
2. 性能对比测试 (重构前后)
3. 代码复杂度降低验证11.3 AI 模型对抗审查机制
基于美团 31 万行代码重构实践，引入多模型对抗审查：
markdown
## 高阶模型审查低阶模型
- 使用高配模型 (如 Claude Sonnet / GPT-4) 作为 Judge Model
- 审查低阶模型 (如 GPT-3.5 / 本地模型) 产出的编码
- 重点审查: 架构合规性、安全红线、业务逻辑正确性
## 不同厂商模型对抗审核
- 使用不同厂商的模型互相审查对方的编码产出
- 通过差异化的模型能力形成互补
- 实测 CR 覆盖面更全，可发现单一模型的盲区
## 审查 checklist
- [ ] 是否遵循 `CLAUDE.md` 约束
- [ ] 是否触碰安全红线
- [ ] 是否有足够的测试覆盖
- [ ] 是否引入技术债务
- [ ] 性能是否有退化
- [ ] 是否破坏向后兼容12. 度量体系与持续改进
12.1 DORA 核心四指标
| 指标 | 定义 | 精英级阈值 | 测量方式 |
|---|---|---|---|
| 部署频率 (Deployment Frequency) | 单位时间内生产部署次数 | 按需 (每天多次) | CI/CD 平台统计 |
| 变更前置时间 (Lead Time for Changes) | 代码提交到生产运行的时间 | < 1 小时 | Git + CI/CD 数据 |
| 变更失败率 (Change Failure Rate) | 导致故障的部署占比 | < 5% | 故障系统关联部署 |
| 服务恢复时间 (Time to Restore) | 故障发生到恢复的时间 | < 1 小时 | 监控 + 事件管理 |
12.2 扩展效能指标
| 指标类别 | 指标名称 | 定义 | 目标 |
|---|---|---|---|
| 质量 | 缺陷逃逸率 | 生产环境发现的缺陷 / 总缺陷数 | < 10% |
| 质量 | 代码评审效率 | PR 创建到合并的平均时间 | < 4h |
| 质量 | 技术债务比率 | 技术债务故事点 / 总故事点 | < 15% |
| 效率 | AI 辅助编码占比 | AI 生成代码行数 / 总代码行数 | 跟踪趋势 |
| 效率 | 需求交付周期 | 需求提出到上线的平均时间 | < 1 周 |
| 效率 | 流水线执行时间 | CI 流水线平均耗时 | < 10min |
| 安全 | 漏洞修复时间 | 高危漏洞发现到修复的平均时间 | < 24h |
| 安全 | 安全扫描通过率 | 无高危漏洞的构建占比 | 100% |
| 可用性 | 系统可用性 | 年度可用时间占比 | ≥ 99.9% |
| 可用性 | MTTR (平均修复时间) | 故障发生到恢复的平均时间 | < 30min |
12.3 价值流度量
需求提出 → 需求评审 → 技术设计 → 编码 → 代码评审 → 测试 → 部署 → 上线 → 监控
│ │ │ │ │ │ │ │ │
└───────────┴──────────┴────────┴────────┴────────┴──────┴──────┴──────┘
价值流效率 = 增值时间 / 总周期时间
目标: 识别并消除等待浪费，提升流动效率12.4 持续改进机制
markdown
## 周度站会 (Stand-up)
- 回顾本周 DORA 指标
- 识别阻塞点和浪费
- 调整下周优先级
## 月度复盘 (Retrospective)
- 分析质量门禁失败原因
- 更新 `CLAUDE.md` 和约束规则
- 分享最佳实践
## 季度规划 (Quarterly Planning)
- 评估技术债务清理计划
- 更新架构决策记录 (ADR)
- 调整效能目标和度量体系
## 年度审计 (Annual Audit)
- 全面审查安全合规性
- 评估 AI 辅助效能提升 ROI
- 更新全链路规范模板13. 实施路线图与行动清单
13.1 四阶段实施路线图
Phase 1: 基础搭建 (Week 1-2)
├── 建立项目目录结构
├── 编写核心约束文件 (PRODUCT.md, CLAUDE.md, TEST.md, DEPLOY.md, OPS.md)
├── 配置本地提交前校验 (.pre-commit-config.yaml)
├── 搭建基础 CI 流水线 (Lint + Test + Build)
└── 团队培训与规范宣导
Phase 2: 流水线完善 (Week 3-4)
├── 完善 Harness Pipeline Templates
├── 配置安全扫描 (SAST, SCA, 容器扫描)
├── 配置制品晋级和签名
├── 搭建测试环境 (TestContainers / 沙盒)
└── 配置基础监控和告警
Phase 3: AI 集成 (Week 5-6)
├── 配置 AI 辅助编码规则 (Cursor Rules / Claude Prompt)
├── 建立 AI 工作流 SOP
├── 实施多模型对抗审查
├── 配置 AI 辅助测试 (Human-in-the-loop)
└── 建立 AI 生成代码的质量门禁
Phase 4: 度量优化 (Week 7-8)
├── 搭建 DORA 指标采集
├── 配置价值流可视化
├── 建立持续改进机制
├── 优化流水线性能 (缓存、并行)
└── 全面审计和合规检查13.2 行动清单 (Action Items)
立即行动 (本周)
- 在项目根目录创建
PRODUCT.md,CLAUDE.md,TEST.md,DEPLOY.md,OPS.md - 配置
.pre-commit-config.yaml(husky + lint-staged) - 建立分支策略:
main(保护) →develop→feature/*→ PR Merge - 配置基础 CI: Lint → Type Check → Unit Test → Build
短期行动 (本月)
- 搭建 Harness / GitHub Actions 完整流水线
- 配置 SonarQube / Codecov 代码分析
- 配置 Snyk / Trivy 安全扫描
- 建立 Staging 环境和自动化部署
- 配置基础监控 (Prometheus + Grafana)
中期行动 (本季度)
- 实施金丝雀部署和自动回滚
- 建立完整测试金字塔 (Unit + Integration + E2E + Contract + Performance)
- 配置 AI 辅助编码规范和审查流程
- 搭建 DORA 指标看板
- 完成灾备演练
长期行动 (本年度)
- 实现 AI 自主开发闭环 (需求 → 代码 → 测试 → 部署)
- 建立价值流管理平台 (VSM)
- 实现预测性维护和智能告警
- 通过安全合规认证 (等保 / ISO27001)
- 持续优化和迭代规范体系
附录
A. 模板速查表
| 项目类型 | 核心约束文件 | 关键门禁 | Harness 模板 |
|---|---|---|---|
| 前端 | CLAUDE.md (组件规范) |
Lint + Type Check + Coverage ≥ 80% | Frontend CD Template |
| 后端 | CLAUDE.md (安全红线) |
Test Coverage ≥ 80% + SonarQube | Java CI Template |
| 数据库 | CLAUDE.md (变更规范) |
SQL Lint + Sandbox 验证 | DB Migration Template |
| 全栈 | CLAUDE.md + PRODUCT.md |
前后端契约测试 + E2E | FullStack CI Template |
| AI 项目 | CLAUDE.md (模型规范) |
模型评估 + A/B 测试 | AI Model Deploy Template |
B. 工具链推荐
| 领域 | 工具 | 用途 |
|---|---|---|
| 需求管理 | Jira / Linear / Notion | PRD 管理和追踪 |
| API 设计 | Swagger / Stoplight | OpenAPI 契约管理 |
| 代码托管 | GitHub / GitLab / Gitee | 版本控制和 CI |
| CI/CD | Harness / GitHub Actions / GitLab CI | 流水线执行 |
| 代码质量 | SonarQube / Codecov | 静态分析和覆盖率 |
| 安全扫描 | Snyk / Trivy / OWASP ZAP | 漏洞检测 |
| 测试 | Vitest / Jest / Playwright / k6 | 各类测试执行 |
| 监控 | Prometheus + Grafana / Datadog | 可观测性 |
| 日志 | ELK / Loki | 日志聚合 |
| 链路追踪 | Jaeger / SkyWalking | 分布式追踪 |
| 密钥管理 | Vault / AWS Secrets Manager | 敏感信息存储 |
| 制品管理 | Harbor / Nexus / Artifactory | 镜像和包管理 |
C. 参考资源
- 美团: 用 Agent 评测思路管理 AI Coding
- Snowflake Cortex: 规范驱动开发
- Harness Engineering Best Practices 2026
- 2026 年研发效能平台对比
- DORA State of DevOps Report
文档维护 : 本规范为动态文档，建议每季度评审更新一次。
反馈渠道 : 通过 PR 提交改进建议，或直接修改对应域的.md约束文件。
AI 训练: 将本文档作为 AI 的上下文知识库，可显著提升 AI 辅助编码的质量和一致性。