AI 全流程研发实战

问题

从需求到上线的每一个研发环节，2026 年如何用 Skills / Subagents / Slash Commands / Hooks / MCP 把 AI 用到极致？每个阶段有哪些可以直接落地的配置和脚本？如何度量全流程的 AI 效能？

面试速答版

从需求到上线，AI 如何用到极致？ 核心思路是把每个研发阶段的工作流固化成 Slash Command / Skill / Subagent / Hook，让团队经验一次沉淀、永久复用：

10 个阶段：需求 → 设计 → 编码 → 审查 → 测试 → 调试 → 文档 → 部署 → 监控 → 度量。
每阶段都有专属资产：如 /new-api、/review-pr、/gen-tests、/debug、/ship。
阶段之间用「产出物流水线」串起来，上一阶段的产物自动喂给下一阶段。

每个阶段有哪些可以直接落地的配置和脚本？ 按四类资产对号入座：

Slash Commands：固化重复操作，如 /new-component、/gen-changelog、/rollback。
Skills：领域知识包，如 api-route、security-checklist、incident-playbook。
Subagents：独立角色，如 security-reviewer、test-writer、bug-hunter（用 Opus）。
Hooks：PostToolUse 自动 lint/tsc/test，PreToolUse 拦截生产破坏，SessionStart 注入 Sprint 上下文。

如何度量全流程的 AI 效能？ 用 Gateway 日志 + 周报 Slash Command 量化收益：

输入指标：模型调用次数、Token 消耗、月度成本。
过程指标：代码采纳率、PR 评审耗时、测试覆盖率变化。
结果指标：需求交付周期、缺陷率、线上 incident MTTR。
人均产出和每元 ROI 是和老板对齐的最终语言。

答案

一、全流程资产地图

2023-2024 年的 AI 全流程 = 「每个阶段都写好 Prompt」。2026 年的全流程 = 把每个阶段的工作流固化为 Slash Command / Skill / Subagent / Hook——让团队经验一次沉淀、永久复用。

1.1 各阶段资产清单（实战落地版）

阶段	Slash Commands	Skills	Subagents	Hooks	MCP
1. 需求分析	`/analyze-req`	`req-parser`	—	`SessionStart` 注入 Sprint	飞书 / Jira / Linear
2. 技术设计	`/design-arch`、`/compare-options`	`architecture-patterns`	—	—	内部设计系统
3. 代码生成	`/new-api`、`/new-component`、`/new-page`	`api-route`、`component-builder`、`form-builder`	—	`PostToolUse` 自动 lint/tsc	—
4. 代码审查	`/review-pr`、`/review-security`	`security-checklist`	`security-reviewer`	—	—
5. 测试	`/gen-tests`、`/mutation-test`	`test-patterns`	`test-writer`	`PostToolUse` 跑 vitest	—
6. 调试	`/debug`、`/analyze-error`、`/bisect`	`bug-hunter`	`bug-hunter`（Opus）	`UserPromptSubmit` 注入 error log	Sentry
7. 文档	`/gen-api-docs`、`/update-readme`、`/gen-changelog`	`doc-patterns`	`doc-writer`	`PostMerge` 同步文档	—
8. 部署	`/ship`、`/rollback`	`release-flow`	—	`PreToolUse` 拦截生产破坏	K8s / Vercel
9. 监控响应	`/triage`、`/postmortem`	`incident-playbook`	—	—	Sentry / Grafana / PagerDuty
10. 效能度量	`/weekly-report`	—	—	—	Gateway logs

目录结构：

.claude/
├── commands/              # Slash Commands
│   ├── workflow/
│   ├── codegen/
│   ├── quality/
│   ├── debug/
│   ├── docs/
│   └── ops/
├── skills/                # Skills
├── agents/                # Subagents
├── hooks/                 # Hook 脚本
├── memory/                # 持久化记忆
└── settings.json          # Hook 和权限配置

一次投入，长期受益：把这套基建打磨好（通常 1-2 个迭代），所有新需求、所有新人都能第一天就有完整 AI 加持。

1.2 产出物流水线：阶段之间如何衔接

每个阶段都读上游产出 → 加工 → 写下游输入。所有阶段产物沉淀到同一个目录：

.claude/artifacts/<feature-id>/
├── 01-requirements.md       # 需求分析：结构化需求 + User Stories + MVP 分层
├── 02-tasks.md              # 需求分析：Epic/Story/Task 树 + Story Points
├── 03-risks.md              # 需求分析：风险清单
├── 04-open-questions.md     # 需求分析：待 PM 澄清的问题
├── 05-architecture.md       # 技术设计：架构图 + 数据模型 + API 契约
├── 06-adr.md                # 技术设计：方案对比 + 决策记录
├── 07-implementation-plan.md # 技术设计：分步实现计划
├── 08-file-changes.md       # 代码生成：改动文件清单 + commit 对应关系
├── 09-review-report.md      # 代码审查：审查发现 + 修复状态
├── 10-test-report.md        # 测试：覆盖率 + 场景分布 + 盲区
├── 11-bug-log.md            # 调试：Bug 现象 + 根因 + 修复
├── 12-release-checklist.md  # 部署：发布前检查 + 回滚预案
├── 13-runbook.md            # 部署：上线操作手册
├── 14-incident-log.md       # 监控：线上事件记录
└── 15-postmortem.md         # 监控：事件复盘

<feature-id> 取飞书文档 token、Jira 卡号，或自定义短名（如 ai-summary-2301），全流程共用同一个目录。

阶段间流动：

为什么要落盘（而不是"AI 记在会话里"）：

跨会话延续：周五分析的需求，周一继续时 AI 能读到完整上下文
跨人交接：你请假，同事接手，读 01-requirements.md 就知道需求、读 05-architecture.md 就知道设计
跨 Agent 协作：主 Agent 和 Subagent 共享状态，都读同一份文件
可审计：出问题后能复盘 AI 当初是基于什么信息做的决策
可复用：好的产出模板能沉淀为 Skill、Changelog 可以直接引用

Slash Command 约定：所有全流程 Slash Command 都接收 <feature-id> 作为第一个参数，自动读写对应目录。举例：

/analyze-req ai-summary-2301 https://xxx.feishu.cn/docx/ABC   # 产出 01-04
/design-arch ai-summary-2301                                   # 读 01-04，产出 05-07
/new-api ai-summary-2301 summaries                             # 读 05-07，产出 08 + 源码
/review-pr ai-summary-2301                                     # 读 01 + 08 + 源码，产出 09
/gen-tests ai-summary-2301 --diff                              # 读 01 + 08 + 源码，产出 10
/ship ai-summary-2301 production                               # 读 10 + 09，产出 12-13

后续命令只要传 feature-id 就能拿到全部上游产物，无需重复描述需求。

不要把敏感数据落盘

.claude/artifacts/ 纳入 Git 时注意：

需求描述、任务拆解、架构设计、测试报告 → 可以提交
客户真实姓名、真实数据样本、密钥、内部定价 → .gitignore 或脱敏后再写入
线上事件日志 → 脱敏 user_id / IP 后再提交

配套阅读

AI 辅助开发 — 五件套的详细实现
AI 研发基建 — 企业级平台建设
Context Engineering — 上下文工程
Harness Engineering — 运行时壳层

示例中的模型和工具版本要定期核对

文中的 Claude / GPT / Gemini / Qwen / DeepSeek 模型名、MCP 包名、GitHub Action 输入项都是 2026 年语境下的示例。真实项目落地前，应以供应商当前官方文档和团队实测为准；面试回答时重点讲流程、边界和验证方法，不要把某个模型版本或包名当成长期不变的结论。

二、阶段 1：需求分析

AI 角色：需求解构、Story Points 估算、风险识别、PRD 审查。

AI 解决的核心问题：

非结构化 PRD → 结构化 Epic / Story / Task 树
需求的未明确边界被 AI 主动反问出来
基于团队历史数据做 Story Points 估算
风险清单自动生成

阶段 I/O

输入：飞书文档链接 / token（PRD 原文）

资源：

飞书 MCP（读 PRD、回写拆解结果）
req-parser Skill（解析规范、估算模式）
.claude/memory/product-context.md（产品背景）
.claude/memory/tech-stack.md（技术栈和边界）
.claude/memory/past-estimates.md（团队历史估算数据）

做法：/analyze-req <feature-id> <飞书文档链接>

产出（全部写入 .claude/artifacts/<feature-id>/）：

01-requirements.md — 结构化需求复述 + User Stories（带验收标准）+ MVP 分层
02-tasks.md — Epic / Story / Task 树 + Story Points + 依赖关系
03-risks.md — 风险清单（影响、概率、缓解措施）
04-open-questions.md — 待 PM / 设计 / 后端澄清的问题清单

下一步：回答 04-open-questions.md 中的问题 → 运行 /design-arch <feature-id>

2.1 配置飞书 MCP

这是需求阶段的最高 ROI 动作。让 AI 直接读飞书文档中的 PRD，不用你复制粘贴。

飞书开放平台官方提供 MCP 支持，社区也有成熟实现（如 @larksuiteoapi/lark-mcp）。

.claude/settings.json
{
  "mcpServers": {
    "feishu": {
      "command": "npx",
      "args": [
        "-y",
        "@larksuiteoapi/lark-mcp",
        "mcp",
        "-a",
        "${env:FEISHU_APP_ID}",
        "-s",
        "${env:FEISHU_APP_SECRET}"
      ]
    }
  }
}

飞书 / Lark MCP 仍需按官方能力边界配置

@larksuiteoapi/lark-mcp 的参数、权限范围、OAuth token mode、国内/国际域名会随版本变化。复制配置前应核对官方 README；文档编辑、文件上传下载等能力也可能有 Beta 限制，不要默认所有云文档操作都可写。

配置要点：

在飞书开放平台创建自建应用，拿到 App ID / App Secret
给应用开通「云文档」相关权限：
- docx:document:readonly（读文档）
- wiki:wiki:readonly（读知识库）
- docx:document（如需 AI 回写文档）
把应用安装到所在组织，或让需要用的成员授权

AI 常用的工具调用：

工具	用途
`feishu__get_doc(token)`	读飞书文档为 Markdown
`feishu__get_wiki(token)`	读知识库页面
`feishu__search(keyword)`	全文搜索
`feishu__list_children(token)`	列文档子页面（读整个 Epic 下的所有 Story）
`feishu__create_doc(...)`	回写 AI 产出到飞书（如 Changelog、Postmortem）

飞书文档的 token 从哪来： URL https://xxx.feishu.cn/docx/ABCDEFG123 中，ABCDEFG123 就是 token。

同时用其他需求工具

Jira / Linear：各自有官方 MCP，和飞书 MCP 可同时配置。例如 PRD 在飞书但任务在 Jira，/analyze-req 先读飞书，然后用 jira__create_issue 把拆解的子任务写入 Jira
Notion：notion-mcp-server
下面的示例都以飞书为主，替换 MCP 名就能迁移到其他工具

2.2 Slash Command `/analyze-req`

.claude/commands/workflow/analyze-req.md
---
name: analyze-req
description: 从飞书 PRD 产出结构化需求、任务、风险、问题清单
argument-hint: "<feature-id> <飞书文档链接或 token>"
---

分析需求并产出全流程上游资产。

## 参数
- feature-id: $1（全流程标识，如 `ai-summary-2301`）
- 飞书链接或 token: $2

## 步骤 1：读取原始需求
- 从 $2 提取 token（URL 中 `/docx/` 或 `/wiki/` 后面的段）
- 调用 `feishu__get_doc(token)` 拿到 Markdown
- 如果是 Wiki 且有子页（PRD + 交互稿 + 背景调研分开写），调用 `feishu__list_children` 把相关子文档一起读入

## 步骤 2：加载团队上下文
并行读：
- `.claude/memory/product-context.md`
- `.claude/memory/tech-stack.md`
- `.claude/memory/past-estimates.md`

## 步骤 3：创建产物目录
`mkdir -p .claude/artifacts/$1`

## 步骤 4：产出 4 份文件（每份独立 Write，便于后续单独读取）

### 4.1 `.claude/artifacts/$1/01-requirements.md`
结构：
- **元信息**：feature-id、飞书文档链接、分析日期、分析人
- **需求复述**（3-5 句，用团队能理解的语言）
- **User Stories**（INVEST 原则，每个含验收标准 checkbox）
- **MVP 分层**：P0 必须 / P1 建议 / P2 可选
- **非功能需求**：性能、兼容性、可访问性、安全约束

### 4.2 `.claude/artifacts/$1/02-tasks.md`
Epic / Story / Task 三级树：
| 层级 | 名称 | Story Points | 预估人日 | 依赖的 Task | 技术方向 |

末尾附：
- 总 Story Points
- 关键路径（longest path）
- 可并行的分支

### 4.3 `.claude/artifacts/$1/03-risks.md`
| 风险 | 类型 | 影响（高/中/低）| 概率（高/中/低） | 缓解措施 | 负责人 | 状态 |

类型包括：技术风险、三方依赖、数据迁移、安全合规、排期冲突。

### 4.4 `.claude/artifacts/$1/04-open-questions.md`
至少 3 个待澄清问题，每条：
- 问题描述
- **为什么需要澄清**（会影响什么设计决策）
- **默认假设**（如果 PM 不响应，先按什么做）
- 负责回答方（PM / 设计 / 后端 / 法务）
- 截止时间（阻塞进入下阶段的时间点）

## 步骤 5：回写飞书（可选）
如果 PM 希望同步看到 AI 拆解，调用 `feishu__create_doc` 在原 PRD 的子页创建
"AI 拆解与澄清问题" 页，把 01-04 合并写入。

## 步骤 6：汇总输出给用户
- 4 个文件路径
- 任务总 Story Points 和预估工期
- 高风险项数量
- **待澄清问题数量**（阻塞下一阶段）
- 下一步命令建议：
  - 若有待澄清问题 → 先与 PM 对齐
  - 若无阻塞 → `/design-arch $1`

使用：

> /analyze-req ai-summary-2301 https://xxx.feishu.cn/docx/ABCDEFG123

AI: [feishu__get_doc] 读取飞书 PRD
    [读取 memory/ 下 3 个上下文文件]
    [Bash] mkdir -p .claude/artifacts/ai-summary-2301
    [Write] .claude/artifacts/ai-summary-2301/01-requirements.md（3 Stories、P0×2 / P1×1）
    [Write] .claude/artifacts/ai-summary-2301/02-tasks.md（13 Task / 21 SP，关键路径 4 Task）
    [Write] .claude/artifacts/ai-summary-2301/03-risks.md（5 项，其中 2 项高风险）
    [Write] .claude/artifacts/ai-summary-2301/04-open-questions.md（4 个待澄清）

产出已落盘。阻塞下一阶段的问题：
  1. 摘要长度上限没定 — 影响 Prompt 设计和 Token 预算
  2. 失败时是否回退显示原文摘要？— 影响降级策略
  3. 单用户 QPS 限制多少？— 影响限流设计
  4. 摘要是否支持用户反馈"重新生成"？— 影响 UI 和缓存策略

建议先把 04-open-questions.md 同步给 PM（链接：飞书文档 XXX）
回答确认后运行：/design-arch ai-summary-2301

2.3 Skill `req-parser`

.claude/skills/req-parser/SKILL.md
---
name: req-parser
description: |
  结构化解析 PRD / Jira / 用户需求。
  触发：用户贴出长段需求描述、提到"分析需求"、"拆解这个功能"、"评估工作量"时。
---

# 需求解析 Skill

## 解析原则

1. **不要编造**：PRD 没说的就是"未明确"，不要自己补全
2. **主动反问**：至少提 3 个澄清问题
3. **结构化输出**：用户能直接复制到 Jira / Confluence

## Story Points 估算参考

引用 `.claude/memory/past-estimates.md` 里的历史数据：
- 1 SP = 半天，小改动
- 2 SP = 1 天，基础组件
- 3 SP = 2 天，中等功能
- 5 SP = 3-5 天，复杂功能
- 8 SP = 5-8 天，涉及架构改动
- 13 SP = 需要预研，拆！

