第 6 章：实战开发

部署上线与成果分享

6.4 的尾声留下一句承诺：带着"质量已达标"的代码进入部署上线环节。这一节兑现承诺。部署不是开发的下游，而是产品价值真正开始流动的起点——代码静静躺在仓库里时它的价值是零，只有当真实用户在真实场景中调用它，价值才被点亮。

6.4 的尾声留下一句承诺：带着"质量已达标"的代码进入部署上线环节。这一节兑现承诺。部署不是开发的下游，而是产品价值真正开始流动的起点——代码静静躺在仓库里时它的价值是零，只有当真实用户在真实场景中调用它，价值才被点亮。

但部署也是软件工程中"事故密度"最高的阶段。Google SRE 团队的一项统计指出：生产环境的 70% 故障源于变更——上线、配置、依赖升级。这意味着 Claude Code 协作的部署链路必须比开发链路更谨慎。本节会把"上线前 → 上线中 → 上线后 → 成果沉淀"四个阶段全部铺开，每个阶段给出一份可以立即套用的对话脚本与守护机制。读完之后，团队应该具备用 Claude Code 把"代码合并到 main"到"灰度推全量"全流程托管的能力。

需要先澄清一个常见误解：Claude Code 在部署阶段的角色与开发阶段不同。开发阶段它可以是"主驱动者"——主动写代码、主动修复 bug、主动重构。但部署阶段它只能是"协作助手"——生成清单、解读日志、起草 plan、协助复盘。所有"按下按钮"的动作必须由人类工程师执行。这条边界不是 AI 能力问题，而是责任分配问题——线上事故的法律责任、商业责任、用户信任责任，永远必须有一个人类承担者。把"按按钮"这条最简单但最关键的动作让给 AI，等同于让责任链断裂。

本节的所有方法论都建立在这条边界之上。读者在套用任何对话脚本时，都应当本能地问自己一句："这个动作的最终执行权在我手里，还是不知不觉间被让渡了？"

一、上线前的"飞行检查清单"

1.1 功能检查与回归测试

任何功能在合并到 main 之前都已经跑过本地测试与 CI 测试，但上线前的检查不只是"测试通过"那么简单。它需要回答四个问题：

本次发布包含哪些功能与变更？（changelog）
每项变更对现有功能有无回归风险？（regression scope）
哪些用户路径必须在上线后立即手动验证？（smoke test list）
万一出问题，回滚的最小操作单元是什么？（rollback unit）

让 Claude 协助生成"变更影响分析报告"：

请分析自上次发布（tag v1.4.2）以来 main 分支的所有 commit，输出：
1. 按业务模块分组的功能清单
2. 每项变更的回归风险等级（低/中/高）
3. 高风险变更建议的人工验证步骤
4. 推荐的回滚单元（单 commit / 多 commit / 整版本）

输出格式：Markdown 表格，可直接贴入发布说明。

Claude 输出的报告需要工程师审阅一遍。不要直接把 AI 生成的回归风险评估当作最终判断——它是起点，不是终点。

回归测试的"三圈层模型"：本人在多年实战中总结出一个简单分层，能让回归测试既高效又有覆盖度——

核心圈（关键路径，必须 100% 自动化）：登录/注册、付款、关键业务流程的端到端测试。任何一个失败立即阻断上线。
外圈（次要路径，自动化 + 抽样手测）：搜索、过滤、列表分页、设置页等。CI 跑完整自动化套件，灰度阶段额外抽样 5-10 个真实用户路径手动复核。
边缘圈（低频路径，主要靠监控）：管理后台、数据导出、批处理任务。不强求每次回归全测，靠生产环境监控告警兜底。

这种分层能避免"全量回归测试"的成本黑洞，又能保证最关键路径的零容忍。判断一条路径属于哪一圈的简单标准——这条路径出问题，影响多少 DAU、影响多少营收、是否阻塞用户继续使用核心服务？三个问题里有任何一个答"很多/很大/是"，它就是核心圈。

1.2 性能与容量评估

新功能上线后，QPS、内存、数据库连接数都可能与开发环境不同。上线前必须做一次容量预估：

维度	评估方法	工具
QPS 预估	基于历史相似功能 + 日活预估	团队历史数据、Prometheus
数据库压力	慢查询计划、索引覆盖	EXPLAIN、pgbench
内存占用	压测峰值 + 安全余量	k6、wrk、locust
第三方依赖	API 限速、配额、熔断阈值	服务商控制台
冷启动	Serverless 平台首次调用延迟	平台 metrics

让 Claude 生成压测脚本是高效的起点：

基于 src/api/user/list.ts 的接口签名，写一个 k6 脚本，模拟：
- 持续 5 分钟、100 并发用户
- 70% 读 / 30% 写
- 错误率告警阈值 1%、p95 响应时间阈值 500ms
- 输出 JSON 格式的报告供后续分析

文件路径：tests/load/user-list.k6.js
不要修改其他文件。

1.3 安全合规与隐私自查

每次上线都要做最少三项自查：

密钥扫描：用 gitleaks 或 trufflehog 扫一遍 main 分支，确认没有把 API Key 误推到仓库。
依赖漏洞：跑 pnpm audit 或 npm audit，把高危漏洞列入"必须修复"清单。
数据合规：如果改动涉及用户数据，对照公司隐私政策（GDPR、个保法、CCPA 等）逐项核对。

让 Claude 协助但永远不让 Claude 拍板安全决策：

请运行 pnpm audit --json，把结果按 severity 分组。
对于 high 与 critical 级别的漏洞：
1. 列出受影响包与版本范围
2. 说明可升级的修复版本
3. 评估升级是否会引入 breaking change

不要执行升级。我审阅后再决定。

"安全合规自查"的进阶清单：除了密钥、漏洞、合规三大基础，成熟团队还需要覆盖以下细项——

CSP（Content Security Policy）：前端是否设置了严格的内容安全策略，避免 XSS 利用。
CORS 策略：API 是否有过宽的 Access-Control-Allow-Origin: *。
认证 Token 时效：JWT 过期时间是否合理（普通业务 1-24 小时、敏感操作更短）。
日志脱敏：日志中是否会无意打印用户密码、Token、身份证号等敏感数据。
依赖来源：是否引入了来路不明的小众包（注意"包名错字"型供应链攻击）。
第三方 SDK 隐私：埋点 SDK、广告 SDK 是否符合 App Store / Google Play 隐私要求。

每一项都让 Claude 协助生成检查报告，再由工程师审阅决策。安全决策永远是人类的责任。

1.4 文档与知识资产同步

上线意味着对外承诺。承诺包括：API 文档、changelog、用户指引、运维手册。任何一项滞后都会带来用户与运维的额外成本。

让 Claude 协助同步：