## 风险识别模式
- 涉及支付 / 鉴权 / 加密 → 高风险
- 涉及数据迁移 → 高风险
- 涉及第三方 API 且无回退 → 中风险
- 涉及性能敏感路径 → 中风险
- 涉及跨团队接口 → 中风险

三、阶段 2：技术设计

AI 角色：架构图生成、API 契约设计、Schema 设计、方案对比、ADR 生成。

关键动作：Plan Mode 强制只读探索。避免"AI 乱改 50 个文件发现方向错了"。

阶段 I/O

输入（读上阶段产物）：

.claude/artifacts/<feature-id>/01-requirements.md — 理解需求
.claude/artifacts/<feature-id>/02-tasks.md — 看拆解粒度
.claude/artifacts/<feature-id>/03-risks.md — 设计需规避的风险

资源：

architecture-patterns Skill（团队架构约定、禁区）
现有代码库（Grep / Read，只读探索）
.claude/skills/architecture-patterns/reference/（选型决策树）
Plan Mode（强制只读）

做法：/design-arch <feature-id>

产出（写入 .claude/artifacts/<feature-id>/）：

05-architecture.md — 整体架构图 + 数据流图 + 数据模型 + API 契约 + 状态管理方案
06-adr.md — 关键决策的多方案对比和选型理由（ADR 格式）
07-implementation-plan.md — 分步实现计划（每步含文件清单、预估时间、验证方法）

前置检查：04-open-questions.md 中标记为"阻塞"的问题必须已回答。

下一步：用户审核 05-architecture.md + 06-adr.md → 批准后运行 /new-api / /new-component 等，传入 <feature-id>

3.1 Slash Command `/design-arch`

.claude/commands/workflow/design-arch.md
---
name: design-arch
description: 读取需求产物做技术方案设计（强制 Plan Mode）
argument-hint: "<feature-id>"
---

## 参数
- feature-id: $1

## 步骤 0：前置检查
- Read `.claude/artifacts/$1/04-open-questions.md`
- 如果有"阻塞"标记的问题未回答 → 停止，告知用户先澄清

## 步骤 1：切换到 Plan Mode（只读探索，不改代码）

## 步骤 2：读取上阶段产物
- Read `.claude/artifacts/$1/01-requirements.md`（需求和验收标准）
- Read `.claude/artifacts/$1/02-tasks.md`（任务边界）
- Read `.claude/artifacts/$1/03-risks.md`（设计要绕开的坑）

## 步骤 3：理解现状
- Grep 相关模块：查找相似功能的现有实现
- Read 关键文件：`package.json`、`prisma/schema.prisma`、`src/lib/` 下的工具
- 读 `.claude/skills/architecture-patterns/reference/` 中的团队架构约定

## 步骤 4：产出 3 份文件

### 4.1 `.claude/artifacts/$1/05-architecture.md`
包含：
- **整体架构图**（Mermaid `graph TD`，模块关系）
- **数据流图**（Mermaid `sequenceDiagram`，关键用户操作的完整路径）
- **数据模型**（Prisma Schema 新增表和字段，含 migration 影响面分析）
- **API 契约**（每个接口：TypeScript 类型 + Zod Schema + 错误码表）
- **状态管理**：客户端状态（Zustand）/ 服务端缓存（TanStack Query）/ 乐观更新策略
- **风险对应**：明确说明本设计如何缓解 `03-risks.md` 中的每一项

### 4.2 `.claude/artifacts/$1/06-adr.md`
对有多方案选择的关键决策写 ADR（一个关键决策一个 ADR 段落）：

## ADR-XXX: `<决策主题>`
### 上下文
（业务和技术约束）
### 考虑过的方案
1. 方案 A — 优劣
2. 方案 B — 优劣
3. 方案 C — 优劣
### 决策
选 X，因为...
### 后果
- 正面：...
- 负面：...
- 待观察：...


### 4.3 `.claude/artifacts/$1/07-implementation-plan.md`
按**依赖顺序**列出 N 步，每步：
| 步骤 | 产物（文件） | 依赖步骤 | 预估时间 | 验证方法 | 可否并行 |

标注关键路径 + 可并行分支（供后续用 Subagent 并行加速）。

## 步骤 5：方案对比（如果有）
调用 `/compare-options` 或直接输出到 `06-adr.md`：
| 方案 | 优势 | 劣势 | 推荐度 |

## 步骤 6：等待用户审核
**不进入执行**。输出：
- 3 份产物路径
- 关键决策摘要
- 关键路径预估总工期
- 提示：审核 `05-architecture.md` + `06-adr.md`，批准后运行代码生成阶段

3.2 架构图自动生成

> /design-arch 实时协同编辑

AI: [Plan Mode 开启] [只读扫描]

## 整体架构

```mermaid
graph TD
    subgraph 客户端
        U[React UI]
        Y[Yjs Doc]
        W[WebSocket Client]
    end
    
    subgraph BFF层
        API[Next.js API]
        Auth[NextAuth]
        Proxy[WS Proxy]
    end
    
    subgraph 协同服务
        LB[Liveblocks SaaS]
        PG[Persistence DB]
    end
    
    U <-->|本地 CRDT| Y
    Y <-->|同步 updates| W
    W <-->|WSS| Proxy
    Proxy <-->|auth| Auth
    Proxy <-->|forward| LB
    LB -->|webhook 持久化| API
    API --> PG

...

#### 3.3 Skill `architecture-patterns`

```markdown title=".claude/skills/architecture-patterns/SKILL.md"
---
name: architecture-patterns
description: |
  团队架构决策参考。
  触发：用户讨论"架构设计"、"技术选型"、"方案对比"、"如何实现 XX"时加载。
---

# 团队架构模式

## 核心约定

1. **BFF 模式**：前端只调内部 `/api/*`，不直接调外部服务
2. **Server Component 优先**：能 SSR 的不 CSR
3. **React Query 管服务端状态**，Zustand 管客户端 UI 状态
4. **表单 3 件套**：React Hook Form + Zod + 设计系统组件
5. **错误边界**：页面级 `error.tsx`，组件级 ErrorBoundary

## 禁区

- ❌ 不用 `localStorage` 存敏感数据（用 httpOnly cookie）
- ❌ 不裸用 fetch（用 `lib/api-client.ts`）
- ❌ 不在 Server Component 里 import 客户端库（bundle 膨胀）
- ❌ 不搞"全能 Hook"（超过 100 行的 Hook 必须拆）

## 常见方案参考

见 `reference/`：
- `state-management.md` — 状态管理选型决策树
- `data-fetching.md` — 数据获取模式
- `error-handling.md` — 错误处理分层
- `performance.md` — 性能优化检查表
- `security.md` — 安全架构清单

四、阶段 3：代码生成

AI 角色：样板消除、规范代码生成、脚手架搭建。

核心原则：

能调 Skill 就不自己写 — Skill 是经过团队打磨的资产，远比临场生成可靠
能调脚本就不让 AI 写 — 脚本执行比 AI 生成快 10 倍且确定
分步迭代，每步验证 — PostToolUse Hook 自动 lint/tsc

阶段 I/O

输入（读上阶段产物）：

.claude/artifacts/<feature-id>/05-architecture.md — API 契约、数据模型、状态管理方案
.claude/artifacts/<feature-id>/07-implementation-plan.md — 分步顺序和文件清单

资源：

Skills（api-route / component-builder / form-builder 等代码模板）
Skills 脚本（scripts/generate-route.ts 等确定性生成器）
test-writer Subagent（并行生成测试）
PostToolUse Hook（自动 lint/tsc）
设计系统 tokens（走 Tailwind / CSS vars）

做法：按 07-implementation-plan.md 顺序执行，每步调用：

/new-api <feature-id> <entity>
/new-component <feature-id> <ComponentName>
/new-migration <feature-id> <description>

产出：

源代码（feature branch，按 plan 分步 commit）
.claude/artifacts/<feature-id>/08-file-changes.md — 改动文件清单：
- 每个文件的路径、用途、关联的 plan 步骤、对应 commit hash
- 新增的依赖（package.json）
- DB migration 文件路径
- 影响的现有接口 / 组件

下一步：/review-pr <feature-id> 本地自审 → 推送 PR

4.1 Slash Command `/new-api` 全流程

.claude/commands/codegen/new-api.md
---
name: new-api
description: 创建符合团队规范的 API 路由（读架构设计，调用 api-route Skill + test-writer Subagent）
argument-hint: "<feature-id> <实体或需求描述>"
---

## 参数
- feature-id: $1
- 实体 / 需求: $2+

## 步骤 1：读架构设计
- Read `.claude/artifacts/$1/05-architecture.md` 中 $2 相关的 API 契约段
  - 请求参数 Zod Schema
  - 响应类型
  - 错误码
  - 鉴权 / 限流 / 幂等性要求
- 如果 `05-architecture.md` 没覆盖这个 entity，停下问用户（避免凭空发挥）

## 步骤 2：调用 api-route Skill

**优先**：如果是标准 CRUD，调用脚本：

\`\`\`bash
node .claude/skills/api-route/scripts/generate-route.ts \\
  --entity <Entity> \\
  --operations "create,read,update,delete" \\
  --auth-required
\`\`\`

**否则**：按 Skill 的 SKILL.md 规范手写：
- 套 `auth()` + `rateLimiter()` + Zod 校验 + 统一错误码

## 步骤 3：Hook 自动验证

PostToolUse Hook 会自动跑 lint + tsc，有错立即修

## 步骤 4：委派 test-writer Subagent（并行）

\`\`\`
请 test-writer Subagent 为刚创建的 API 生成测试（传入 feature-id=$1，
Subagent 会自己读 01-requirements.md 作为"规格"而不是只看代码）：
- 正向测试（happy path）
- 异常测试（401 / 400 / 500）
- 边界测试（空数据、极大数据）
- 幂等性测试（如适用）
\`\`\`

## 步骤 5：跑测试

`pnpm test <测试文件>` 确保通过

## 步骤 6：更新产物清单

追加一段到 `.claude/artifacts/$1/08-file-changes.md`：
\`\`\`
## $2 API
- src/app/api/$2/route.ts — 新建，对应 plan 步骤 N，commit <hash>
- src/app/api/$2/route.test.ts — 新建
- prisma/migrations/YYYYMMDDHHMMSS_add_$2.sql — 如有
\`\`\`

## 步骤 7：输出汇总

- 文件清单
- 测试结果
- 是否引入新依赖 / migration
- 下一步建议（按 plan 下一步）

4.2 Skill `api-route` 的完整模板

.claude/skills/api-route/templates/rest-route.ts
// highlight-start
// 这是 api-route Skill 的模板文件
// AI 在生成 API 路由时参考这个模板
// highlight-end
import { NextRequest, NextResponse } from 'next/server';
import { z } from 'zod';
import { auth } from '@/lib/auth';
import { rateLimiter } from '@/lib/rate-limit';
import { ApiError, apiResponse } from '@/lib/api-response';
import { logger } from '@/lib/logger';

// 1. 请求参数 Schema
const requestSchema = z.object({
  // 字段定义
});

// 2. 响应类型
type Response = {
  // 响应字段
};

export async function POST(request: NextRequest) {
  // 2.1 限流
  const limited = await rateLimiter('api-xxx', request);
  if (limited) return apiResponse.error('RATE_LIMITED', 429);

  // 2.2 鉴权（公开接口可跳过）
  const session = await auth();
  if (!session) return apiResponse.error('UNAUTHORIZED', 401);

  // 2.3 参数校验
  const parsed = requestSchema.safeParse(await request.json());
  if (!parsed.success) {
    return apiResponse.error('INVALID_PARAMS', 400, parsed.error);
  }

  // 2.4 业务逻辑（走 lib/db/* 封装层）
  try {
    const result = await doSomething(parsed.data, session.user.id);
    logger.info('xxx.success', { userId: session.user.id });
    return apiResponse.ok(result);
  } catch (err) {
    if (err instanceof ApiError) return err.toResponse();
    logger.error('xxx.error', { err });
    return apiResponse.error('INTERNAL', 500);
  }
}

4.3 PostToolUse Hook 自动验证（标配）

.claude/settings.json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": ".claude/hooks/post-edit-check.sh" }
        ]
      }
    ]
  }
}

.claude/hooks/post-edit-check.sh
#!/bin/bash
set +e

INPUT=$(cat)
FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

if [[ "$FILE" =~ \.(ts|tsx)$ ]]; then
  LINT=$(pnpm eslint --fix "$FILE" 2>&1)
  LINT_EXIT=$?
  TSC=$(pnpm tsc --noEmit 2>&1 | grep "$FILE" | head -10)

  if [ $LINT_EXIT -ne 0 ] || [ -n "$TSC" ]; then
    echo "⚠️ 质量检查失败："
    echo "$LINT" | tail -10
    echo "$TSC"
    exit 2
  fi
fi

效果：AI 写完文件 3 秒内看到 lint/type error，下一轮自动修复。这是 2026 年最有价值的 Hook，必配。

4.4 并行开发：test-writer Subagent

主 Agent 生成业务代码，Subagent 并行生成测试，总时间 = max 而非 sum：

.claude/agents/test-writer.md
---
name: test-writer
description: |
  为指定文件生成 Vitest + React Testing Library 测试。
  覆盖正向、异常、边界场景。
model: claude-sonnet-4-6
tools: [Read, Write, Bash]
---

你是测试工程师，负责为前端 + BFF 代码生成测试。

## 测试原则

1. **从需求出发**，不是从代码出发。读代码只是理解实现，测试验证**规格**
2. **测试 3 类**：
   - ✅ Happy path（正向）
   - ❌ Error path（异常）
   - 📏 Edge cases（边界：空、极大、恰好等于阈值）
3. **Mock 最小化**：只 mock 外部依赖（网络、DB、时钟）
4. **异步等待用 `findBy*`**，不用 `await waitFor(...)`
5. **UI 测试聚焦行为，不聚焦实现**：用 `getByRole` 而非 `getByTestId`

## 输出

每个测试文件给出：
- describe/it 结构清晰
- 测试名用中文描述（`should ...` 改成"应该..."）
- Mock 写在 `beforeEach`
- 不引入新的测试工具库（只用已有的）

完成后运行 `pnpm test <file>` 验证通过。失败则修复。

Subagent 路径权限不要写成伪字段

Claude Code Subagent 标准 frontmatter 使用 tools / disallowedTools / permissionMode / hooks 等字段。若要限制只能写测试文件，建议用项目权限 deny 规则或 PreToolUse Hook 校验 .tool_input.file_path，不要依赖非标准的 allowedPaths 字段。

使用示例（主 Agent 委派）：

主 Agent: 我已经实现了 src/app/api/share/route.ts，委派 test-writer 生成测试

→ test-writer Subagent：
  [Read] src/app/api/share/route.ts
  [Read] src/lib/api-response.ts（理解响应格式）
  [Write] src/app/api/share/route.test.ts
  [Bash] pnpm test src/app/api/share/route.test.ts
  → 通过
  返回："测试已生成，4 个 case 全部通过"

主 Agent: 收到结果，继续写前端 share button 组件...

并行效果：一个 5 文件的功能，传统串行需要 40 分钟，并行 + Subagent 只要 20 分钟。

4.5 从 Figma 设计稿生成 UI 组件

AI 角色：从视觉稿直接生成符合设计系统的组件代码。

2026 年 Figma-to-code 已经从「拖拖拽拽出一堆脏代码」升级为 「设计稿 → 语义化组件 + 遵守设计系统」。三条主流路径，按推荐度排序：

4.5.1 路径 A：Figma MCP Server + Code Connect（最推荐，2026 年主流方案）

Figma 的 Code Connect 可以把真实代码组件映射到 Figma Dev Mode，并增强 Figma MCP Server 给 AI Agent 的实现上下文。实际 MCP Server 的安装方式、包名和权限要求请以 Figma 官方文档为准；不少能力依赖 Dev / Full seat 和组织或企业计划。

配置：

.claude/settings.json
{
  "mcpServers": {
    "figma": {
      "command": "npx",
      "args": ["-y", "<figma-mcp-server-package>"],
      "env": {
        "FIGMA_ACCESS_TOKEN": "${env:FIGMA_TOKEN}"
      }
    }
  }
}

工作流（用 Slash Command /figma-to-component 固化）：

.claude/commands/codegen/figma-to-component.md
---
name: figma-to-component
description: 从 Figma 设计稿生成 React 组件
argument-hint: "[figma-url] [component-name]"
---

从 Figma 设计稿生成组件。

## 参数
- Figma URL: $1（含 node-id）
- 组件名: $2

## 步骤

### 1. 读取设计稿
调用 `figma__get_node($1)` 拿到：
- 节点结构（父子关系、布局）
- 样式属性（颜色、间距、字号、圆角、阴影）
- 引用的 Design Token（如 `color.primary.500`）
- 标注的组件类型（Button、Card、Input…）

### 2. 映射到设计系统
**不要**把 Figma 的原始值（`#3B82F6`、`24px`）直接写到代码里。
**要**映射到项目已有的设计系统：
- 颜色 → `bg-primary-500` 或 `var(--color-primary-500)`
- 间距 → `p-4`、`gap-6`（走 Tailwind spacing scale）
- 字号 → `text-lg font-semibold`（走 typography scale）
- 圆角 → `rounded-lg`（走 radius scale）

如果 Figma 某个值**在设计系统中找不到对应**，必须 STOP 并告知用户：
「Figma 用了 `#3B82F6` 但项目里最接近的 primary 是 `#2563EB`，差异 XX%，是直接用 primary 还是新增 token？」

**禁止自动编造新 Token**。

### 3. 判断组件语义
根据视觉特征和 Figma 标注推断：
- 有 hover 状态 + 文字 + 背景 → Button
- 有 placeholder + 边框 → Input
- 卡片式布局 → Card
- 复杂交互 → 需要用户说明

优先复用 `.claude/skills/component-builder/` 里的 shadcn/ui 模板。

### 4. 生成代码
调用 `component-builder` Skill 生成：
- `components/$2.tsx` — 组件实现
- `components/$2.test.tsx` — 单元测试（test-writer Subagent 并行）
- `components/$2.stories.tsx` — Storybook（如项目有）

### 5. 视觉对比验证
- 启动 Storybook 或用 Playwright 打开组件页面
- 截图
- 委派 `visual-reviewer` Subagent 对比 Figma 原稿和截图
- Subagent 返回：✅ 通过 / ⚠️ 差异清单（位置、大小、颜色）
- 有差异 → 主 Agent 迭代修复，最多 3 轮

### 6. 产出清单
- 组件文件 + 测试 + Story
- 视觉对比报告（Figma vs 实现）
- 如果用了新 Token，列出待设计师确认的清单

为什么 MCP 方式最好：

✅ AI 拿到的是结构化数据（不是像素），语义更准
✅ Design Token 引用自动解析（AI 知道是 color.primary，不是 #3B82F6）
✅ 无网络开销，增量更新快
✅ 支持多个 AI 工具共享（Cursor / Claude Code 都能用）

4.5.2 路径 B：截图 + 多模态模型（快速验证场景）

如果没有 Figma 或只是一张设计图，用多模态能力直接喂给 Claude / GPT-5：

.claude/commands/codegen/from-screenshot.md
---
name: from-screenshot
description: 从截图生成 UI 组件
argument-hint: "[image-path] [component-name]"
---

从截图生成组件：$1 → $2

## 步骤

### 1. 读取截图
[Read] $1（多模态模型会看到图片）

### 2. 加载设计系统参考
[Read] `.claude/design-system/tokens.md`（颜色/间距/字号表）
[Read] `.claude/skills/component-builder/templates/`（组件模板）

### 3. 视觉分析
AI 分析图片，输出结构化描述：
- 整体布局（flex/grid，方向、间距）
- 每个元素（类型、尺寸、颜色、文字）
- 交互推断（可点击？hover 态？）

### 4. 生成前先确认
列出理解的要点：
- 布局结构
- 使用的 Design Token 映射
- 推测的组件类型
- 不确定的地方（⚠️ 图中字号不明确，按 text-base 处理？）

等用户确认再生成。

### 5. 生成代码（同路径 A 第 4-6 步）

多模态生成的三条铁律：

分辨率要够（建议 2x、4K+）：AI 才能看清细节
先让 AI 描述再生成：描述错的比生成错的好修复
不要一次给太复杂的截图：复杂页面拆成多个组件分别喂

4.5.3 路径 C：v0 / Lovable / Bolt（快速原型）

这类专业工具擅长从 0 到 1 生成可运行的 React + Tailwind + shadcn/ui 页面：

工具	最适合	输出
v0.dev	单个组件快速生成	React + shadcn/ui + Tailwind
Lovable	完整 Web App 原型	全栈（前端 + Supabase）
Bolt.new	快速 MVP	全栈 Node.js 项目

推荐工作流：

v0 的代码虽然能跑，但通常不符合你的设计系统和编码规范。所以：

# Step 1: 在 v0 上生成并下载代码到 /tmp/v0-output.tsx

# Step 2: 用 Claude Code 适配
claude "读取 /tmp/v0-output.tsx，按项目规范重构：
1. 替换 v0 默认颜色/间距为我们的 design token（看 @.claude/design-system/tokens.md）
2. 替换 v0 默认 shadcn 为我们的封装（看 @src/components/ui/）
3. 加 TypeScript 类型（Props interface）
4. 加加载态和错误态
5. 生成测试（委派 test-writer Subagent）
6. 移到 src/components/$name.tsx"

三条路径怎么选

设计系统成熟、有 Figma → 路径 A（Figma MCP，最准确）
只有截图/设计师没用 Figma → 路径 B（多模态）
快速原型、MVP 阶段 → 路径 C（v0 + Claude Code 适配）
大多数团队：A 做主力，B 做补充，C 做原型

4.5.4 Design Token 提取（一次投入，永久受益）

Figma-to-code 的最大瓶颈不是生成代码，是把 Figma 的设计 Token 和代码的 Token 对齐。

标准做法：用 Style Dictionary 或 Tokens Studio 做单一事实源（Single Source of Truth）：

scripts/sync-figma-tokens.ts
// 每天凌晨从 Figma 拉最新 Token，跑 Style Dictionary 编译
// CI 上跑，Token 变化自动发 PR

import { tokensFromFigma } from './figma-api';
import StyleDictionary from 'style-dictionary';

const tokens = await tokensFromFigma({ fileId: 'XXX' });
writeFileSync('tokens/figma.json', JSON.stringify(tokens, null, 2));

StyleDictionary.buildAllPlatforms(); // 生成 tailwind.config / CSS vars

效果：设计师改一个色值，第二天 tailwind.config.ts 自动同步，AI 生成代码时看到的是最新 Token，不会写死过时颜色。

4.5.5 Hook：UI 改动后自动截图验证

PostToolUse Hook 配合 Playwright，让 AI 看到自己的改动效果：

.claude/hooks/ui-screenshot.sh
#!/bin/bash
# AI 改完 components/**/*.tsx 后自动截图
INPUT=$(cat)
FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
if [[ "$FILE" =~ components/.*\.tsx$ ]]; then
  # 提取组件名
  COMPONENT=$(basename "$FILE" .tsx)
  # 跑 Storybook 并截图
  pnpm exec playwright test \
    --grep "$COMPONENT" \
    --reporter=line 2>&1 | head -10
  # 截图保存到 /tmp/ai-preview/$COMPONENT.png
  # Claude Code 下次迭代时可以 Read 这张图（多模态）
  echo "预览已生成：/tmp/ai-preview/$COMPONENT.png"
fi

配合 visual-reviewer Subagent：

.claude/agents/visual-reviewer.md
---
name: visual-reviewer
description: 对比 Figma 原稿和实现截图，找出视觉差异
model: claude-opus-4-7
tools: [Read]   # 多模态 Read 支持图片
---

你是视觉审查专家。接收两张图（左：Figma 设计稿，右：代码实现），
输出 JSON 格式的差异列表：

{
  "matches": true | false,
  "diffs": [
    { "category": "color", "description": "按钮背景比 Figma 深 5%", "severity": "low" },
    { "category": "spacing", "description": "卡片 padding 偏大 8px", "severity": "medium" },
    { "category": "typography", "description": "标题字号应为 text-xl 实际 text-lg", "severity": "high" }
  ]
}

**不要**给修复建议，只做判断。修复由主 Agent 负责。

4.5.6 完整端到端示例

> /figma-to-component https://figma.com/file/XXX?node-id=123 UserCard

AI:
  [figma__get_node] 读取 Figma 节点
  → 识别：Card 组件，含头像 + 姓名 + 角色标签 + 操作按钮
  → Token 映射：全部命中项目设计系统 ✅

  [component-builder Skill] 加载模板
  [Edit] components/user-card.tsx
  [PostToolUse Hook] ✅ lint + tsc 通过

  [委派 test-writer Subagent] 并行
  [委派 visual-reviewer Subagent] 对比截图
  
  visual-reviewer 返回：
    ⚠️ 卡片 padding 比 Figma 小 4px（应该 p-6 不是 p-5）
    ⚠️ 头像尺寸 Figma 是 48px 代码是 40px

  [Edit] 修复两处
  [再截图] visual-reviewer 返回：✅ 完全一致

  完成：
  - components/user-card.tsx
  - components/user-card.test.tsx
  - 视觉对比报告 /tmp/ui-diff/user-card.md

效率对比：

传统手写 + 肉眼对齐：2-4 小时
Figma MCP + AI 生成 + 自动视觉验证：15-30 分钟
提升 5-8 倍

4.5.7 常见坑

坑	后果	避坑
把 Figma 原始色值写死到代码	设计改色全项目要改	严格走 Design Token
让 AI 自己创建新 Token	设计系统碎片化	找不到对应 Token 必须停下问
一个截图喂整页	AI 分析不准、生成冗长组件	拆成独立组件分别处理
不做视觉对比验证	AI 以为生成对了实则有偏差	visual-reviewer Subagent 必配
v0 生成的代码直接用	不符合项目规范	下载后用 Claude Code 适配一轮
忽略响应式	只做了桌面端	Figma 里多个 Frame（桌面/平板/手机）各生成一次
Dark Mode 漏掉	暗色模式坏掉	显式要求 AI 用 `dark:` 变体 + 测试两种模式

五、阶段 4：代码审查

AI 角色：自动初审、安全扫描、风格检查、补充测试建议。

阶段 I/O

输入：

.claude/artifacts/<feature-id>/01-requirements.md — 验证实现是否满足规格（不只看代码）
.claude/artifacts/<feature-id>/05-architecture.md — 验证是否偏离架构决策
.claude/artifacts/<feature-id>/08-file-changes.md — 改动清单
git diff main...HEAD — 实际 diff

资源：

security-reviewer Subagent（Opus，只读）
db-query-reviewer Subagent（针对 DB 查询）
claude-code-action（PR 自动 inline review）
Husky pre-commit Hook（本地快速预审）
security-checklist Skill

做法：

本地：/review-pr <feature-id> [focus]
推送 PR 后：claude-code-action 自动触发

产出：

.claude/artifacts/<feature-id>/09-review-report.md — 审查报告：
- 发现的问题（🔴 MUST_FIX / 🟡 SHOULD_FIX / 🔵 NICE_TO_HAVE）
- 每条问题的位置、描述、修复建议、修复状态
- 与需求不符的行为（对照 01-requirements.md 的验收标准）
- 与架构偏离的点（对照 05-architecture.md）
PR inline comments

下一步：修复 MUST_FIX → /gen-tests <feature-id> --diff

2026 年最佳实践：三层审查

5.1 `claude-code-action` PR 自动审查（推荐）

.github/workflows/ai-review.yml
name: AI Code Review

on:
  pull_request:
    types: [opened, synchronize]
  issue_comment:
    types: [created]  # 支持 @claude 追问