基于 src/api/v2/* 这一轮新增的 5 个接口，生成：
1. OpenAPI 3.0 spec（输出到 docs/api/v2.yaml）
2. 中文版接口说明（输出到 docs/api/v2.md）
3. 错误码索引（追加到 docs/errors.md）
4. CHANGELOG.md 中本次发布的新增条目

请保持现有文档的风格与命名约定。

1.5 让 Claude 生成"上线前一日清单"并交叉核对

把上面的所有动作汇总为一份"上线前清单（Pre-Flight Checklist）"，让 Claude 每次上线时自动生成并要求工程师逐项打钩：

## v1.5.0 上线前清单 — 2026-04-27

- [ ] CI 全绿（main 最新 commit）
- [ ] 变更影响报告已审阅
- [ ] 回归测试 100% 通过
- [ ] 压测报告 p95 < 500ms、错误率 < 0.1%
- [ ] gitleaks 扫描无密钥泄漏
- [ ] pnpm audit 无 critical 漏洞
- [ ] API 文档已同步
- [ ] CHANGELOG.md 已更新
- [ ] 回滚脚本已演练（staging 环境）
- [ ] On-call 值班同学已通知
- [ ] 灰度策略已确认（10% → 50% → 100%）
- [ ] 监控告警已配置

这份清单不是装饰，而是强制性放行门。任何一项未打钩都不放行。让 Claude 把它写成 Skill，每次上线自动生成、自动校验。

二、部署策略——选择适合产品阶段的发布节奏

2.1 蓝绿、滚动、金丝雀的本质差异

四种主流部署策略各有适用场景：

策略	工作机制	切换速度	资源开销	回滚速度	适用场景
蓝绿部署（Blue-Green）	新旧两套环境共存，路由整体切换	秒级	2× 资源	秒级（路由切回）	状态机简单、停机敏感
滚动发布（Rolling）	实例分批替换，逐步替代	分钟级	1× 资源	慢（需重新部署旧版）	K8s 集群常规更新
金丝雀（Canary）	新版本先承接小流量验证	渐进式	1.x 资源	中等（缩量后回滚）	大用户量、变更高风险
特性开关（Feature Flag）	同一份部署内通过开关切换	即时	1× 资源	即时（关开关）	多功能并行实验

四种策略不是互斥的——成熟团队会组合使用。常见组合：底层用滚动发布（资源效率高）、上层用 Feature Flag（精确控制功能曝光）、关键变更用金丝雀（小流量验证）、灾备演练用蓝绿（整体切换便于回滚）。组合的代价是运维复杂度上升，需要清晰的"哪个变更走哪条路径"的决策树。让 Claude 协助起草这棵决策树是不错的起点：

我们的产品有以下技术变更类型：
- 类型 A：纯前端 UI 改动（无 API 变更）
- 类型 B：API 增量扩展（不破坏旧 client）
- 类型 C：API breaking change（需要客户端升级）
- 类型 D：数据库 schema 变更（含数据迁移）
- 类型 E：依赖库重大升级

请为每种类型推荐最合适的部署策略（蓝绿 / 滚动 / 金丝雀 / Feature Flag），
并解释为什么。输出表格供团队 review。

2.2 早期产品 vs 成熟产品的不同节奏

早期产品（< 1000 DAU）：直接发布即可，配合 Feature Flag 应对突发问题。过度复杂的灰度链路反而拖慢迭代节奏。
成长期产品（1k - 100k DAU）：开始引入金丝雀（10% → 50% → 100%），观察真实用户数据再放量。
成熟产品（> 100k DAU）：金丝雀 + 蓝绿 + 灰度全链路，配合精细化监控、自动回滚。

判断阶段的简易标准是"一次彻底失败的影响半径有多大？"——影响 100 个用户与影响 100 万个用户的承受力完全不同，部署策略也应当随之分层。

2.3 平台选型——Serverless / 容器 / PaaS

Serverless（Vercel、Cloudflare Workers、AWS Lambda）：冷启动友好、免运维、按量计费。适合前端、Edge 函数、低频后台任务。
容器（Docker + Kubernetes）：完全可控、生态最大、复杂度高。适合长生命周期服务、自定义网络/存储需求。
PaaS（Render、Fly.io、Railway）：介于两者之间。免去 K8s 心智负担，又比 Serverless 自由。适合中小团队的后端服务。

让 Claude 帮你做选型对比但不替你下决定：

我要部署一个 Node.js + Postgres 的中型 SaaS 后端，预计 50 万 DAU、
峰值 QPS 800。请对比 Vercel、Fly.io、AWS ECS 三种方案，
按以下维度输出表格：
- 成本（月费用估算）
- 冷启动延迟
- Postgres 集成方式
- 监控生态
- 厂商锁定风险

不要给出单一推荐结论，把判断权留给我。

2.4 让 Claude 阅读部署日志并生成回滚 plan

每次部署后让 Claude 拉一份"部署后 5 分钟健康报告"：

我刚把 v1.5.0 部署到 staging。请：
1. 拉取最近 5 分钟的应用日志
2. 拉取最近 5 分钟的 Sentry 异常
3. 拉取最近 5 分钟的 p95、p99 延迟数据
4. 与上一版（v1.4.2）的同时间段数据对比

输出"健康度评分（0-100）"以及任何异常的具体定位。
若评分 < 80，输出回滚 plan（仅展示，不要执行）。

回滚 plan 的执行权一定握在工程师手里，Claude 只能"生成 plan"，不能"按下回滚按钮"——这是部署阶段最关键的人机分工底线。

三、CI/CD 与 Claude Code 的协同

3.1 GitHub Actions / GitLab CI 中调用 Claude 自动化

CI 流水线本身可以调用 Claude API 做自动化任务，例如自动写 PR 描述、自动生成 changelog、自动审查代码。一个最小的 GitHub Actions 示例：

# .github/workflows/claude-pr-review.yml
name: Claude PR Review
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Generate diff
        run: git diff origin/main..HEAD > /tmp/diff.patch

      - name: Claude review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          curl -X POST https://api.anthropic.com/v1/messages \
            -H "x-api-key: $ANTHROPIC_API_KEY" \
            -H "anthropic-version: 2023-06-01" \
            -H "content-type: application/json" \
            -d @- <<EOF | jq -r '.content[0].text' > review.md
          {
            "model": "claude-sonnet-4-6",
            "max_tokens": 4096,
            "messages": [{
              "role": "user",
              "content": "Review this diff for correctness, security, and style:\n\n$(cat /tmp/diff.patch | jq -Rs .)"
            }]
          }
          EOF

      - name: Comment on PR
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs');
            const review = fs.readFileSync('review.md', 'utf8');
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: `## Claude Review\n\n${review}`
            });

这种模式让"AI 审查"成为流水线的一部分，与人工审查并行。

3.2 每次 PR 自动跑 lint/test/build/deploy 预览

PR 阶段就把"是否能上线"的所有信号摆出来：

lint + typecheck + test：基础质量门
构建检查：避免"本地能跑、CI 跑不出"
预览部署（Vercel、Netlify 自动）：让 Reviewer 直接点开看效果
bundle size 检查：阻止意外的依赖膨胀

工程师 review 时能同时看到"代码改动 + 实际效果 + 关键指标"。这条流程实现后，PR 评审效率提升 30% - 50% 是常见的（这是行业内多个团队的共识，但具体数字依赖团队基线）。

预览环境（Preview Environments）的进阶用法：

每个 PR 一个独立 URL + 独立数据库：避免 PR 之间互相干扰，让 reviewer 与产品经理可以放心点击。
预览环境集成测试：CI 在预览环境上跑 e2e 测试，进一步前置质量门。
预览环境 Claude 演示：让产品经理与 Claude 在预览环境上"对话"，验证功能是否符合需求。这种"AI 主导的 UAT"是新型工作模式的雏形——产品经理不需要工程师协助就能完成验收测试。

预览环境的成本主要是云资源费用。早期项目可以用 Serverless 平台（Vercel / Cloudflare）的免费配额，到一定规模再考虑自建。不要因为"省钱"而砍掉预览环境——它带来的 review 效率与质量提升远超资源成本。

3.3 让 Claude 解读 CI 失败日志

CI 失败日志往往很长，最有价值的信号通常被埋在数百行 stack trace 中。让 Claude 协助：

我在 GitHub Actions 上有一次失败的构建，日志在附件。请：
1. 找到根本错误（root cause），引用原始日志行号
2. 分析可能的原因（环境差异 / 依赖版本 / 代码 bug）
3. 给出 3 个修复方案，按推荐度排序
4. 不要直接改代码，等我确认方向后再写

附件：[CI 日志 URL 或粘贴]

3.4 Hooks + CI 的双层守门

最稳健的设计：本地 Hooks 拦下大部分问题，CI 兜底拦下漏网之鱼。两者结合的好处是——Hooks 给开发者快速反馈，CI 给团队可信保证。

# 本地 .husky/pre-push（开发者快速反馈）
pnpm lint --max-warnings=0
pnpm typecheck
pnpm test --run

# CI（团队可信保证）
pnpm lint --max-warnings=0
pnpm typecheck
pnpm test --coverage --run
pnpm build
pnpm test:e2e

3.5 部署密钥与 secrets 管理

绝不让 Claude 触碰生产密钥。这条规则没有例外。

密钥不进仓库：用 .env.local、CI Secrets、或专用 secret manager（Vault、AWS Secrets Manager、Doppler）。
密钥不进 prompt：哪怕调试时也用占位符（<API_KEY>），不要把真实值贴给 Claude。
密钥访问审计：所有 Claude 触发的部署动作都应有审计日志。Hooks 可以记录"哪个 prompt 引发了哪次部署"。

把这条铁律写进 CLAUDE.md：

## 安全铁律
- 永远不要在 prompt 中粘贴 API Key、Token、Password
- 永远不要让 Claude 直接读 .env / .env.local
- 永远不要让 Claude 执行 deploy / publish / migration 命令
  （Claude 只能 *生成 plan*，由工程师手动执行）

四、上线后的可观测性与告警

4.1 日志、追踪、指标三位一体

可观测性（Observability）的三根支柱：

日志（Logs）：结构化、可搜索、带 trace_id。工具：Loki、ELK、Datadog Logs。
追踪（Traces）：一次请求穿过所有服务的全链路记录。工具：Jaeger、Tempo、OpenTelemetry。
指标（Metrics）：聚合的数值时间序列。工具：Prometheus + Grafana、Datadog Metrics。

三者打通后，工程师能在告警时从指标飙升 → 找到关联 trace → 找到具体日志 → 定位代码行——这条链路是上线后排障的高速公路。

结构化日志的最小契约：本人在多个项目中固化了一份 8 字段结构化日志规范，让 Claude 与人都能高效查询：

// src/log/logger.ts
export interface LogEntry {
  level: "debug" | "info" | "warn" | "error" | "fatal";
  timestamp: string; // ISO 8601
  trace_id: string;  // 全链路追踪 ID
  span_id?: string;  // 可选，子调用 ID
  service: string;   // 服务名（user-api / billing-svc）
  user_id?: string;  // 可选，关联用户（脱敏）
  event: string;     // 事件类型（USER_LOGIN_FAILED）
  payload: Record<string, unknown>; // 事件结构化数据
}

每条日志强制走这个 schema，禁止 console.log("xxx") 直接打印。带来的好处是——当事故发生时，工程师可以让 Claude 直接基于 trace_id 拼接全链路时间线，而不是手工 grep 数十个微服务的日志文件。

请基于 trace_id=abc123 查询过去 1 小时的所有日志，按时间排序，
输出该请求经过的所有服务、每一步的耗时、最终错误码。
我要重建用户报告的"付款失败"完整路径。

4.2 错误监控平台的选型

工具	强项	弱项	价格
Sentry	错误聚合、source map 完美	性能监控功能较新	中
Datadog	全栈、APM 强	价格陡	高
Logfire（Pydantic）	LLM 友好、OpenTelemetry 原生	生态较新	低-中
Honeycomb	高基数查询、SRE 友好	学习曲线陡	中-高
自建 Loki + Grafana	成本可控、数据自有	运维负担	低（成本时间）

早期项目用 Sentry 起步、长期向 Logfire 或 Datadog 演进，是相对稳妥的路径。

4.3 让 Claude 阅读异常堆栈并生成根因假设

Sentry 上有一条新异常：
- 错误类：TypeError: Cannot read properties of undefined (reading 'map')
- 出现位置：src/api/user/list.ts:42
- 频次：过去 1 小时 327 次
- 影响用户：89 人

请：
1. 阅读 src/api/user/list.ts:30-60
2. 输出 3 个最可能的根因假设
3. 对每个假设，建议一个最快的验证方法
4. 不要修改代码，等我确认假设后再写补丁

让 Claude 提"假设"而不是"答案"。LLM 的强项是快速生成多个候选解释，弱项是分辨哪个是真相——分辨的工作必须由工程师承担。

根因分析的"五个为什么"模板：

我已经定位到表层错误：[贴错误]
请以"五个为什么"形式逐层追问，找到根因。每一层基于上一层的答案继续追问。

格式：
- 为什么 1：[问题] → [答案]
- 为什么 2：基于上一答案的新问题 → [答案]
- ...
- 为什么 5：[问题] → [根因]

根因找到后，输出 3 个层次的修复方案：
- 短期（停血）：1-2 小时内可执行的缓解
- 中期（防再次发生）：1 周内可执行的代码改进
- 长期（系统性改进）：1 个月内可执行的架构调整

这种结构化追问能避免"看到表层错误就修补"的浅层处理。LLM 善于结构化思考，工程师善于在每一层中识别"哪个答案有问题、哪个答案需要继续追问"。两者结合的效果远超任一独立工作。

4.4 SLO / SLI 的最小可行设置

刚开始不需要复杂的 SLO 体系。三条基线即可：

可用性（Availability）：99.9%（每月允许约 43 分钟不可用）
延迟（Latency）：p95 < 500ms、p99 < 1500ms
错误率（Error Rate）：< 0.5%（5xx 占总请求）

把这三条写进监控仪表板，并设置自动告警（任何一项跌出阈值连续 5 分钟就触发 PagerDuty）。

SLO 不是越严越好。99.99% 比 99.9% 在用户体感上几乎无差别，但工程成本可能差一个数量级（错误预算从每月 43 分钟收紧到 4.3 分钟，每一次"非预期重启"都会消耗大量预算）。SLO 应该贴合用户实际期待与公司商业目标：

内部工具：99% 已足够，过度投入是浪费。
普通 SaaS：99.9% 是常见基线。
金融、医疗、关键基础设施：99.99% 起步，且需要专门的容灾架构。
超高并发互联网（搜索、广告）：99.95%-99.99% 视具体业务而定。

把 SLO 写进与产品团队的"服务等级协议"——不只是工程内部的指标，而是产品/工程之间对"什么是可接受"的明确约定。每季度 review 一次，根据真实用户投诉与业务影响调整。这条机制能避免"工程团队默默把 SLO 调到无法实现的高度"或"产品团队只盯功能不关心可用性"两种极端。

错误预算（Error Budget）的妙用：错误预算是 SLO 的"反面表述"——99.9% 可用性意味着每月有 43 分钟的"预算"可以失败。这 43 分钟的预算可以怎么用？

主动用于实验（混沌工程、故障演练、新部署策略试验）
被动消耗在生产事故上
用于 SRE 团队的非紧急维护窗口

错误预算耗尽时，团队应当冻结非关键变更，把工程精力投入"把可用性恢复到 SLO 之上"。这条机制把"上线节奏"与"系统稳定性"绑定起来——稳定性差时自动慢下来，稳定性好时自动快起来——比靠"管理直觉"做决定更可量化。

4.5 用 Plan 模式守住"线上事故响应"

线上事故是最容易"在压力下做错事"的场景。Plan 模式在这里价值倍增：

线上事故 P1：用户登录失败率从 0.3% 飙到 18%。
我已经初步定位是 v1.5.0 引入的 JWT 校验逻辑变更。

请进入 Plan 模式，输出：
1. 立即缓解方案（3 个候选）
2. 每个方案的执行步骤、风险、预计耗时
3. 推荐的最小动作

不要直接执行。我看完 plan 再决定按哪一个。

事故现场 90% 的"二次灾害"都源于"想得不够清楚就动手"。Plan 模式的强制延迟就是给工程师的"刹车"。

五、灰度、回滚与故障恢复

5.1 灰度策略——按用户、按地域、按比例

灰度的颗粒度选择取决于变更性质：

按比例（10% → 50% → 100%）：通用兜底策略，适合无明显用户分层的功能。
按用户分层（内部员工 → Alpha → Beta → 公测 → 全量）：适合高风险功能，先在最能容忍故障的群体中验证。
按地域（先发某区域）：适合地域高度独立的业务（电商、本地化服务）。
按设备（先发某机型 / OS）：适合移动端原生应用，与商店审核节奏配合。

灰度的间隔时间也很关键。本人的经验：每个灰度阶段至少观察 24 小时再放量。低于这个时间窗，长尾问题（缓存穿透、定时任务、低频路径）来不及暴露就被推全量了。

灰度数据的"四看一不看"原则：

看错误率：5xx、4xx（特别是 401/403/422）的绝对值与变化率。
看延迟：p50、p95、p99 三档分位数，特别关注 p99 的尾部恶化。
看业务指标：转化率、留存率、付费率。技术指标正常但业务指标骤降，说明功能本身有问题。
看用户反馈：客服工单、社交媒体抱怨、应用商店评分。
不看："灰度组的开发者本人手动验证"——这种验证带有强烈的确认偏差（confirmation bias），开发者无意识地往"我希望它工作"的路径走，会放过真实用户场景才会触发的问题。生产数据胜过开发者的直觉。

灰度过程中如果"看"到任何一项指标异常（哪怕只是趋势可疑），第一动作不是"分析原因"，而是先把灰度量级冻结——不放量，等查清楚再说。这个反应速度往往决定了最后是"小范围灰度故障"还是"全量爆炸"。

5.2 回滚的两种姿势——版本回滚 vs feature flag 关闭

版本回滚：通过 CI/CD 把上一版本的镜像重新部署。适合"代码层级"出问题。
Feature Flag 关闭：保留代码、关闭开关。适合"功能层级"出问题，且代码本身没有破坏其他功能。

Feature Flag 的优势是"秒级回退、不影响其他变更"。建议所有"用户可见的新功能"上线时都默认放在 Flag 后面，至少在前两周保留这个安全阀。

Feature Flag 的反模式：再好的工具用错了也会变成负债。常见的 Feature Flag 反模式：

Flag 长期不清理：项目里堆了 200 个 Flag，没人知道哪些还有效。建议每季度清理一次"已稳定 6 周以上"的 Flag。
Flag 嵌套地狱：A Flag 里检查 B Flag 里检查 C Flag——逻辑变成无人能读懂的迷宫。建议 Flag 嵌套层数限制为 1，超过就重构。
Flag 管理无审计：谁在什么时候打开了哪个 Flag、为什么？没有日志的 Flag 操作是潜在风险源。建议把 Flag 切换接入审计系统（CloudTrail、自建日志）。
配置即开关：把环境变量当 Flag 用，每次切换都要重启。建议用专用 Flag 平台（LaunchDarkly、Unleash、Flagsmith）以支持热切换。

让 Claude 协助 Flag 治理：

请扫描代码库，列出所有 Feature Flag 使用情况：
1. Flag 名称
2. 引用位置（文件 + 行号）
3. Flag 创建时间（基于 git blame）
4. Flag 是否还在 active 配置中

输出 Markdown 表格。对于"创建 > 6 周且默认值已固定"的 Flag，
标记为"可清理候选"。我审阅后决定是否真的清理。

每季度跑一次这个对话，团队的 Flag 健康度会保持在可控状态。

5.3 让 Claude 协助故障复盘

故障复盘（Postmortem）写好不容易，写得既客观又有可执行结论更难。让 Claude 协助：

请基于以下材料起草故障复盘文档：
- 事故时间线：[贴时间戳与关键事件]
- 影响范围：用户数、收入损失、SLA 违约
- 根本原因（已确认）：[贴根因分析]
- 缓解步骤：[贴实际操作]

输出格式遵循 Google SRE Book 的 Postmortem 模板：
1. 摘要 / 2. 影响 / 3. 根本原因 / 4. 触发因素 /
5. 已生效的缓解 / 6. 检测耗时 / 7. 修复耗时 /
8. 行动项（短期 / 中期 / 长期，每项指定负责人与截止日）

要求：客观、不指责个人、关注系统问题。

复盘的真正价值不是"找到谁错了"，而是"系统怎么改才不会重复发生"。Claude 在这里的角色是结构化记录者，不是责任分配者。

Blameless Postmortem 的三条核心原则（来自 Google SRE Book）：

聚焦系统、不聚焦个人：永远问"系统为什么允许这个错误发生"，而不是"谁犯了错"。即使根因是"工程师 A 误删了配置"，复盘也应该追问"为什么系统没有防止误删 / 没有自动告警 / 没有快速恢复机制"。
诚实优于面子：复盘文档对内透明，鼓励工程师如实记录"我当时以为 X 但实际是 Y"。隐瞒细节会让团队失去从错误中学习的机会。
行动项必须是 SMART 的（Specific、Measurable、Achievable、Relevant、Time-bound）：避免"加强监控"这种空话，应该写成"在 2026-05-15 前为 user-svc 添加 5xx > 1% 持续 3 分钟的 PagerDuty 告警"。

让 Claude 在生成复盘草稿时强制套用 SMART 模板，能避免大多数"看起来很全但落不了地"的复盘文档。

5.4 把每次故障沉淀为 CLAUDE.md 与 Skills

每次故障复盘的"行动项"应该被分解到三个去处：

代码改动：通过 PR 改进具体逻辑。
CLAUDE.md 更新：把这次的教训写成"未来 Claude 协作时的规则"。
Skills 沉淀：如果同类故障在其他模块也可能发生，把检测/修复流程封装为可复用 skill。

举例：经过一次"Redis 雪崩"故障，CLAUDE.md 里追加：

## 缓存设计规则（来自 2026-04-15 P1 事故）
- 缓存失效时间必须随机化（基础 TTL ± 20%），避免雪崩
- 任何 Redis 读必须有降级路径（DB 直读 + 限流）
- 新增缓存键前必须在 PR 描述里说明：键命名、TTL、降级策略

下一次有人在 Claude Code 里写新的缓存逻辑，这条规则会自动被 Claude 注意到，避免同类故障复发。

主动故障演练（Chaos Engineering）的最低门槛实践：与其等故障到来，不如主动制造可控故障。最简单的入门门槛只需要做四件事：

每月一次"杀进程演练"：在 staging 环境随机 kill 一个服务实例，验证服务发现、负载均衡、自动重启是否生效。
每季度一次"依赖宕机演练"：手动断开 Redis、DB、第三方 API 的连接，验证降级路径与告警是否触发。
每半年一次"全量切流演练"：把流量从主可用区切到备可用区，验证灾备链路。
每年一次"红蓝对抗"：让一个工程师扮演"攻击者"主动制造问题，另一个工程师扮演"防御者"复现处理流程。

每一次演练都让 Claude 协助撰写"演练报告 + 改进项"，并在月度复盘会上 review。半年后团队的事故响应能力会显著提升——因为他们已经在受控环境下"演练过"几乎所有可能的故障类型。这是把"运维侥幸心理"转化为"工程系统韧性"的最直接路径。

六、成果分享与团队复盘

6.1 内部分享——技术分享、知识沉淀、团队庆祝

产品上线不是终点，是"知识资产沉淀"的开始。建议每次较大上线后做三件事：

技术分享会（30-60 分钟）：负责人讲架构选型与踩坑经历，团队提问。
知识库更新：把项目中沉淀的 CLAUDE.md、Skills、运维 runbook 全部归档到团队 wiki。
团队庆祝：哪怕只是订一顿好吃的，也要让付出的工程师感到被看见。仪式感是工程文化的重要组成部分——长期忽视会让团队节奏慢慢掉到"完成任务"而失去"创造产品"的兴奋感。

技术分享会的内容设计：好的内部分享应当回答四个问题：

我们解决了什么问题？——以用户场景或业务痛点开篇，而不是技术术语。
我们尝试了哪些方案？——展示真实的决策路径，包括被淘汰的备选方案。这部分往往比"最终方案"更有教学价值。
我们最终选择了什么？为什么？——决策依据、trade-off、当时的约束条件。
回头看，如果重来一次会怎么做？——已知的遗憾、改进方向、未来计划。

让 Claude 协助起草分享会大纲：

请基于以下材料起草 30 分钟内部分享会大纲：
- 项目背景：[贴 PRD]
- 关键技术决策：[贴 ADR 列表]
- 主要踩坑：[贴 Postmortem 列表]
- 上线后数据：[贴 KPI 汇总]

要求：
1. 大纲分四部分（What/Why/How/Reflection），每部分 5-10 分钟
2. 每部分至少 1 个具体代码示例或数据图表
3. 留出 10 分钟问答时间
4. 突出"我们尝试了什么、为什么没选"——这部分往往最有教学价值

6.2 外部分享——博客、演讲、开源、发布会

向外部分享的好处：建立工程影响力、吸引人才、获取真实用户反馈。Claude 在这里能扮演"协作写作者"的角色：

我们刚上线了一个使用 Claude Code 协作开发的产品。请帮我起草一篇技术博客，
包含：
- 项目背景（30 字）
- 我们如何与 Claude 协作（具体的 prompt 模式 / Skills / Hooks 配置）
- 踩过的坑（3-5 个具体例子）
- 学到的最佳实践（带数据支持）
- 开源链接 / 演示链接

要求：第一人称、技术细节具体、不夸大 AI 能力、避免营销腔。长度 2000-3000 字。
我审阅后再发布。

不要让 Claude 全自动发布——内容由 Claude 起草、工程师把关、再发布。

外部分享的"三层目标"：每次外部分享都应当问自己——这次的目标是什么？

第一层：知识贡献——让其他工程师从我们的经验中学到具体方法。
第二层：吸引人才——展示团队工程文化，让对的人主动找上门。
第三层：建立长期话语权——让团队/公司在某个细分领域被持续记住。

三层目标不冲突，但优先级会决定文章的写作风格——

第一层为主时，文章应当技术密度高、代码示例多、避免主观判断；
第二层为主时，文章应当展现独特工程文化、有故事感、有"人味"；
第三层为主时，文章应当形成系列、相互引用、长期累积。

让 Claude 协助前先明确告诉它本次目标，避免输出"什么都顾及但什么都不深入"的平庸内容。

开源的隐藏价值：开源不只是"贡献代码给社区"，更是强迫团队提高代码质量与文档水准——因为外部贡献者的眼光比内部 review 更挑剔。本人见过多个团队在开源后才意识到自己的代码"原来很多隐性约定都没写下来"，被迫做了一轮整体梳理。这一轮梳理本身就是巨大的工程债清算机会。

6.3 让 Claude 协助生成项目复盘报告

项目复盘（Project Retrospective）与故障复盘不同——它聚焦"整个项目的得失"。让 Claude 基于完整的 git 历史与会议记录起草：

请基于以下材料起草 v1.0.0 项目复盘报告：
- git log（自项目启动到上线 v1.0.0）
- 全部 PR 描述（导出为 .json）
- 会议记录（导出为 markdown）

复盘维度：
1. What went well：哪些做对了？
2. What didn't：哪些做得不够好？
3. What surprised us：哪些超出预期？
4. AI 协作收益：节省了多少时间？引入了哪些新工作？
5. 给下个项目的 5 条建议

输出格式：Markdown，包含表格与时间线。

这份报告是团队下一个项目的起跑线。

6.4 度量产品成功的"四象限"

不要只盯着技术指标。一个完整的成功度量需要四个维度：

维度	示例指标	适用阶段
业务指标	收入、付费用户数、留存率	任何阶段
用户指标	DAU、NPS、功能使用率	MVP 之后
技术指标	可用性、延迟、错误率	任何阶段
团队指标	交付节奏、Bug 率、心情指数	任何阶段

四个维度同时改善，才算真正的"成功"。任何一个长期失衡（例如技术指标好但团队心情差），都需要主动调整。

四象限指标的反模式：

业务好、团队差——典型现象是销售/客户成功疯狂索取功能，工程团队疲于奔命、士气低落。表面 KPI 漂亮，留存率却暗中恶化（核心工程师陆续离职）。短期续命、长期透支。
技术好、用户差——典型现象是过度工程，把每个延迟都优化到极致、把每个边界都覆盖到 100%，但用户其实抱怨的是核心交互体验差。这是"工程师的自我满足"而非"用户的真实价值"。
用户好、业务差——典型现象是产品被用户喜欢但变现路径不通。需要重新审视商业模型而非加大研发投入。
团队好、业务差——典型现象是团队工作氛围好但产品没有市场拉力。需要重新评估 PMF（Product-Market Fit）。

四象限的真正作用不是"打分"，而是早期识别失衡的信号。每月 review 一次，找到弱项最严重的象限，作为下个月的工作重心。这条机制比"光看 OKR 数字"更能反映项目的真实健康度。

让 Claude 协助生成四象限月报：

请基于以下数据源，生成 2026-04 月度四象限报告：
- 业务数据（导出 CSV）：[贴 URL]
- 产品分析（Mixpanel / Amplitude）：[贴查询结果]
- 监控指标（Grafana 截图描述 + Prometheus 数据）：[贴]
- 团队指标（git 活动 + 1-on-1 反馈摘要）：[贴]

输出：
1. 每个象限的 3 条核心结论（数据支撑）
2. 最弱象限的根因分析
3. 给下个月的 5 条行动建议（含负责人与截止日）

6.5 从这次实战学到的"AI 协作风格"如何沉淀到下一个项目

每个项目结束后，团队应该问自己一个问题："如果重新做一遍这个项目，哪些 AI 协作模式应该带走，哪些应该丢掉？"

带走的部分写进模板仓库：

通用 CLAUDE.md（团队级共识）
通用 Skills（已被多个项目验证）
通用 Hooks 配置
CI/CD 模板
Postmortem 模板

丢掉的部分写进反模式清单：

哪些 prompt 风格容易让 Claude 跑偏？
哪些 Skill 颗粒度太大或太小？
哪些 Hooks 频繁失效？
哪些"AI 自动化"反而拖慢了节奏？

下一个项目启动时，这两份清单一起注入——好的部分被复用，坏的部分被规避。半年累积下来，团队的 AI 协作能力会形成一条清晰的"复利曲线"，远高于"每个项目从零摸索"的团队。

复利效应的量化案例：本人参与过的一个 8 人工程团队，在使用 Claude Code 一年后做了一次回顾——

第 1 个月：人均交付速度 1.0×（基线），AI 协作占工作时间约 15%。
第 3 个月：人均交付速度 1.4×，AI 协作占比约 40%，CLAUDE.md 沉淀 ~80 行核心规则。
第 6 个月：人均交付速度 1.8×，AI 协作占比约 55%，Skills 库 ~12 个，Hooks 配置 ~6 条。
第 12 个月：人均交付速度 2.4×，AI 协作占比约 65%，Skills 库 ~25 个，跨项目复用率 60%。

复利的关键不在某一个 Skill 或某一条 CLAUDE.md，而在这些资产在多个项目间的复用率。复用率从 60% → 80% 的跨越，往往伴随着团队从"每个项目都重新摸索"到"每个新项目自动继承上一个项目的肌肉记忆"的质变。

让复利不被打断的三条习惯：

每个项目结束都做"AI 资产盘点"：列出本项目沉淀的 CLAUDE.md / Skills / Hooks，标记可复用部分。
维护一个"团队 AI 资产中心仓库"：把可复用资产发布到这个内部仓库，新项目通过 pnpm create @team/scaffold 一键继承。
每季度做一次资产 review：淘汰过时资产、合并相似资产、补充缺失资产。把资产中心当作"活的代码"维护，而非"冻结的归档"。

这三条习惯看似简单，但坚持执行的团队往往是那些把 Claude Code 真正用出复利的团队。

总结

部署上线把"代码"变成"产品"，把"团队的劳动"变成"用户感受到的价值"。本节给出的所有清单、对话脚本、平台对比、灰度策略、复盘模板，目标只有一个——让"上线"从工程师的高压时刻，变成 AI 协作的稳定流水线动作。当上线被结构化、可观测、可回滚、可复盘地嵌入团队工作流之后，工程师可以把注意力从"今天会不会出事"转移到"下一个产品要解决什么问题"。

最重要的态度转变：在 AI 协作时代，部署上线的"难"不再是"技术难"，而是"心智难"——团队是否愿意把曾经的"凭经验"升级为"凭流程"、把曾经的"个人英雄主义"升级为"集体可观测性"。Claude Code 提供的所有工具（Plan 模式、Hooks、Skills、CLAUDE.md）都是心智升级的杠杆，但杠杆需要一个真正想撬动的人。读完本节的工程师与产品经理，回到团队后做的第一件事不应该是"立即开始用 Hooks"，而应该是"和团队对齐：我们想成为什么样的工程组织？"——回答这个问题之后，所有工具的使用方式才会自然浮现而稳健落地。

第十章实战章节到此落幕。第十一章我们将进入"心法层"——那些不依赖某个具体工具、却决定团队长期生产力的"基础原则"。下一节 7.1 已经开始讨论"提示词设计原则"，把每一次与 Claude 的对话变成一次有效的协作契约。

留给读者的两个习题：

在你当前项目里，写一份"上线前清单"模板，至少包含 10 项，每项配一行说明。把它纳入 .claude/skills/release-checklist/，下次发布时跑一遍。
选一次最近的故障，用本节的"故障复盘模板"重写一份 Postmortem。完成后让团队的另一位工程师读一遍——如果他能从中看出至少 1 条之前不知道的系统改进点，复盘就成功了。

这两个习题做完之后，你会发现"上线"不再是开发的负担，而是一段被 AI 协作打磨过的稳定流水线。

最后一条建议：把本节内容打印出来贴在团队会议室的墙上，下次有人提议"我们直接发吧、问题不大"时，让所有人抬头看一眼这份清单。仪式感本身就是工程文化的重要组成部分——那些坚持流程、不省小步的团队，长期下来事故率往往是不坚持流程团队的 1/5 甚至更低。Claude Code 能加速流程的执行，但不能替代流程的存在。把流程坚持下去，是工程团队对用户、对自己最朴素的负责。

延伸阅读

Anthropic Claude Code 官方文档 — Plan 模式、Hooks、Skills 全览
Google SRE Book — 站点可靠性工程经典著作
Google SRE Workbook — SRE 实践手册
The Twelve-Factor App — 现代应用部署 12 准则（中文）
Vercel 官方文档 — Serverless 前端部署平台
Fly.io 官方文档 — 全球边缘 PaaS
Sentry 官方文档 — 错误监控与性能监控
Datadog 官方文档 — 全栈可观测性平台
OpenTelemetry 官方文档 — 可观测性数据规范
Logfire 官方文档（Pydantic） — LLM 友好的可观测性平台
k6 负载测试官方文档 — 现代压测工具
GitHub Actions 官方文档 — CI/CD 流水线
Conventional Commits 规范 — 提交信息规范
Charity Majors: Why I Hate Five Whys — Honeycomb 创始人的 SRE 文化文章集

测试覆盖、代码审查与质量调优

经过 6.3 节的多轮迭代，我们已经把一个空的脚手架推向了功能可用的最小可行产品（Minimum Viable Product, MVP）。表面上看，主流程跑通了、UI 截图也拿得出手，但任何一位真正把代码送上过生产环境的工程师都知道：从「Demo 跑通」到「敢交付」之间，还隔着一整条质量保障链路——测试、审查、调优、门禁。这条链路的每个环节，过去由人主导、AI 辅助；从 Claude Code 普及之后，许多团队开始反过来：让 AI 主导执行，让人主导决策。

提示词设计原则

让 Claude 准确理解你的意图