jobs:
  review:
    runs-on: ubuntu-latest
    permissions:
      pull-requests: write
      contents: read
      issues: write

    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }

      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          # 自动读取仓库 AGENTS.md + .claude/agents/*
          prompt: |
            审查此 PR 变更。按文件类型路由专业审查：
            
            - src/app/api/** → 委派 security-reviewer Subagent
            - lib/db/** → 委派 db-query-reviewer Subagent
            - src/components/** → 关注 React 性能
            - prisma/migrations/** → 关注数据迁移安全
            
            输出格式：
            - 🔴 MUST_FIX（阻塞合并）：Bug、安全漏洞、数据丢失
            - 🟡 SHOULD_FIX（建议修复）：性能、可维护性
            - 🔵 NICE_TO_HAVE（优化）：命名、简化
            - 🟢 GOOD（值得肯定）：好实践
            
            用 inline comment 精确到行，不要汇总评论。
          claude_args: |
            --allowedTools Read,Grep,Glob
            --max-turns 10

Action v1 使用 prompt + claude_args

direct_prompt、allowed_tools、model 等旧字段已迁移。需要运行 Bash、调用自定义 MCP 或访问 CI 日志时，要通过 claude_args / additional_permissions 明确授权，避免 CI 中权限过大或示例复制后不可用。

审查流程图：

5.2 Slash Command `/review-pr`

本地预审（在合并前、推送前自己先跑一遍）：

.claude/commands/quality/review-pr.md
---
name: review-pr
description: 审查当前分支改动（对照需求和架构产物）
argument-hint: "<feature-id> [focus: security|perf|types|all]"
---

审查 feature `$1` 相对 main 的改动。

Focus: ${2:-all}

## 步骤

1. Read `.claude/artifacts/$1/01-requirements.md`（作为"规格"）
2. Read `.claude/artifacts/$1/05-architecture.md`（作为"设计"）
3. Read `.claude/artifacts/$1/08-file-changes.md`（改动清单）
4. `git diff main...HEAD --stat` 看改动规模
5. `git log main..HEAD` 看 commit 消息
6. 逐个文件分析（按影响程度排序）

## 审查维度

**永远检查**：
- 实现是否满足 `01-requirements.md` 的验收标准
- 是否偏离 `05-architecture.md` 的约定

根据 focus：
- **security**: 委派 security-reviewer Subagent
- **perf**: 重点查 N+1 查询、不必要的重渲染、bundle 影响
- **types**: 重点查 any / as 断言 / 类型不完整
- **all**: 全部都查

## 输出

写入 `.claude/artifacts/$1/09-review-report.md`，结构：

# 审查报告 — `<feature-id>`
## 与需求的差异
（对照 01-requirements.md 的每条验收标准）
## 与架构的偏离
（对照 05-architecture.md）
## 代码问题
### 🔴 MUST_FIX
- `<file:line> <问题> <修复建议>`
### 🟡 SHOULD_FIX
### 🔵 NICE_TO_HAVE
## 值得肯定的实践


末尾汇总数量和修复优先级建议。

5.3 `security-reviewer` Subagent

见 AI 辅助开发 - Subagents 的完整配置。要点：

模型：Claude Opus 4.7（深度推理）
工具：只给 Read、Grep、Glob（物理上不能改代码）
输出：严格 JSON，便于 CI 消费
审查维度：XSS / SQL 注入 / 鉴权缺失 / 密钥泄露 / CSRF / 开放重定向 / SSRF

5.4 本地 pre-commit 预审

.husky/pre-commit
#!/bin/bash

# 基础 lint
pnpm lint-staged

# AI 快速预审（只查 MUST_FIX 级别，控制在 30s 内）
CHANGED=$(git diff --cached --name-only --diff-filter=ACM | grep -E '\.(ts|tsx)$')

if [ -n "$CHANGED" ]; then
  claude -p "快速检查 \`git diff --cached\` 是否有明显的 MUST_FIX 问题（Bug、安全、数据丢失）。只返回 JSON: {\"issues\":[{\"file\":\"\",\"line\":0,\"issue\":\"\"}]}" \
    --output-format json > /tmp/ai-review.json

  N=$(jq '.issues | length' /tmp/ai-review.json)
  if [ "$N" -gt 0 ]; then
    echo "🚫 AI 发现 $N 个严重问题："
    jq '.issues' /tmp/ai-review.json
    echo ""
    echo "使用 --no-verify 跳过（不推荐）"
    exit 1
  fi
fi

六、阶段 5：测试

AI 角色：测试用例生成、变异测试、视觉回归、测试维护。

核心升级：2026 年不再是"写完代码再补测试"，而是 Subagent 并行生成测试 + 测试从需求出发。

阶段 I/O

输入：

.claude/artifacts/<feature-id>/01-requirements.md — 测试的规格来源（从需求出发，不是从代码出发）
.claude/artifacts/<feature-id>/08-file-changes.md — 改动文件清单
.claude/artifacts/<feature-id>/09-review-report.md — 审查发现的可补测试场景
实际代码（实现细节，仅作参考）

资源：

test-writer Subagent（主力，并行生成测试）
test-patterns Skill（团队测试约定）
Vitest / Playwright / MSW
变异测试器（Stryker，可选）

做法：/gen-tests <feature-id> [--diff | <file-path>]

产出：

测试代码（*.test.ts、*.test.tsx、tests/**）
.claude/artifacts/<feature-id>/10-test-report.md — 测试报告：
- 覆盖率（语句 / 分支 / 函数 / 行）
- 测试数量 + 场景分布（正向 / 异常 / 边界）
- 验收标准 × 测试矩阵（对照 01-requirements.md 的每条标准，标注覆盖它的测试）
- 变异测试存活率（可选）
- 已知盲区（AI 判断覆盖不到的场景）

下一步：

盲区高风险 → 补手动测试
测试全绿 → 推送 PR 或 /ship <feature-id>

6.1 Slash Command `/gen-tests`

.claude/commands/quality/gen-tests.md
---
name: gen-tests
description: 从需求和改动生成测试，产出 10-test-report.md
argument-hint: "<feature-id> [file-path | --diff]"
---

生成测试：feature=$1，范围=${2:---diff}

## 步骤

1. **读规格**：Read `.claude/artifacts/$1/01-requirements.md`（这是"测试要验证什么"的来源）
2. **读改动清单**：Read `.claude/artifacts/$1/08-file-changes.md`
3. **读审查发现**：Read `.claude/artifacts/$1/09-review-report.md`（是否有遗漏场景）

4. 确定范围：
   - 参数是文件路径 → 只给该文件生成
   - 参数是 `--diff` 或无参 → `git diff main...HEAD --name-only`

5. **委派 test-writer Subagent**（并行处理多个文件）：
   - 每个文件独立一个 Subagent session
   - **传入 `01-requirements.md` 路径，强调"从需求出发"**
   - 主 Agent 聚合结果

6. Subagent 生成后：
   - 运行 `pnpm test <file>` 验证通过
   - 失败则 Subagent 自己修复（最多 3 轮）

7. **Write `.claude/artifacts/$1/10-test-report.md`**：
   - 覆盖率统计
   - 测试数量 + 场景分布
   - 验收标准 × 测试矩阵：

| 验收标准 | 对应测试文件:行 | 状态 |

- 已知盲区清单（AI 判断）

6.2 Skill `test-patterns`

.claude/skills/test-patterns/SKILL.md
---
name: test-patterns
description: |
  团队测试模式。触发：用户需要写测试、讨论测试策略时。
---

# 测试模式

## 分层

| 层级 | 工具 | 覆盖 |
|-----|------|-----|
| 单元测试 | Vitest | 工具函数、Hook、纯逻辑 |
| 组件测试 | Vitest + RTL | 组件行为（非实现细节） |
| 集成测试 | Vitest + MSW | API 路由、DB 集成 |
| E2E | Playwright | 关键用户流程 |

## 原则

1. **需求驱动不是代码驱动**：测试验证规格，不是复述实现
2. **行为测试 > 实现测试**：`getByRole('button', {name: '提交'})` > `getByTestId('submit-btn')`
3. **Mock 最小化**：只 mock 网络、DB、时钟
4. **边界优先**：null、undefined、空数组、空字符串、恰好等于阈值
5. **异步用 `findBy*`**：不用 `waitFor` 手动等

## 模板

见 `templates/`：
- `unit.test.ts` — 工具函数测试
- `hook.test.ts` — Hook 测试
- `component.test.tsx` — 组件测试
- `api.test.ts` — API 集成测试

## 变异测试

对关键逻辑用 Stryker 跑变异测试，找测试盲区。

6.3 Slash Command `/mutation-test`

变异测试：AI 智能生成"能揭示测试盲区"的变异：

.claude/commands/quality/mutation-test.md
---
name: mutation-test
description: AI 变异测试（发现测试盲区）
argument-hint: "[file-path]"
---

对 $ARGUMENTS 做变异测试。

## 步骤

1. 读取源代码和对应测试
2. **生成有意义的变异**（不是无脑替换）：
   - 边界改动：`>` ↔ `>=`、`<` ↔ `<=`
   - 逻辑翻转：`&&` ↔ `||`
   - 返回值改变：`return true` → `return false`
   - 常量替换
   - 条件删除
3. 对每个变异，评估：
   - 当前测试是否仍然通过？
   - 如果通过 → 意味着**缺少覆盖此场景的测试**
4. 输出盲区清单

## 输出

```json
{
  "mutants_killed": 8,
  "mutants_survived": 3,
  "survival_rate": "27%",
  "blind_spots": [
    {
      "line": 42,
      "original": "if (age >= 18)",
      "mutated": "if (age > 18)",
      "missing_test": "缺少 age === 18 的边界测试"
    }
  ]
}
```

6.4 视觉回归 + AI 分析

tests/visual.spec.ts
import { test, expect } from '@playwright/test';

test.describe('视觉回归', () => {
  test('聊天页面 - 桌面端', async ({ page }) => {
    await page.goto('/chat/test-id');
    await page.waitForSelector('[data-testid="message-list"]');
    
    // 等所有图片加载完
    await page.waitForFunction(() => 
      Array.from(document.images).every(img => img.complete)
    );
    
    await expect(page).toHaveScreenshot('chat-desktop.png', {
      maxDiffPixelRatio: 0.01,
      animations: 'disabled',
    });
  });
});

进阶：对于 CI 失败的截图差异，调用多模态 AI 分析：

scripts/analyze-visual-diff.ts
// 当视觉回归失败，让 AI 判断是否真的是 regression
const baseline = await fs.readFile('tests/snapshots/chat-desktop.png');
const actual = await fs.readFile('test-results/chat-desktop-actual.png');

const analysis = await claude.messages.create({
  model: 'claude-sonnet-4-6',
  messages: [{
    role: 'user',
    content: [
      { type: 'image', source: { type: 'base64', media_type: 'image/png', data: baseline.toString('base64') }},
      { type: 'image', source: { type: 'base64', media_type: 'image/png', data: actual.toString('base64') }},
      { type: 'text', text: '对比两张截图。第一张是基线，第二张是当前。是真正的视觉 regression 还是字体渲染等无关差异？' },
    ],
  }],
});

七、阶段 6：调试

AI 角色：错误分析、根因定位、二分查找、复现方案。

关键动作：结构化调试 Prompt。不结构化的 Prompt 是调试效率杀手。

阶段 I/O

输入：

Bug 现象描述（必填 7 项，见 /debug 模板）
Sentry Issue ID 或 URL（通过 MCP 自动拉完整上下文）
.claude/artifacts/<feature-id>/05-architecture.md — 理解代码边界和数据流
.claude/artifacts/<feature-id>/11-bug-log.md（如存在）— 看是否已经遇到过类似问题

资源：

Sentry MCP（线上错误）
bug-hunter Skill（疑难 Bug 模式库）
bug-hunter Subagent（Opus，深度推理）
git bisect（定位引入 commit）

做法：

/debug（结构化填 Bug 信息）
/debug SENTRY-XYZ（直接从 Sentry 拉）
/bisect <bad> <good>（定位引入 commit）

产出：

修复代码（新 commit）

追加到 .claude/artifacts/<feature-id>/11-bug-log.md：

## Bug #N — <一句话摘要>
- 现象 / 期望 vs 实际 / 环境
- Sentry 链接（如有）
- 根因（5 Whys）
- 引入 commit（如定位到）
- 修复 commit
- 修复后的回归测试位置
- 预防措施（写入哪个 rule / skill / hook）

下一步：更新受影响的 Skill / Rule，避免同类问题再犯

7.1 Slash Command `/debug`

.claude/commands/debug/debug.md
---
name: debug
description: 结构化调试流程
---

请按以下结构告诉我 Bug 信息。**如果缺少任何一项，先反问补充**，不要急着给答案：

## 必填

### 1. 现象
（用户看到的，精确描述）

### 2. 期望 vs 实际
期望：...
实际：...

### 3. 复现步骤
1. ...
2. ...
3. ...

### 4. 环境
- 浏览器 + 版本
- OS
- 环境：开发 / 预发 / 生产

### 5. 错误日志/堆栈
（完整粘贴，不要省略）

## 选填但强烈建议

### 6. 已试过的排查
（避免我重复你做过的事）

### 7. 相关代码
（@mention 或粘贴）

---

**收到完整信息后**：

1. **根因假设**：按概率排序列 3 个最可能原因
2. **验证方法**：每个假设给出验证手段
3. **推荐先验证哪个**：说明理由
4. 等我验证结果再继续

**不要**：
- 不要未验证就给修复方案
- 不要猜测"可能是……也可能是……"
- 不要给 10 个低概率猜测

7.2 Skill `bug-hunter` + Subagent

.claude/skills/bug-hunter/SKILL.md
---
name: bug-hunter
description: |
  疑难 Bug 排查。
  触发：用户描述"有个 Bug"、"奇怪的问题"、"偶尔出现"、"无法复现"时。
---

# Bug Hunter

## 典型疑难 Bug 模式

### 1. 竞态条件（Race Condition）
- 症状：偶尔出现、刷新或重试后正常
- 排查：检查 async 调用顺序、是否缺 AbortController、useEffect 依赖

### 2. 闭包陷阱
- 症状：事件处理器里拿到过期的 state
- 排查：useRef 或 useEffect 依赖数组

### 3. Hydration 不一致
- 症状："Text content does not match"、样式闪烁
- 排查：服务端 vs 客户端渲染差异（Date.now、Math.random、typeof window）

### 4. CSS 层叠/特异性
- 症状：样式不生效但选择器看起来对
- 排查：DevTools 计算样式面板看被哪个规则覆盖

### 5. 内存泄漏
- 症状：页面越用越卡、内存曲线只涨不降
- 排查：Chrome Memory Profiler Heap Snapshot

### 6. 网络抖动
- 症状：慢速网络下功能异常
- 排查：Chrome Network 面板 Slow 3G 模拟

## 常用工具

- **git bisect** — 二分定位引入 Bug 的 commit
- **Chrome DevTools Performance** — 性能问题
- **React DevTools Profiler** — 重渲染分析
- **Sentry** — 生产错误

7.3 Slash Command `/bisect`

.claude/commands/debug/bisect.md
---
name: bisect
description: 用 git bisect + AI 分析定位引入 Bug 的 commit
argument-hint: "[bad-commit] [good-commit]"
---

用 git bisect 定位引入 Bug 的 commit。

## 参数
Bad: ${1:-HEAD}
Good: $2

## 步骤

1. `git bisect start`
2. `git bisect bad $1`
3. `git bisect good $2`
4. 对每个中间 commit：
   - 问用户如何验证（是否能复现 Bug）？
   - 用户确认后跑 `git bisect good/bad`
5. 定位到具体 commit 后：
   - `git show` 看这个 commit 的改动
   - 分析这个改动为何引入 Bug
   - 给出修复建议
6. `git bisect reset` 恢复

**进阶**：如果有自动化测试能验证，用 `git bisect run <script>` 全自动。

7.4 Sentry MCP 集成

.claude/settings.json
{
  "mcpServers": {
    "sentry": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-sentry"],
      "env": {
        "SENTRY_AUTH_TOKEN": "${env:SENTRY_TOKEN}",
        "SENTRY_ORG": "yourcompany"
      }
    }
  }
}

使用：

> /debug SENTRY-ISSUE-1234

AI: [调用 sentry__get_issue(1234)]
[获得完整错误堆栈、用户会话、相关 breadcrumbs]
[Grep 源代码定位相关模块]
[输出根因分析]

不用手动复制粘贴错误日志——AI 直接从 Sentry 读。

八、阶段 7：文档

AI 角色：API 文档、Changelog、README、代码注释。

核心原则：从代码自动提取，不要 AI 编造。

阶段 I/O

输入：

实际代码（API route、Zod Schema、类型定义）— 文档的唯一事实来源
.claude/artifacts/<feature-id>/01-requirements.md — 用户视角的价值描述（用于 Changelog）
.claude/artifacts/<feature-id>/11-bug-log.md — 修复列入 Changelog
git log — Commit 历史

资源：

doc-patterns Skill
doc-writer Subagent
飞书 MCP（可回写到内部知识库）
PostMerge Hook（合并后自动同步）

做法：

/gen-api-docs（扫描 src/app/api/**）
/update-readme
/gen-changelog <since-tag>

产出：

docs/api.md — API 文档（增量更新、保留人工章节）
CHANGELOG.md — 用户可感知的 Changelog
飞书发版说明文档（可选，通过 feishu__create_doc 回写）
README 更新

下一步：Changelog 准备好 → /ship <feature-id>

8.1 Slash Command `/gen-api-docs`

.claude/commands/docs/gen-api-docs.md
---
name: gen-api-docs
description: 从代码自动生成 API 文档
---

扫描 `src/app/api/**/route.ts` 生成 API 文档。

## 严格规则

1. **只从代码提取**：HTTP 方法、路径、Zod Schema、响应类型
2. **不要编造**：如果代码里没有，就写"未标注"
3. **引用代码位置**：每个接口标注 `src/app/api/xxx/route.ts:42`

## 输出结构

按 URL 路径分组：

```
# API 文档

## /api/users

### GET /api/users
- 认证：需要 Bearer Token
- 限流：100/min
- 参数：...
- 响应：...
- 错误码：...
- 示例：
  ```bash
  curl -X GET ...
  ```
- 源码：src/app/api/users/route.ts:10
```

## 增量更新

如果已经有 `docs/api.md`：
- 只补充新增接口
- 标记已删除接口为 `[Deprecated]`
- 保留手工写的"使用场景"、"注意事项"等人工章节

8.2 Slash Command `/gen-changelog`

.claude/commands/docs/gen-changelog.md
---
name: gen-changelog
description: 从 commit 生成用户可读 Changelog
argument-hint: "[since-tag]"
---

生成从 `${ARGUMENTS:-上一个 tag}` 到 HEAD 的 Changelog。

## 步骤

1. `git log <since>..HEAD --pretty=format:"%h|%s|%b" --no-merges`
2. 按 conventional commit 类型分组：
   - `feat:` → 新功能
   - `fix:` → Bug 修复
   - `perf:` → 性能优化
   - `refactor:` → 重构
   - `docs:` → 文档
   - Breaking changes（commit body 含 `BREAKING CHANGE:`）→ 置顶

3. **关键**：每条用**用户可感知**的描述，不是代码层面
   - ❌ "修复 UserService.getById 的 N+1 查询"
   - ✅ "用户列表页加载速度提升 5 倍"

4. 关联 PR：`(#123)` 链接

## 输出

```markdown
# v2.3.0 (2026-XX-XX)

## 🚨 Breaking Changes
- ...

## ✨ 新功能
- 支持拖拽上传图片到聊天框 (#125)

## 🐛 Bug 修复
- 移动端输入法不再重复发送消息 (#130)

## ⚡ 性能优化
- 消息列表滚动性能提升 50% (#128)
```

8.3 PostMerge Hook 自动同步

合并到 main 时自动更新文档：

.github/workflows/auto-docs.yml
on:
  push:
    branches: [main]
    paths:
      - 'src/app/api/**'

jobs:
  update-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Update API docs
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          claude -p "运行 /gen-api-docs 更新 docs/api.md" > /dev/null
      
      - name: Commit if changed
        run: |
          git config user.name "auto-doc-bot"
          git config user.email "bot@example.com"
          git add docs/api.md
          git diff --staged --quiet || git commit -m "docs: auto-update API docs"
          git push

九、阶段 8：部署

AI 角色：CI/CD 配置生成、部署问题排查、发布清单。

红线：AI 不能自主部署生产，部署必须人工触发。

阶段 I/O

输入：

.claude/artifacts/<feature-id>/10-test-report.md — 验证测试覆盖达标
.claude/artifacts/<feature-id>/09-review-report.md — MUST_FIX 已全部处理
.claude/artifacts/<feature-id>/03-risks.md — 发布前对照是否已缓解
CHANGELOG.md、docs/api.md — 文档已更新
Prisma migration、环境变量、FeatureFlag 配置

资源：

release-flow Skill（发布规范）
deploy-troubleshoot Skill（部署问题排查）
PreToolUse Hook（拦截生产破坏性命令）
K8s / Vercel MCP（可选，查部署状态）

做法：/ship <feature-id> <env: staging|production>

产出：

.claude/artifacts/<feature-id>/12-release-checklist.md — 发布前检查清单（逐项 ✅ 或说明豁免理由）：
- 代码、测试、性能、安全、文档、回滚预案 6 大维度
- 引用上游产物作为依据（例：测试覆盖 → 引用 10-test-report.md）
.claude/artifacts/<feature-id>/13-runbook.md — 上线运维手册：
- 发布命令、发布顺序、灰度节奏
- 回滚命令（含数据库 migration down 脚本）
- 监控关键指标 + 告警阈值
- 联系人 + on-call

下一步：

Staging 验证 → 生产发布（人工执行）
发布后监控 15 分钟

9.1 Slash Command `/ship`

.claude/commands/ops/ship.md
---
name: ship
description: 发布流程检查清单
argument-hint: "[env: staging|production]"
---

准备发布到 ${ARGUMENTS:-staging}。

## 发布前检查

### 1. 代码就绪
- [ ] 所有 PR 已合并
- [ ] main 分支 CI 全绿
- [ ] 没有未解决的 P0/P1 Bug

### 2. 测试覆盖
- [ ] 单元测试覆盖率 ≥ 80%
- [ ] E2E 关键流程全通
- [ ] 手动回归关键路径（列出清单）

### 3. 性能
- [ ] Lighthouse Core Web Vitals 无退化
- [ ] Bundle size 在预算内

### 4. 安全
- [ ] 依赖无 high/critical 漏洞
- [ ] `security-reviewer` 最近扫描通过

### 5. 文档
- [ ] Changelog 已更新
- [ ] Breaking changes 已通知

### 6. 回滚预案
- [ ] 回滚命令明确（写到 runbook）
- [ ] 数据库 migration 有 down 脚本

## 发布时

生产环境发布**需要人工执行**。以下命令不要 AI 自动执行：

```bash
# 人工跑
pnpm run release
git tag v2.3.0
git push origin v2.3.0
```

## 发布后

- [ ] 监控看板 15 分钟（错误率、延迟、QPS）
- [ ] 发布通知（Slack / 邮件）
- [ ] 更新 `.claude/memory/releases.md`

9.2 PreToolUse Hook 拦截生产破坏性操作

.claude/hooks/pre-bash-guard.sh
#!/bin/bash
INPUT=$(cat)
CMD=$(echo "$INPUT" | jq -r '.tool_input.command')

# 生产相关的破坏性命令黑名单
PROD_DANGER=(
  "kubectl delete.*prod"
  "aws s3 rm.*--recursive"
  "dropdb.*prod"
  "truncate.*prod"
  "DROP TABLE"
  "DROP DATABASE"
  "git push.*main.*--force"
  "prisma migrate deploy.*prod"
)

for pattern in "${PROD_DANGER[@]}"; do
  if echo "$CMD" | grep -qE "$pattern"; then
    echo "🚫 BLOCKED: 生产破坏性命令不允许自动执行" >&2
    echo "命令: $CMD" >&2
    echo "如需执行，请人工在终端操作" >&2
    exit 2
  fi
done

9.3 部署问题排查

.claude/skills/deploy-troubleshoot/SKILL.md
---
name: deploy-troubleshoot
description: |
  部署问题排查。触发：用户提到"部署失败"、"上线后报错"、"CDN"、"hydration"问题时。
---

# 部署问题排查

## 常见 5 类问题

### 1. ChunkLoadError
**症状**：`Loading chunk xxx failed`  
**根因**：CDN 缓存旧 chunk，路由切换时加载到 404  
**排查**：检查 `next.config.js` 的 `assetPrefix`、CDN 缓存策略  
**修复**：加版本化 chunk name + 服务端 chunk 存在校验

### 2. Hydration Mismatch
**症状**：`Text content does not match server-rendered HTML`  
**根因**：SSR 和 CSR 渲染结果不一致  
**排查**：检查 Date、Math.random、typeof window、localStorage 使用点  
**修复**：用 `useEffect` 或 `suppressHydrationWarning`

### 3. 环境变量缺失
**症状**：线上报 `undefined`，本地正常  
**排查**：对比 `.env.example` 和生产配置，看是否漏配  
**预防**：启动时 Zod 校验所有环境变量

### 4. CORS 错误
**症状**：`Access-Control-Allow-Origin`  
**排查**：API 和前端是否同域？Nginx / Vercel headers 配置？

### 5. Standalone 部署缺文件
**症状**：Next.js standalone 部署后 public/ 或静态文件 404  
**修复**：部署脚本需额外 copy `public/` 和 `.next/static/`

十、阶段 9：监控与事件响应

AI 角色：异常分级、根因分析、Postmortem 生成。

阶段 I/O

输入：

告警（Sentry / PagerDuty / 自建）
.claude/artifacts/<feature-id>/13-runbook.md — 查询告警阈值、联系人、回滚命令
.claude/artifacts/<feature-id>/05-architecture.md — 快速理解出问题的模块
Sentry / Grafana / K8s 实时数据（MCP）

资源：

Sentry / PagerDuty / Grafana MCP（实时拉数据）
incident-playbook Skill（事件响应流程）
bug-hunter Subagent（深度根因）

做法：

告警触发：/triage <sentry-url>
事件结束：/postmortem <incident-id>

产出：

.claude/artifacts/<feature-id>/14-incident-log.md — 事件日志（追加式）：
- 时间线（何时触发、何时定位、何时缓解、何时解决）
- 分级（P0-P3）+ 根因假设
- 采取的缓解操作（回滚 / Feature Flag / 热修）
- 影响范围（用户数、持续时长、业务损失）
.claude/artifacts/<feature-id>/15-postmortem.md — 复盘报告（blameless）：
- Summary / Impact / Timeline / 5 Whys / What went well-wrong-lucky / Action Items
Action Items 回写到 PM 系统（飞书任务、Jira、Linear）

反馈闭环：

高频问题 → 更新 bug-hunter Skill 中的模式库
监控盲区 → 更新 13-runbook.md 模板，下次新功能有更好的告警
Postmortem 反哺 03-risks.md 模板（同类风险下次被识别出来）

10.1 Slash Command `/triage`

.claude/commands/ops/triage.md
---
name: triage
description: 对告警做自动分级和初步分析
argument-hint: "[sentry-url 或 alert-id]"
---

对告警做分级：$ARGUMENTS

## 步骤

1. **拉取告警详情**
   - 如果是 Sentry URL → `sentry__get_issue(id)`
   - 否则从 PagerDuty / Grafana MCP 拉

2. **相关上下文收集**
   - 最近 24h 的部署记录
   - 相关服务的监控曲线
   - 最近 3 次 commit 的改动

3. **分级**
   - **P0（紧急）**：核心功能完全不可用、全量用户、数据丢失
   - **P1（严重）**：核心功能部分不可用、大量用户
   - **P2（一般）**：非核心、少量用户
   - **P3（轻微）**：体验问题、不影响核心流程

4. **根因猜测**
   - 按概率排序 3 个假设
   - 每个假设给出验证命令/查询

5. **临时缓解**
   - 能不能关 Feature Flag？
   - 能不能 rollback？
   - 需要紧急手动介入吗？

6. **通知建议**
   - 是否需要通知 on-call？
   - 是否需要对外公告？

10.2 Slash Command `/postmortem`

.claude/commands/ops/postmortem.md
---
name: postmortem
description: 生成事件复盘报告
argument-hint: "[incident-id]"
---

生成 incident $ARGUMENTS 的 Postmortem。

## 数据收集

1. 事件详情（PagerDuty / Sentry MCP）
2. 时间线（Slack incidents channel / 事件记录）
3. 已采取的操作（runbook 执行记录）
4. 受影响指标（Grafana MCP 查曲线）

## 生成标准 Postmortem

```markdown
# Postmortem: <事件名> (YYYY-MM-DD)

## Summary
一句话总结

## Impact
- 用户数：
- 持续时间：
- 功能影响：
- 商业影响：$

## Timeline
| 时间 | 事件 | 操作人 |

## Root Cause (5 Whys)
Why 1: 为什么 X 发生？ → ...
Why 2: 为什么 Y 发生？ → ...
...

## Contributing Factors
- ...

## What Went Well
- ...（做得好的，避免 blame culture）

## What Went Wrong
- ...

## Lucky Breaks
- ...（运气好的，本可以更严重）

## Action Items
| 优先级 | 行动 | 负责人 | 截止 |
```

**原则**：
- 不指责个人（blameless）
- 聚焦系统改进（流程、工具、监控）
- Action items 必须有负责人和截止日期

10.3 AI 辅助事件响应的关键

秒级分级：告警一到自动跑 /triage，不用等人判断
根因辅助：AI 不给出"一定是 X"的断言，而是"3 个假设 + 验证方法"
决策权在人：是否回滚、是否通知客户——这些是人的责任，AI 不能决定
Postmortem 自动化：事件结束后 24h 内出初稿，人工审核补充

十一、端到端示例：3 天完成完整功能

真实案例，展示所有阶段如何通过 .claude/artifacts/<feature-id>/ 目录串联：

目标：给一个知识库应用加「AI 智能摘要」功能 feature-id：ai-summary-2301（飞书 PRD 文档 token）

Day 1（需求 + 设计 + 基础）— 6 小时

上午（2h）：需求分析 + 技术设计

# 09:00
> /analyze-req ai-summary-2301 https://xxx.feishu.cn/docx/AbcDefGhi

AI: [feishu__get_doc] 读飞书 PRD
    [读 memory/product-context、tech-stack、past-estimates]
    [Bash] mkdir -p .claude/artifacts/ai-summary-2301
    [Write] 01-requirements.md (5 Stories)
    [Write] 02-tasks.md (13 Task / 21 SP)
    [Write] 03-risks.md (5 风险，2 高危：成本、LLM 不稳定)
    [Write] 04-open-questions.md (4 个问题)

→ 把 04-open-questions 发 PM → 20 分钟后 PM 在飞书回复 → 更新 04

# 10:30
> /design-arch ai-summary-2301

AI: [Read] 01/02/03/04
    [Plan Mode] [Grep 现有 llm 调用、Read ai-sdk wrapper]
    [Write] 05-architecture.md（架构图 + Prisma schema + API 契约）
    [Write] 06-adr.md（3 方案对比 → 选 B：后台任务 + Redis 缓存）
    [Write] 07-implementation-plan.md（15 步，标注关键路径）

→ Review 05 + 06 → 批准

下午（4h）：数据模型 + 核心 API（按 07-implementation-plan.md 顺序）

# 13:00
> /new-migration ai-summary-2301 "add summaries table"
AI: [Read] 05-architecture.md 里的 Prisma schema 段
    [Edit] prisma/migrations/.../migration.sql
    [Append] 08-file-changes.md

# 13:30
> /new-api ai-summary-2301 summaries
AI: [Read] 05-architecture.md 里的 /api/summaries 契约
    [调用 api-route Skill] → app/api/summaries/route.ts
    [PostToolUse Hook] ✅ lint/tsc
    [委派 test-writer Subagent] → 并行生成 route.test.ts
    [Edit] lib/queue/summary-worker.ts（后台 worker）
    [Append] 08-file-changes.md（4 个新文件 + commit hash）

Day 2（业务逻辑 + 前端）— 7 小时

上午（3h）：LLM 集成 + 业务逻辑

# 09:00
> 按 plan 第 6 步实现 generateSummary
AI: [Read] 05-architecture.md（知道该用 ai-sdk wrapper）
    [Edit] lib/ai/summarize.ts（含重试 / 超时 / fallback）
    [Edit] lib/ai/prompts/summary.md
    [Append] 08-file-changes.md

# 11:00
遇到 Bug：偶尔 LLM 返回空字符串
> /debug SENTRY-ERR-7823

AI: [sentry__get_issue] 拉完整堆栈 + breadcrumbs
    [Read] 05-architecture.md（理解数据流）
    [Grep] summarize.ts 的错误处理
    根因假设 3 个 → 推荐先验证"上下文超长被截断"
    → 验证确认 → 修复：加预检和分段摘要
    [Append] 11-bug-log.md（现象 / 根因 / 修复 commit / 预防措施：
              加到 ai-sdk Skill 的 tips 里，下次新用法会被警告）

下午（4h）：前端组件 + UI

# 14:00
> /new-component ai-summary-2301 SummaryCard
AI: [Read] 05-architecture.md 的状态管理段
    [调用 component-builder Skill]
    [Edit] components/summary-card.tsx
    [Subagent test-writer] 并行 → summary-card.test.tsx
    [Append] 08-file-changes.md

# 15:30
> /new-page ai-summary-2301 docs/[id]/summary
AI: [Edit] app/docs/[id]/summary/{page,loading,error}.tsx
    [Append] 08-file-changes.md

Day 3（测试 + 审查 + 发布）— 5 小时

上午（2h）：完整测试 + 本地审查

# 09:00
> /gen-tests ai-summary-2301 --diff
AI: [Read] 01-requirements.md（规格）/ 08-file-changes.md / 09-review-report.md
    [委派 test-writer Subagent × 5 并行]
    5 个新文件全部有测试
    [Write] 10-test-report.md：
      - 覆盖率 87%
      - 验收标准 × 测试矩阵：5/5 全覆盖
      - 盲区：长文档（>50k token）场景未测（标注为待人工验证）

# 10:30
> /review-pr ai-summary-2301 security
AI: [Read] 01 + 05 + 08
    [委派 security-reviewer]
    发现 1 个 MUST_FIX：API 没做 rate limit → 修复
    [Write] 09-review-report.md（1 MUST_FIX 已修，2 SHOULD_FIX 已修）

中午（1h）：推送 PR + CI 审查

# 11:30
git push
→ PR #542 创建（描述体自动引用 .claude/artifacts/ai-summary-2301/ 中的产物）
→ claude-code-action 读 01 + 05 + 09 自动审查
→ 团队 reviewer @张三："AI 已对照需求和架构审过，我只看核心业务逻辑" → 10 分钟批准

下午（2h）：发布 + 监控

# 14:00
merge 到 main → 自动部署到 staging
手动回归（对照 01-requirements.md 的验收标准逐条） → 通过

# 15:00
> /ship ai-summary-2301 production
AI: [Read] 09 + 10 + 03
    [Write] 12-release-checklist.md（每项引用上游产物作依据）
    [Write] 13-runbook.md（发布命令 / 回滚命令 / 告警阈值 / on-call）
    → 展示清单 → 用户确认 → **用户手动跑** `pnpm release`

# 15:30
Vercel 完成部署
> 监控 15 分钟（按 13-runbook.md 指标）→ 无异常

# 16:00
> /gen-changelog since=v2.3.0
AI: [Read] 01-requirements.md（用户价值）+ 11-bug-log.md（修复项）
    生成 v2.4.0 CHANGELOG.md → 飞书回写发版通知

产物目录最终状态：

.claude/artifacts/ai-summary-2301/
├── 01-requirements.md       ✅ Day 1 上午
├── 02-tasks.md              ✅ Day 1 上午
├── 03-risks.md              ✅ Day 1 上午
├── 04-open-questions.md     ✅ Day 1 上午（PM 已回答）
├── 05-architecture.md       ✅ Day 1 上午
├── 06-adr.md                ✅ Day 1 上午
├── 07-implementation-plan.md ✅ Day 1 上午
├── 08-file-changes.md       ✅ Day 1-2（每步追加）
├── 09-review-report.md      ✅ Day 3 上午
├── 10-test-report.md        ✅ Day 3 上午
├── 11-bug-log.md            ✅ Day 2（LLM 空返回 Bug）
├── 12-release-checklist.md  ✅ Day 3 下午
└── 13-runbook.md            ✅ Day 3 下午

下次上线若出线上问题，会追加 14-incident-log.md + 15-postmortem.md，闭环完整。

效率对比：

阶段	传统	AI 全流程
需求分析	2h	1h
技术设计	4h	1h
代码实现	2 天	0.5 天
测试	1 天	2h
审查 + 修复	4h	1h
文档 + 发布	2h	0.5h
总计	6-7 天	3 天

效率提升 ≈ 2.5x。注意：效率提升不是 AI 取代了人，而是：

样板代码用 Skill 自动生成
测试并行由 Subagent 生成
质量检查由 Hook + Subagent 自动化
人力聚焦在架构决策、业务逻辑、质量终审——这是真正的价值所在

十二、全流程效能度量

12.1 核心指标看板

接 Gateway（LiteLLM）日志到 Metabase，5 大维度：

核心指标 SQL 示例
-- 1. 各阶段 AI 使用占比（从 Slash Command 类型统计）
SELECT 
  SUBSTRING(command FROM '/([^ ]+)') AS stage,
  COUNT(*) AS usage_count
FROM litellm_requests
WHERE command LIKE '/%'
GROUP BY stage
ORDER BY usage_count DESC;

-- 2. Feature 平均交付时间（对比基线）
SELECT 
  DATE_TRUNC('month', pr_merged_at) AS month,
  AVG(EXTRACT(EPOCH FROM (pr_merged_at - issue_started_at)) / 3600) AS avg_hours
FROM github_pr_with_jira
GROUP BY month;

-- 3. AI 代码 Bug 率
SELECT 
  DATE_TRUNC('month', bug_reported_at) AS month,
  COUNT(*) FILTER (WHERE introduced_by = 'ai') * 100.0 / COUNT(*) AS ai_bug_rate
FROM bugs_with_attribution
GROUP BY month;

-- 4. Skill 触发准确率
SELECT 
  skill_name,
  SUM(was_correct_trigger::int) * 100.0 / COUNT(*) AS accuracy
FROM skill_triggers_audit
GROUP BY skill_name
HAVING COUNT(*) > 20;

-- 5. 按阶段统计成本
SELECT 
  stage,
  SUM(input_tokens * 0.000003 + output_tokens * 0.000015) AS cost_usd
FROM litellm_requests
WHERE created_at > NOW() - INTERVAL '30 days'
GROUP BY stage;

12.2 月度效能报告模板

# 2026-XX AI 全流程效能月报

## 总览
- AI 使用率：50/50 = 100%
- Gateway 总花费：$3,200
- ROI：约 6.8x

## 各阶段数据

### 需求分析
- `/analyze-req` 使用：123 次
- 平均节省：45 分钟/需求
- 月度价值：123 × 0.75h × $30 = $2,768

### 代码生成
- Skill 触发：1,540 次
- 采纳率：87%
- Top 3 Skill:
  1. api-route: 410 次
  2. component-builder: 320 次
  3. form-builder: 280 次

### 代码审查
- claude-code-action 触发：156 PR
- AI 发现 MUST_FIX：23 个（全部被修复）
- AI 发现 SHOULD_FIX：67 个（85% 修复）

### 测试
- Subagent 生成测试：480 个
- 覆盖率：平均 82%（上月 74%）

### 调试
- `/debug` 使用：89 次
- 平均定位时间：从 2.1h → 0.8h

### 部署
- 发布次数：12 次
- 无 P0 事件

## 问题与改进
- `api-route` Skill 触发准确率偏低（72%），需要优化 description
- 某团队的 `component-builder` 使用率低，需要培训

## 下月计划
- 新增 `mobile-component` Skill
- 接入 Grafana MCP

十三、常见反模式

反模式	后果	正解
全流程用同一个 Prompt	各阶段效率都平平	每阶段有专用 Slash Command
不用 Plan Mode 就开干大型改动	方向错了返工惨重	强制 `/plan`
测试放到最后补	测试草率、覆盖低	Subagent 并行生成（和业务代码同步）
不委派 Subagent 什么都主 Agent 干	主上下文膨胀、质量下降	大任务、审查类任务必用 Subagent
让 AI 自主部署	灾难性风险	Hook 拦截 + 人工触发
Postmortem 写成责任追究	团队文化受损	Blameless，聚焦系统改进
不度量 AI 效能	说不清 ROI	Day 1 接 Gateway + Metabase

十四、面试速答与追问清单

3 分钟速答版

如果面试官问“AI 如何参与完整研发流程”，可以这样答：

需求阶段：AI 读 PRD/Jira/飞书，产出 User Stories、任务拆解、风险和澄清问题。
设计阶段：强制 Plan Mode 只读探索，产出架构图、API 契约、数据模型、ADR 和实施计划。
实现阶段：高频样板交给 Skills/脚本，主 Agent 写业务，test-writer Subagent 并行补测试。
质量阶段：Hook 自动 lint/typecheck，PR 用 claude-code-action 和安全 Subagent 初审，人工只聚焦业务和架构。
上线阶段：AI 生成发布清单、runbook、回滚预案和监控项，但生产发布、DB migration、灰度决策必须人工确认。
复盘阶段：告警自动 triage，事件结束后生成 blameless postmortem，并把经验反哺 Rules/Skills。

一句话总结：AI 做执行和穷举，人做决策和最终负责；每个阶段都要有产物、校验和反馈闭环。

10 分钟展开版

按“输入 → AI 能力 → 产物 → 校验 → 下一阶段”展开每个阶段。重点讲 .claude/artifacts/<feature-id>/ 作为贯穿全流程的事实源：需求、设计、实现清单、审查报告、测试报告、发布清单、runbook、事件复盘都落盘。这样跨会话、跨人、跨 Agent 都能接续，也方便审计和复盘。

高频追问

追问	回答要点
为什么要把产物落盘？	跨会话延续、跨人交接、跨 Agent 协作、可审计、可复用
Plan Mode 解决什么问题？	避免未理解代码就乱改；先读代码和产物，再由人批准执行
测试为什么要从需求出发？	代码驱动测试容易复述实现，需求驱动测试才能覆盖验收标准
AI 审查能替代人工吗？	不能；AI 查类型、安全、重复、边界，人查业务语义和架构权衡
部署阶段 AI 的红线是什么？	不自动部署生产、不自动执行不可逆 migration、不绕过审批
如何处理 AI 输出不稳定？	golden set、回归评测、交叉验证、人工确认、灰度和 kill switch
如何度量全流程收益？	阶段耗时、PR 周期、测试覆盖、缺陷率、事故数、成本和采纳率
如何把一次事故变成资产？	Postmortem action item 回写到 Rule、Skill、Hook、测试和 runbook

阅读分工

本篇回答“从需求到上线怎么串起来”。五件套工具细节见 AI 辅助开发，企业级平台和治理见 AI 研发基建。

常见面试问题

Q1: 描述 AI 参与全流程研发的最佳实践

答案：

2026 年的核心理念是 "把每个研发阶段的流程固化为 Slash Command / Skill / Subagent / Hook"，而非每次临场写 Prompt。各阶段典型做法：

需求分析：/analyze-req + Jira MCP + req-parser Skill → 结构化 Epic/Story，AI 主动反问未明确点
技术设计：/design-arch 强制 Plan Mode → 只读探索后出方案、出 ADR，避免"乱改 50 个文件"
代码生成：/new-api / /new-component → 调 Skill 或脚本（比 AI 现写快 10 倍），PostToolUse Hook 自动 lint/tsc
代码审查：三层防御（本地 Hook、PR claude-code-action、夜间全量扫描）+ security-reviewer Subagent
测试：主 Agent 写业务时，test-writer Subagent 并行生成测试，不是顺序
调试：/debug 强制结构化、Sentry MCP 直接拉错误、git bisect + AI 分析
文档：PostMerge Hook 自动同步 API docs，从代码提取不编造
部署：AI 做清单 + PreToolUse Hook 拦截破坏性命令，人工执行发布
监控：告警自动 /triage + /postmortem 草稿，人工审核

最大提升在代码生成阶段（3-5x），但最大价值在团队基建层面 —— 新人 Day 1 就有完整 AI 加持，知识不再依赖个人记忆。

Q2: 如何在需求分析阶段高效使用 AI？

答案：

3 个关键动作：

1. 接 Jira / Linear MCP（最高 ROI）

> /analyze-req PROJ-1234
AI 直接读取 ticket 详情，不用复制粘贴

2. 使用结构化 Slash Command

/analyze-req 强制 AI 按 6 段结构输出：

需求复述
User Stories（INVEST 原则）
Epic/Story/Task 树（带 Story Points）
澄清问题（至少 3 个）
风险清单
MVP 建议（P0/P1/P2）

3. 提供历史数据给 AI 估算

在 .claude/memory/past-estimates.md 里记录团队历史 Story 和实际工时，AI 能给出基于团队真实生产力的估算，而不是通用模板。

核心原则：

AI 拆解，人决策：AI 擅长穷举和结构化，优先级排序还是人
让 AI 反问：不要等 AI 自己补全遗漏，要求它主动列出"未明确"清单
输出即 Jira 格式：AI 产出直接能粘贴到 Jira / Confluence，不用再手动整理

Q3: 技术设计阶段为什么强调 Plan Mode？

答案：

Plan Mode = 只读探索 + 出计划 + 人审批 + 再执行。

核心价值：避免"AI 乱改 50 个文件，事后发现方向错了"。

强制 Plan Mode 的场景：

大型重构（影响 > 10 个文件）
迁移/升级（框架、数据库、重要依赖）
探索未知代码库
高风险改动（数据库 migration、破坏性 API 变更）

Plan Mode 流程：

用户: 把全局 Zustand store 拆分为模块化 store

Claude [Plan Mode 开启]:
  [只读] Grep "useStore"、Read 相关文件
  [分析] 42 个使用点、3 种访问模式
  [输出] 18 步迁移计划
  等待审批

用户: [审核, 删掉第 15 步, 添加第 16b 步] → 批准

Claude [切到 Auto Mode]: 按批准的计划执行

为什么必须：大改之前，计划阶段发现方向错误代价 ≈ 0；执行完才发现方向错误代价 ≈ 整个任务时间。ROI 极其悬殊。

Q4: 代码生成阶段如何让 AI 效率最大化？

答案：

3 条金科玉律：

1. 能调 Skill 就不自己写

Skill 是团队打磨过的资产，比 AI 临场生成可靠得多。/new-api 调 api-route Skill，规范、测试、限流、错误处理一次搞定，而且全团队一致。

2. 能调脚本就不让 AI 写

对于强约束样板（标准 CRUD、表单、迁移），写一个接收 JSON Spec 的生成脚本。AI 负责"决策是否调脚本"和"准备参数"，脚本负责"产出代码"。比 AI 逐行写快 10 倍，结果确定。

3. 分步迭代 + Hook 验证

每完成一个文件立即 commit
PostToolUse Hook 自动 lint/tsc，AI 立即看到错误并修复
出现 block 立即停，不要累积错误

并行升级：

主 Agent 写业务代码时，test-writer Subagent 并行生成测试
主 Agent 继续写前端时，doc-writer Subagent 并行补 API 文档

这把 40 分钟的活压缩到 20 分钟（瓶颈是 max 而非 sum）。

2026 年典型效率数据（中等复杂度功能，5-10 个文件）：

纯手写：1-2 天
AI 辅助（有完整基建）：2-4 小时
提升 3-5 倍

Q5: 代码审查的三层体系是什么？

答案：

第 1 层：本地（秒级反馈）

PostToolUse Hook 自动 lint/tsc：AI 写完代码 3 秒内看到错误
pre-commit Hook 调 Claude headless 快速预审：MUST_FIX 级别扫描（< 30s）

第 2 层：PR（分钟级）

claude-code-action：Anthropic 官方集成，自动读 PR diff + AGENTS.md，发 inline comment
按文件类型路由 Subagent：
- src/app/api/** → security-reviewer（Opus + 只读）
- lib/db/** → db-query-reviewer
- src/components/** → React 性能
人工 reviewer 聚焦业务逻辑和架构（AI 审完的语法/安全问题不用再看）

第 3 层：持续（定期）

每晚全量跑 security-reviewer：扫描主分支，发现"增量审查漏掉的全局性问题"
每周 dep-auditor：依赖漏洞扫描

为什么分层：

第 1 层：让 AI 自我修复，不浪费人的时间
第 2 层：自动化 + 人工分工，AI 管"能被规则捕捉的"，人管"需要理解业务的"
第 3 层：对抗累积性风险（第三方依赖变漏洞、代码微小变化引入新问题）

关键：AI 审查不阻塞合并，作为辅助。AI 的误报率 ~10%，强制阻塞会拖慢开发。

Q6: 如何用 AI 高效生成测试？

答案：

4 个关键动作：

1. 需求驱动，不是代码驱动

传统：写完代码 → AI 看代码补测试 → 只能验证"代码做了什么"
进阶：从 PRD / User Story → AI 直接生成测试 → 验证"规格要求什么"

这能暴露"代码做了，但不是需求要的"问题。

2. 用 test-writer Subagent 并行

主 Agent 写业务代码时，直接委派 Subagent 写测试。并行后：

主 Agent 上下文保持清爽（不被测试代码污染）
总时间 ≈ max(业务耗时, 测试耗时)，而非 sum
Subagent 自己跑测试验证通过，失败自己修

3. 边界测试必须强制

明确要求 AI 生成：

空值（null、undefined、[]、""）
极值（超长字符串、极大数字）
恰好等于阈值（这是最常漏的）
并发/竞态

4. 变异测试找盲区

/mutation-test 让 AI 生成有意义的变异：

边界改动：>= → >
逻辑翻转：&& → ||
返回值反转

如果测试仍然通过，意味着缺少覆盖该场景的测试。

输出期望：覆盖率 80%+，关键路径 95%+，变异存活率 < 15%。

Q7: AI 调试的结构化流程是什么？

答案：

不结构化的 /debug 是效率杀手。没有上下文，AI 只会猜。

结构化 /debug Slash Command 要求用户提供 7 项：

必填：

现象（用户看到的）
期望 vs 实际
复现步骤
环境（浏览器、OS、开发/预发/生产）
错误日志/堆栈（完整，不省略）

强烈建议： 6. 已试过的排查（避免 AI 重做） 7. 相关代码（@mention）

AI 的响应准则：

信息不全主动反问，不急着给答案
给根因假设，不给断言：按概率排序 3 个最可能原因
每个假设附验证方法：跑什么命令、读哪个文件、加什么日志
推荐先验证哪个：说明理由
不要列 10 个低概率猜测：聚焦高概率

进阶：

/debug SENTRY-XYZ-123 — Sentry MCP 直接拉错误上下文
/bisect [bad] [good] — git bisect + AI 分析定位引入 Bug 的 commit
bug-hunter Skill — 加载团队经验（竞态、Hydration、闭包陷阱等典型疑难 Bug 模式）

效果：定位时间通常从 2 小时 → 30 分钟。关键是结构化，不是 AI 能力本身。

Q8: 如何让 AI 生成的文档可靠？

答案：

3 条铁律：

1. 只从代码提取，不编造

好的 Prompt: "扫描 src/app/api/**/route.ts，从代码中的 HTTP 方法、Zod Schema、响应类型提取文档"
坏的 Prompt: "给我写份 API 文档"（AI 会补全它想象的接口）

2. 引用代码位置

每个文档条目标注 src/app/api/xxx/route.ts:42。未来代码变动时可以快速校验文档是否失效。

3. 保留人工章节

自动生成的文档增量更新，不是整个覆盖：

新增接口 → 补充
删除接口 → 标记 [Deprecated]
人工写的"使用场景"、"注意事项" → 保留不动

PostMerge Hook 自动同步：合并到 main 时触发 /gen-api-docs，commit 回仓库。文档永远和代码同步。

Changelog 特别注意：从 commit 生成时，要转换为用户可感知的语言：

❌ "修复 UserService.getById 的 N+1 查询"
✅ "用户列表页加载速度提升 5 倍"

用户不关心你的代码，关心你给他带来的变化。

Q9: 部署阶段 AI 应该做什么、不应该做什么？

答案：

AI 应该做（辅助）：

发布前检查清单（/ship Slash Command）
部署问题排查（deploy-troubleshoot Skill）
生成 CI/CD 配置
审查部署配置变更
回滚 runbook 生成
Changelog 自动更新
发布通知模板

AI 不应该做（红线）：

❌ 自主执行 pnpm release / kubectl apply / terraform apply
❌ 自主合并 PR 到 main
❌ 自主操作生产数据库（DROP / TRUNCATE / 大范围 UPDATE）
❌ 自主修改 CI/CD 凭据
❌ 自主 force push

实现机制：PreToolUse Hook 硬拦截

# 生产破坏性命令黑名单
"kubectl delete.*prod"
"aws s3 rm.*--recursive"
"dropdb.*prod"
"git push.*main.*--force"
# ... 命中就 exit 2 阻断

原则：

可回滚的操作可以让 AI 做（本地开发、staging）
不可回滚的操作必须人工做（生产部署、DB migration、发包）
Hook 拦截是技术兜底，不依赖 AI 自觉

Q10: AI 在事件响应中的角色是什么？

答案：

3 个关键作用：

1. 秒级自动分级（/triage）

告警一到自动跑：

Sentry MCP 拉完整错误上下文
对比最近 24h 部署记录
按 P0-P3 标准自动分级
决定是否需要紧急通知

比人工判断快 10 倍，尤其在半夜收到告警时。

2. 辅助根因分析

收集：相关服务监控曲线、最近 commit、错误日志、相关 Grafana 数据（通过 MCP）
输出：
- 3 个根因假设（按概率排序）
- 每个假设的验证方法（查什么、跑什么）
- 推荐先验证哪个 + 理由
不做断言："可能是 X"而非"一定是 X"

3. Postmortem 自动草稿（/postmortem）

事件结束后 24h 内 AI 生成初稿：

Summary、Impact、Timeline
5 Whys 根因分析
What went well / wrong / lucky
Action items（带负责人和截止）

人工审核、补充业务影响、分配 owner。

AI 不能替代的：

❌ 是否回滚（业务判断）
❌ 是否通知客户（公关判断）
❌ 责任归属（管理判断）

这些是人的责任。AI 做"信息收集和分析"，人做"决策"。

Q11: 如何度量 AI 在研发流程中的 ROI？

答案：

三维度指标体系：

1. 效率（最易量化）

效率 ROI = 节省的等价人力成本 / AI 工具总成本

Sprint Velocity 提升比例（目标 30%+）
PR 平均合并周期缩短（目标 30%+）
Feature 平均交付时间（目标 30%+）
首次代码提交时间（目标 40%+）

2. 质量（防止"为快牺牲质量"）

Bug 密度（bugs / KLOC）不应增加
生产 P0/P1 事件数不应增加
测试覆盖率应提升（AI 帮忙写测试）
PR 首次审查通过率应提升

3. 满意度（决定可持续性）

开发者 NPS（1-10）> 7
AI 工具日活率 > 80%
Skill 平均触发准确率 > 85%

典型 50 人团队年度 ROI：

基建成本：60 万（2 人 3 月）
模型费用：45 万/年
效率提升：540 万/年（30% × 50 × 3 万 × 12）
新人 onboarding 节省：30 万
生产事件减少：150 万
ROI ≈ 6.8x

关键工具：Gateway（LiteLLM）Postgres 日志 → Metabase 自建看板。Day 1 就要接度量，否则半年后拿不出数据。

注意：

代码行数不是价值指标
短期 Velocity 提升可能是技术债积累
建议至少跟踪 3 个月才得出结论

Q12: 过度依赖 AI 开发有哪些风险？如何缓解？

答案：

7 大风险：

风险	表现	缓解
能力退化	离开 AI 无法独立编码	定期无 AI 编码、面试准备关闭 AI
知识断层	不理解 AI 生成的原理	Code Review 聚焦"为什么"、要求 AI 解释
安全盲区	AI 代码包含漏洞	`security-reviewer` Subagent、SAST 扫描、安全培训
同质化	代码风格高度相似缺创新	鼓励多方案探索、技术分享
幻觉问题	AI 编造不存在的 API	始终验证运行、检查 import
成本失控	API 费用爆炸	Gateway 限额、按需选模型
隐私风险	敏感代码发到第三方	数据分级、本地模型部署

最重要的 3 条原则：

AI 是工具不是替代：理解原理比使用工具更重要
信任但验证：AI 生成的每一行代码都要经过审查
保持学习：AI 擅长执行，人的价值在判断和创新

AI 是"自行车"不是"轮椅"——让你更快到达目的地，但你必须自己有骑车的能力。2026 年最值钱的工程师不是写代码最快的，而是判断力最强的——知道该做什么、为什么做、怎么做最优。

Q13: 怎么设计 AI 参与的团队协作工作流？

答案：

核心原则：AI 做执行，人做决策。每个关键节点设人工确认。

推荐 PR 工作流：

关键控制点（黄色节点 = 人工确认，红色 = 必须人工执行）：

需求理解正确吗？
技术方案合理吗？
业务逻辑正确吗？
生产验收通过吗？
生产部署执行

角色分工：

阶段	AI 做什么	人做什么
需求	结构化拆解、估算、识别风险	确认理解、补业务背景
设计	出方案、画架构图、对比选型	评审方案、做最终决策
编码	生成代码、写测试、自动修复	审查业务逻辑、把控质量
审查	语法/安全/类型/性能初审	业务逻辑、架构合理性
部署	检查清单、生成 runbook	执行部署、监控
响应	告警分级、根因辅助	决定回滚、通知客户

禁区（误区）：

❌ AI 写完直接 commit 不看 → 线上 Bug 频发
❌ 每行都手写 AI 只用来查文档 → 浪费效率提升
✅ AI 做 80% 执行工作，人做 100% 审查和决策

Q14: 如何从 0 开始建设全流程 AI 研发基建？

答案：

6 个月渐进式路线：

月 1-2：MVP 阶段

Week 1：搭建 LiteLLM Gateway（Docker 一天搞定）
Week 2：写 AGENTS.md、.cursor/rules/ 全局规则
Week 3：3 个核心 Skills（api-route / component-builder / form-builder）
Week 4：5 人试点，收集反馈
月 2：迭代 Skills、扩大到 20 人

月 3-4：工具扩展

MCP Servers：Jira / GitHub / Sentry
Slash Commands 标准库（workflow / codegen / quality / debug / docs / ops）
Subagents：security-reviewer / test-writer / doc-writer
扩大到 50 人试点

月 5：自动化

Hooks 配置（PostToolUse 自动 lint、PreToolUse 拦截、SessionStart 注入）
CI 集成 claude-code-action
Metabase 看板上线
发布使用规范

月 6+：全员推广

全团队推广
月度效能月报机制
新人 Day 1 培训固化

成功关键：

Day 1 有 Gateway：成本、安全、审计全解决
Day 1 接度量：半年后有数据说话
先试点再推广：5 人跑通 → 20 → 50 → 全员
全部纳入 Git：Skills/Subagents/Slash Commands 不放个人电脑
不强制统一 IDE：工具自由，规范统一

详细落地见 AI 研发基建。

Q15: 分享一个 AI 全流程提效的真实案例

答案：

案例：3 天交付「AI 智能摘要」功能（对比传统 6-7 天）

Day 1（需求+设计+数据层）— 6h

/analyze-req PROJ-2301 → Jira MCP 直接读需求，AI 拆出 13 SP 和 4 个澄清问题（1h）
/design-arch Plan Mode → 扫描现有 LLM 调用，出 3 方案对比，选方案 B + 15 步实现计划（1h）
/new-migration + /new-api → 数据模型和核心 API 生成，PostToolUse Hook 自动 lint/tsc，test-writer Subagent 并行测试（4h）

Day 2（业务+前端）— 7h

LLM 集成 + 业务逻辑（3h）
中间遇到 Bug：/debug SENTRY-ERR-7823 AI 通过 Sentry MCP 拉完整错误，定位到"上下文超长被截断"（30 min，传统要 2h）
/new-component + /new-page → 组件和页面生成 + 并行测试（4h）

Day 3（测试+审查+发布）— 5h

/gen-tests --diff → Subagent 并行生成 5 个测试文件，覆盖率 87%（2h）
/review-pr security + /review-pr perf → 发现并修复 3 个问题（1h）
PR 推送 → claude-code-action 自动审查 → 人工 reviewer 10 分钟批准（1h）
/ship production → 人工执行发布 + 15 分钟监控（1h）

效率对比：

阶段	传统	AI 全流程
需求+设计	6h	2h
实现	2 天	0.5 天
测试	1 天	2h
审查+发布	6h	1.5h
总计	6-7 天	3 天

关键：效率提升不是 AI 取代了人，而是：

样板代码用 Skill 生成
测试并行由 Subagent 搞
质量检查由 Hook + Subagent 自动化
人聚焦在架构决策、业务逻辑、质量终审——这是真正的价值所在

Q16: 如何在团队中推广全流程 AI？

答案：

4 阶段渐进式：

阶段 1：个人探索（1-2 周）

2-3 名技术骨干选 1-2 个阶段深度试用（通常选代码生成 + 审查）
对比效率数据
选定团队主工具（Cursor + Claude Code）

阶段 2：制度建设（2-3 周）

建立团队 Rules / Skills 仓库（.claude/ 纳入 Git）
制定 AI 使用规范（数据分级、红线）
编写 Slash Commands 标准库
配置 CI 集成

阶段 3：培训推广（1-2 周）

AI 编程工作坊（Live Demo + 实操）
Prompt 模板库（团队 Wiki）
配对编程：老人带新人

阶段 4：持续优化（持续）

每周 15 分钟闪电分享
月度效能月报
根据数据优化 Skills / 工作流

成功指标：

团队采用率 > 80%
开发者满意度 > 7/10
Sprint Velocity 提升 > 30%
Skill 触发准确率 > 85%

反模式：

❌ 一次性铺开到全团队（风险大、反弹大）
❌ 强制统一 IDE（老用户反感）
❌ 不做度量就说"效果很好"（说不清 ROI）
❌ Rules/Skills 只放个人电脑（离职带走）

详细策略见 AI 研发基建 - 推广策略。

Q17: 怎么保证 AI 生成的代码质量？

答案：

4 层防御：

Layer 1：预防（编码前）

Rules 先行：CLAUDE.md / AGENTS.md 约束 AI 生成范式
Skills 沉淀：常见代码走 Skill，有团队约束兜底
TypeScript strict：类型系统自动捕获错误

Layer 2：生成（编码中）

分步迭代：每步完成立即 pnpm build && pnpm test
PostToolUse Hook：AI 改完自动 lint/tsc，立即反馈
增量 commit：每个功能一个 commit，出错可回退

Layer 3：检查（编码后）

静态分析：ESLint + Prettier + TypeScript CI 门禁
Subagent 审查：security-reviewer / db-query-reviewer 并行审
人工审查：业务逻辑、架构合理性
测试覆盖：AI 生成测试验证 AI 生成代码（test-writer Subagent）

Layer 4：运行（上线后）

监控告警：错误率、性能实时监控
灰度发布：新功能小流量验证
持续扫描：夜间 security-reviewer 全量跑

质量保证链：

Rules → AI 生成 → TypeCheck → Lint → 测试 → AI 审查 → 人工审查 → CI → 灰度

关键：任何一层都不能替代所有其他层。分层防御比单点加强更可靠。

Q18: AI 全流程有哪些典型反模式？

答案：

10 大反模式：

全流程用同一个 Prompt → 各阶段效率平平
- 正解：每阶段有专用 Slash Command
不用 Plan Mode 就开干大型改动 → 方向错了返工惨重
- 正解：大改强制 /plan
测试放到最后补 → 测试草率、覆盖低
- 正解：Subagent 并行生成（和业务代码同步）
不委派 Subagent 主 Agent 什么都干 → 上下文膨胀、质量下降
- 正解：大任务、审查类任务必用 Subagent
让 AI 自主部署 → 灾难性风险
- 正解：Hook 硬拦截 + 人工执行
Postmortem 写成责任追究 → 团队文化受损
- 正解：Blameless，聚焦系统改进
Skills 写得像论文 → AI 触发不准确
- 正解：< 500 字，description 用用户原话
Hook 里跑全量 test → Agent 卡死
- 正解：Hook 只做快速操作
@codebase 乱塞上下文 → 信噪比低、质量差
- 正解：精确 @mention + Grep 定位
不度量 AI 效能 → 说不清 ROI
- 正解：Day 1 接 Gateway + Metabase

最根本的反模式：把 AI 当个人工具用而不是团队基建。单人用的再好也是单点收益，团队基建才能全员受益、持续沉淀。

Q19: 怎么写 Prompt 效果最好？

答案：

2026 年的答案有一个重要转折：对高频操作，不要"写 Prompt"，要"写 Skill / Slash Command"。临场写 Prompt 只适合低频、一次性的任务。

一、对低频任务：结构化 Prompt 的 CRAFT 框架

要素	含义	示例
Context	项目背景、技术栈、当前状态	"Next.js 15 App Router + TypeScript + Prisma"
Role	AI 扮演的角色	"资深前端架构师"
Action	具体要做什么	"审查以下代码的性能问题"
Format	期望的输出格式	"按严重度排序，每条包含描述/影响/修复代码"
Tone/constraints	约束条件	"不改 API、保持向后兼容"

二、4 条实战铁律

1. 提供上下文比炫技 Prompt 重要 10 倍

❌ 差：帮我写个购物车功能
✅ 好：在我们的 Next.js 15 项目里（用 Zustand 管购物车、SWR 拉商品）
     实现「加入购物车」的乐观更新，要求：错误自动回滚、
     处理并发添加、包含单元测试。参考 @lib/store/favorite.ts 的模式

2. 用 Few-shot 示例引导风格

给 AI 2-3 个现有代码作为范例，AI 会"模仿"生成。比描述规则有效 10 倍。

3. 分步迭代，不要一次性要完美

第 1 轮：给基础方案和整体设计
第 2 轮：针对方案，如果用户快速连点 10 次怎么保证数量正确？
第 3 轮：补充边界：网络断开、库存不足、登录过期
第 4 轮：为上述代码生成完整测试

4. 明确约束（用 ❌/✅ 硬措辞）

✅ 必须：TypeScript strict、React Hook Form + Zod、包含加载态
❌ 禁止：any、class 组件、硬编码魔数、直接 fetch

AI 对显式禁忌的响应远好于隐式期望。

三、对高频任务：把 Prompt 升级为资产

如果一个 Prompt 你一周用 3 次以上——立即封装：

复用粒度	手段	何时用
一次性	直接写 Prompt	探索、调研、讨论
我自己会重复	Prompt 片段库（Notion/TextExpander）	个人高频
团队会重复	Skill（自然语言触发）或 Slash Command（显式触发）	团队沉淀
每次都要做	Hook 自动化	完全无人化

2026 年的核心转变：

2024 年问"怎么写好 Prompt？" → 关心那一句话
2026 年问"怎么把这个需求做好？" → 关心整个上下文 + 能力包 + 流程

一个封装好的 /new-api Slash Command，比任何临场写的 Prompt 都强——因为它内置了团队的鉴权规范、错误码、限流约定、测试模板。Prompt 的工程化升级路径就是 Skill。

四、核心心法

Prompt 工程的本质不是"写魔法咒语"，而是"清晰表达你的需求"。如果你自己都说不清要什么，AI 也无法给出好结果。

写 Prompt 前先想清楚：要什么、为什么、约束是什么
一次 Prompt 完成一件事：不要"帮我实现购物车、写测试、部署上线"三合一
验证驱动迭代：看到 AI 输出不对，立即追问"为什么这样做？" 或"考虑了 X 场景吗？"
积累到资产：每用 3 次以上的 Prompt 立即固化为 Skill / Slash Command

更多技巧见 Prompt Engineering。

Q20: 应该做交叉验证吗？怎么做？

答案：

该做，但不是所有任务都要。交叉验证是对抗"AI 幻觉"和"思维定势"的最有效手段，但它有成本。按关键程度分级。

一、为什么需要交叉验证

单一 AI 模型存在系统性偏差——同一个问题问同一个模型 10 遍，会一致地犯同一个错误。就像只问一个人意见，即使问 10 遍，偏见也一样。

二、按任务关键度分级

三、三种实战策略

策略 1：多模型交叉验证

问同一个问题给不同模型，对比差异：

Step 1: Claude Sonnet 4.6 给方案 A
Step 2: GPT-5 给方案 B（不告诉它 Claude 的答案）
Step 3: 对比：
  - 一致的部分 → 可信度高
  - 不一致的部分 → 重点验证
Step 4: 追问每个模型："另一种方案认为应该 XXX，你怎么看？"
Step 5: 根据论据质量判断

成本：2-3 倍 token。适用：关键架构决策、安全审查。

策略 2：角色对抗验证（单模型也能做）

让同一个 AI 扮演"提出者"和"审查者"两个角色：

第 1 步：提方案
"设计前端鉴权方案，要支持 JWT + 刷新 Token + 多标签页同步"

第 2 步：对抗审查（新会话）
"以下是一个前端鉴权方案：[粘贴]
请以安全审查专家身份找出所有漏洞，至少列 5 个攻击场景"

第 3 步：修复完善
"针对审查发现的问题改方案，逐条说明如何修复"

这相当于自己给自己做 peer review。团队资产化：把这个流程固化为 /self-review Slash Command。

策略 3：代码级验证——"跑它"

对于代码，最可靠的验证就是运行：

// 1. AI 生成代码后，让它生成测试
// "为上面代码生成完整测试，包含边界情况"

// 2. 运行测试
// pnpm test

// 3. 失败的测试让另一个模型分析原因
// "这些测试失败了：[日志]，分析根本原因"

// 4. TypeScript 编译器静态验证
// pnpm tsc --noEmit

配合 PostToolUse Hook 自动 lint/tsc + test-writer Subagent 并行测试 + security-reviewer Subagent 审查，这就是基建级别的自动化交叉验证——不需要人工介入。

四、企业基建的自动化交叉验证

2026 年最佳实践是把交叉验证做成流水线：

每一层都是一次"交叉"——不同模型、不同视角、不同粒度。这比手动问两个模型可靠得多。

五、交叉验证的 ROI

不是所有代码都值得验证。遵循 80/20 原则：

代码类型	验证强度	示例
⭐ 样式/格式	跑一下就行	CSS 调整、文案修改
⭐⭐ 常见 CRUD	编译 + 跑测试	列表页、表单
⭐⭐⭐ 业务逻辑	Subagent 审查 + 完整测试	订单流程、权限
⭐⭐⭐⭐ 架构/安全	多模型 + 人工审查	鉴权、加密、支付
⭐⭐⭐⭐⭐ 不可逆操作	多人工验证 + 灰度	数据迁移、DB migration

花 80% 的验证精力在 20% 的关键代码上。

六、识别"AI 自信地说错话"的信号

高危信号（一出现立即做交叉验证）：

过于自信："这是唯一正确的做法" → 通常存在多方案
模糊措辞："大概"、"应该"、"一般来说" → AI 也不确定
不存在的引用："根据官方文档" → 去文档验证，经常是编造
过于完美的代码：没有错误处理、没有边界 → 现实不会这么简单
回避具体细节：问"为什么用 A 不用 B"得到模糊回答 → 追问技术对比
新模型刚出的特性：模型知识可能过期，务必查官方文档

Q21: 怎么得出最佳技术方案？

答案：

不是问 AI 一句"怎么做"就拿答案，而是通过结构化的发散→对比→验证→收敛流程逐步收敛。

一、四步法总览

二、第 1 步：发散——强制要多个方案

关键动作：明确要求 AI 给 3-5 种不同方案。如果只问"怎么做"，AI 会给它认为最好的那一个，你看不到替代选项。

需求：前端实时搜索，10 万条数据、输入延迟 < 100ms、支持拼音

请给 3-5 种技术方案，每种说明：
核心思路
技术选型
优势
劣势
适用场景

AI 会给出类似：

A: Array.filter 主线程
B: Web Worker + Fuse.js
C: IndexedDB + 预建索引
D: Elasticsearch（需后端）
E: WebAssembly 搜索引擎

三、第 2 步：对比——决策矩阵

让 AI 生成多维度对比表：

请把上面 5 种方案做成决策矩阵：

| 维度 | A | B | C | D | E |
|------|---|---|---|---|---|
| 10 万数据响应时间 | | | | | |
| 开发成本（人天） | | | | | |
| 维护复杂度 | | | | | |
| Bundle 体积影响 | | | | | |
| 浏览器兼容性 | | | | | |
| 是否需要后端 | | | | | |
| 社区成熟度 | | | | | |

基于我们的约束（中后台、10 万级数据、需 IE11 支持、纯前端），
给出推荐排序和理由

四、第 3 步：验证——PoC 跑 benchmark

不要只看理论分析。让 AI 生成最小 PoC，实际跑 benchmark：

用方案 B（Web Worker + Fuse.js）生成最小 PoC：
生成 10 万条模拟数据
实现搜索逻辑
用 performance.mark 精确测量延迟
对比主线程 vs Worker 的性能差异
可以直接在浏览器里运行

poc/search-benchmark.ts
const testData = Array.from({ length: 100_000 }, (_, i) => ({
  id: i, name: `用户${i}`, pinyin: `yonghu${i}`,
}));

// 关键：跑多次取中位数，不要相信 AI 的"预估性能"
function benchmark(fn: () => void, times = 100) {
  const results: number[] = [];
  for (let i = 0; i < times; i++) {
    const start = performance.now();
    fn();
    results.push(performance.now() - start);
  }
  results.sort();
  return { p50: results[50], p95: results[95], p99: results[99] };
}

const scenarios = {
  'Array.filter': () => testData.filter(d => d.name.includes('yong')),
  'Fuse.js': () => fuse.search('yong'),
  'Worker + Fuse.js': () => workerSearch('yong'),
};

2026 年的优势：Subagent 可以独立跑 PoC——委派一个 Subagent 说"对这 3 个方案各生成 PoC 并跑 benchmark，返回 P50/P95/P99 数据"，主 Agent 不被污染。

五、第 4 步：收敛——基于真实数据决策

综合理论 + PoC 结果：

PoC 实测：
- A（Array.filter）：P95 = 200ms ❌ 不达标
- B（Worker + Fuse.js）：P95 = 50ms ✅ 达标，bundle +45KB
- C（IndexedDB）：P95 = 30ms ✅ 达标，但初次加载慢

结合约束（纯前端、bundle 敏感），选 B

请基于 B 给出完整实现：
1. Worker 通信封装
2. 搜索组件
3. 降级方案（Worker 不可用时 fallback 到主线程）

六、记录为 ADR（可复用资产）

方案确定后，用 AI 生成 ADR（Architecture Decision Record），沉淀为团队资产：

docs/adr/003-search-implementation.md
# ADR-003: 前端实时搜索方案

## 状态：已采纳（2026-04-20）

## 上下文
需要在中后台系统实现 10 万级数据的前端实时搜索，输入延迟 < 100ms。

## 决策
采用 Web Worker + Fuse.js 方案。

## 考虑过的方案
1. Array.filter → PoC 实测 P95=200ms，不达标
2. Web Worker + Fuse.js → ✅ 选定，P95=50ms
3. IndexedDB + 预建索引 → 初次加载慢，体验差
4. Elasticsearch → 需要后端，不符合纯前端约束
5. WebAssembly → 社区不成熟，维护成本高

## 后果
- ✅ 搜索延迟 P95 < 100ms
- ✅ 不阻塞主线程
- ⚠️ 包体积 +45KB（可接受）
- ⚠️ 团队需要维护 Worker 通信代码

## 实施计划
见 Epic PROJ-1234

ADR 让未来的人（包括 AI）能理解为什么选 B 不是 A——避免半年后有人问"当初为啥不用方案 C 啊"。

七、工作流固化：`/design-arch` Slash Command

把这四步法固化为 Slash Command：

.claude/commands/workflow/design-arch.md
---
name: design-arch
---

对需求做技术方案设计（进入 Plan Mode）。

## 强制 4 步流程

1. **发散**：给 3-5 种方案
2. **对比**：生成决策矩阵
3. **验证**：最优 2 个方案生成 PoC + benchmark
4. **收敛**：基于实测数据选定 + 生成 ADR

**每步完成后等我确认，不要跳步**

这样团队每一次架构决策都走这个流程，不会因为人懒而省略验证步骤。

八、核心心法

最佳方案不是 AI 告诉你的，是你通过结构化流程筛选出来的。

AI 的价值：快速生成候选方案 + 生成 PoC 代码 + 整理对比矩阵 → 大幅缩短探索时间
人的价值：判断哪个方案最适合你的场景、团队、约束 → 最终决策权永远在人

反模式：

❌ 直接问"最好的 X 方案是什么" → 拿到"通用答案"，不适合你
❌ 只看理论分析不跑 PoC → benchmark 数字 AI 常常编造
❌ 选完方案不写 ADR → 半年后团队忘了为什么这么选
❌ 不用 Plan Mode → AI 给完方案直接开始改代码，方向错了返工惨重

问题​

答案​

一、全流程资产地图​

1.1 各阶段资产清单（实战落地版）​

1.2 产出物流水线：阶段之间如何衔接​

二、阶段 1：需求分析​

2.1 配置飞书 MCP​

2.2 Slash Command /analyze-req​

2.3 Skill req-parser​

三、阶段 2：技术设计​

3.1 Slash Command /design-arch​

3.2 架构图自动生成​

四、阶段 3：代码生成​

4.1 Slash Command /new-api 全流程​

4.2 Skill api-route 的完整模板​

4.3 PostToolUse Hook 自动验证（标配）​

4.4 并行开发：test-writer Subagent​

4.5 从 Figma 设计稿生成 UI 组件​

4.5.1 路径 A：Figma MCP Server + Code Connect（最推荐，2026 年主流方案）​

4.5.2 路径 B：截图 + 多模态模型（快速验证场景）​

4.5.3 路径 C：v0 / Lovable / Bolt（快速原型）​

4.5.4 Design Token 提取（一次投入，永久受益）​

4.5.5 Hook：UI 改动后自动截图验证​

4.5.6 完整端到端示例​

4.5.7 常见坑​

五、阶段 4：代码审查​

5.1 claude-code-action PR 自动审查（推荐）​

5.2 Slash Command /review-pr​

5.3 security-reviewer Subagent​

5.4 本地 pre-commit 预审​

六、阶段 5：测试​

6.1 Slash Command /gen-tests​

6.2 Skill test-patterns​

6.3 Slash Command /mutation-test​

6.4 视觉回归 + AI 分析​

七、阶段 6：调试​

7.1 Slash Command /debug​

7.2 Skill bug-hunter + Subagent​

7.3 Slash Command /bisect​

7.4 Sentry MCP 集成​

八、阶段 7：文档​

8.1 Slash Command /gen-api-docs​

8.2 Slash Command /gen-changelog​

8.3 PostMerge Hook 自动同步​

九、阶段 8：部署​

9.1 Slash Command /ship​

9.2 PreToolUse Hook 拦截生产破坏性操作​

9.3 部署问题排查​

十、阶段 9：监控与事件响应​

10.1 Slash Command /triage​

10.2 Slash Command /postmortem​

10.3 AI 辅助事件响应的关键​

十一、端到端示例：3 天完成完整功能​

Day 1（需求 + 设计 + 基础）— 6 小时​

Day 2（业务逻辑 + 前端）— 7 小时​

Day 3（测试 + 审查 + 发布）— 5 小时​

十二、全流程效能度量​

12.1 核心指标看板​

12.2 月度效能报告模板​

十三、常见反模式​

十四、面试速答与追问清单​

3 分钟速答版​

10 分钟展开版​

高频追问​

常见面试问题​

Q1: 描述 AI 参与全流程研发的最佳实践​

Q2: 如何在需求分析阶段高效使用 AI？​

Q3: 技术设计阶段为什么强调 Plan Mode？​

Q4: 代码生成阶段如何让 AI 效率最大化？​

Q5: 代码审查的三层体系是什么？​

Q6: 如何用 AI 高效生成测试？​

Q7: AI 调试的结构化流程是什么？​

Q8: 如何让 AI 生成的文档可靠？​

Q9: 部署阶段 AI 应该做什么、不应该做什么？​

Q10: AI 在事件响应中的角色是什么？​

Q11: 如何度量 AI 在研发流程中的 ROI？​

Q12: 过度依赖 AI 开发有哪些风险？如何缓解？​

Q13: 怎么设计 AI 参与的团队协作工作流？​

Q14: 如何从 0 开始建设全流程 AI 研发基建？​

Q15: 分享一个 AI 全流程提效的真实案例​

问题

答案

一、全流程资产地图

1.1 各阶段资产清单（实战落地版）

1.2 产出物流水线：阶段之间如何衔接

二、阶段 1：需求分析

2.1 配置飞书 MCP

2.2 Slash Command `/analyze-req`

2.3 Skill `req-parser`

三、阶段 2：技术设计

3.1 Slash Command `/design-arch`

3.2 架构图自动生成

四、阶段 3：代码生成

4.1 Slash Command `/new-api` 全流程

4.2 Skill `api-route` 的完整模板

4.3 PostToolUse Hook 自动验证（标配）

4.4 并行开发：test-writer Subagent

4.5 从 Figma 设计稿生成 UI 组件

4.5.1 路径 A：Figma MCP Server + Code Connect（最推荐，2026 年主流方案）

4.5.2 路径 B：截图 + 多模态模型（快速验证场景）

4.5.3 路径 C：v0 / Lovable / Bolt（快速原型）

4.5.4 Design Token 提取（一次投入，永久受益）

4.5.5 Hook：UI 改动后自动截图验证

4.5.6 完整端到端示例

4.5.7 常见坑

五、阶段 4：代码审查

5.1 `claude-code-action` PR 自动审查（推荐）

5.2 Slash Command `/review-pr`

5.3 `security-reviewer` Subagent

5.4 本地 pre-commit 预审

六、阶段 5：测试

6.1 Slash Command `/gen-tests`

6.2 Skill `test-patterns`

6.3 Slash Command `/mutation-test`

6.4 视觉回归 + AI 分析

七、阶段 6：调试

7.1 Slash Command `/debug`

7.2 Skill `bug-hunter` + Subagent

7.3 Slash Command `/bisect`

7.4 Sentry MCP 集成

八、阶段 7：文档

8.1 Slash Command `/gen-api-docs`

8.2 Slash Command `/gen-changelog`

8.3 PostMerge Hook 自动同步

九、阶段 8：部署

9.1 Slash Command `/ship`

9.2 PreToolUse Hook 拦截生产破坏性操作

9.3 部署问题排查

十、阶段 9：监控与事件响应

10.1 Slash Command `/triage`

10.2 Slash Command `/postmortem`

10.3 AI 辅助事件响应的关键

十一、端到端示例：3 天完成完整功能

Day 1（需求 + 设计 + 基础）— 6 小时

Day 2（业务逻辑 + 前端）— 7 小时

Day 3（测试 + 审查 + 发布）— 5 小时

十二、全流程效能度量

12.1 核心指标看板

12.2 月度效能报告模板

十三、常见反模式

十四、面试速答与追问清单

3 分钟速答版

10 分钟展开版

高频追问

常见面试问题

Q1: 描述 AI 参与全流程研发的最佳实践

Q2: 如何在需求分析阶段高效使用 AI？

Q3: 技术设计阶段为什么强调 Plan Mode？

Q4: 代码生成阶段如何让 AI 效率最大化？

Q5: 代码审查的三层体系是什么？

Q6: 如何用 AI 高效生成测试？

Q7: AI 调试的结构化流程是什么？

Q8: 如何让 AI 生成的文档可靠？

Q9: 部署阶段 AI 应该做什么、不应该做什么？

Q10: AI 在事件响应中的角色是什么？

Q11: 如何度量 AI 在研发流程中的 ROI？

Q12: 过度依赖 AI 开发有哪些风险？如何缓解？

Q13: 怎么设计 AI 参与的团队协作工作流？

Q14: 如何从 0 开始建设全流程 AI 研发基建？

Q15: 分享一个 AI 全流程提效的真实案例