12 常见问题与反模式¶

这一章把 AI 全流程开发中最常见的坑集中列出来。建议在项目开始时扫一遍，在出问题时当排查手册用。

1. 需求阶段¶

Q1：AI 生成的需求看起来很好，但总感觉哪里不对？¶

症状：文档结构完整、术语专业，但细看全是“应该”“适当”“友好”这类无法验收的词。

原因：AI 在信息不足时会用“合理猜测”填补空白。

处理：

把每条需求改写成可测试的句子（输入、动作、输出、错误码）。
列出所有“假设”，逐条找人确认。
让另一个 Agent 做需求批判。
没有验收标准的需求，不进入开发。

Q2：用户故事拆得太细/太粗怎么办？¶

判断标准：

一个故事应该能独立开发、测试、演示；
1-3 天能完成；
超过 8 个故事点继续拆；
如果拆完每个故事都无法独立演示，说明拆错了（按技术层拆了）。

Q3：需求总是变，CSV 状态乱了怎么办？¶

处理：

变更走 CR（变更请求），记录原因和影响；
需求变更后，重新评估受影响的故事；
已完成的 story 如果需要改，回到 dev 或新建 story；
CSV 只由脚本更新；
每次变更更新 last_updated。

Q4：要不要写非目标？¶

一定要。 非目标是防止范围蔓延的第一道防线。没有非目标，AI 会“顺手”加功能，人也会不断加需求。

2. UI / Figma¶

Q5：Figma MCP 连不上怎么办？¶

排查：

用 Figma 桌面应用，不是浏览器；
进入 Dev Mode（Shift + D）；
Enable desktop MCP server；
端口 3845 是否被占用；
传输方式 http / sse 换着试；
/mcp 是否 connected；
代理是否拦截 localhost（NO_PROXY）。

Q6：Figma MCP 不能改设计稿，怎么办？¶

官方 Dev Mode MCP 主要读取/生成代码，不一定支持写入。备选：

Figma Plugin API：让 AI 写插件，在 Figma 里创建/修改图层；
第三方 MCP：自行评估稳定性和安全；
HTML 原型作为设计契约；
人工在 Figma 中调整，AI 只负责读取和生成代码。

Q7：AI 做的设计很“模板化”？¶

给更多约束：

品牌气质、参考产品、反例；
token 和组件库；
先出 3 个方向，人选一个；
明确“不要做什么”。

Q8：设计稿没有异常状态怎么办？¶

在提示词里强制列出状态清单，评审时逐项检查。没有空/加载/错误/无权限状态，不允许进入前端开发。

3. 前端¶

Q9：AI 一次生成整个 Vue 应用，越改越乱？¶

分两阶段：

静态 HTML/CSS 原型，先把视觉做对；
再拆 Vue 组件、接 API。

一次只改一个页面/组件，改完跑 typecheck/test。

Q10：前端和接口对不上？¶

从 OpenAPI 生成 TypeScript 类型；
API client 统一封装；
后端改字段后重新生成类型；
CI 中跑类型检查；
契约测试。

Q11：页面只做了正常态，空数据就白屏？¶

强制五种状态：loading / empty / error / no-permission / success。用 useAsync 统一管理。DoD 里加检查项。

Q12：AI 写了很多 `any` 和 `@ts-ignore`？¶

tsconfig 开 strict；
ESLint 禁止 any（或至少警告）；
CI 中 vue-tsc --noEmit；
审查时把 any 当 P1。

Q13：前端鉴权能当安全边界吗？¶

不能。 前端隐藏按钮只是体验。所有权限必须在后端校验，返回 403。

4. 后端¶

Q14：编译型语言真的能解决幻觉吗？¶

解决“语法/类型/签名”类幻觉，不解决“业务语义”类幻觉。还需要：

契约测试；
单元/集成测试；
E2E；
人工验收。

Q15：Go / Java / Rust 到底选哪个？¶

默认 Go；
企业复杂业务/团队 Java 强 → Java；
高性能/强安全 → Rust；
单人 + AI + 快速交付 → Go。

Q16：多个请求互相干扰怎么排查？¶

检查：

是否有包级可变变量；
是否把用户/租户信息存全局；
缓存 key 是否带租户；
事务是否覆盖完整；
连接池是否耗尽；
是否有 goroutine 泄漏；
是否有共享 map 未加锁（-race）。

Q17：AI 写的 SQL 有注入风险吗？¶

用参数化查询（pgx/sqlc 默认），不要拼接 SQL。审查时搜 fmt.Sprintf 拼 SQL、+ 拼接查询。

Q18：数据库迁移把线上弄挂了？¶

不在应用启动时自动迁移生产；
迁移前备份；
expand-contract；
大表用 CONCURRENTLY/分批；
迁移演练；
回滚脚本。

Q19：AI 把测试删了让 CI 变绿？¶

零容忍。 审查 diff，发现删除/跳过测试立即还原。规则写进 CLAUDE.md 和 Agent 任务书。

5. 开发环境 / WSL¶

Q20：WSL 里 Chrome 打不开？¶

wsl --update；
检查 WSLg；
看 /tmp/chrome-debug.log；
root 用户需要 --no-sandbox（仅开发）；
中文乱码装 fonts-noto-cjk。

Q21：Chrome 9222 端口连不上？¶

Chrome 136+ 必须用非默认 --user-data-dir；
端口一致；
Chrome 是否启动成功；
WSL 镜像网络；
Windows 防火墙；
curl http://127.0.0.1:9222/json/version。

Q22：项目放 `/mnt/c` 下 npm install 很慢？¶

移到 ~/projects/，删除 node_modules 重装。不要跨文件系统做开发。

Q23：Claude Code 在 WSL 里比 Windows 原生好多少？¶

在命令、脚本、路径、Git、构建工具兼容性上明显更顺；GUI 用 Windows 端 VS Code/Chrome 即可。详见 Claude Code 跨平台表现对比。

Q24：WSL 占用内存/磁盘越来越大？¶

.wslconfig 限制内存；
autoMemoryReclaim=dropcache；
wsl --shutdown + wsl --compact；
清理 apt/journal；
定期导出备份后重建。

6. 技术设计¶

Q25：契约冻结了还能改吗？¶

能，但要走 CR：

新增可选字段：兼容；
修改语义/类型：破坏性，升版本/双写；
删除字段：先 deprecated；
所有变更记录、通知、重新生成类型。

Q26：OpenAPI 写了但没人用？¶

把它变成门禁：

后端用 oapi-codegen 生成类型；
前端用 openapi-typescript 生成类型；
CI 跑 lint 和契约测试；
代码审查检查字段一致性。

Q27：文件所有权太麻烦，能不能不写？¶

并行度低（1-2 个 Agent）时可以简化，但至少要：

共享文件只有一个 Agent 改；
迁移编号统一；
合并前跑全量测试。

并行度高时，所有权清单是刚需。

Q28：技术设计写多细？¶

标准：一个中等水平的 Agent 看完能直接写代码和测试，不需要猜。 太细会浪费时间，太粗会返工。

7. 多 Agent 编码¶

Q29：开几个 Agent 合适？¶

第一次：2 个；
熟练：3-4 个；
模块非常独立：最多 5 个；
超过 5 个，协调成本通常大于收益。

Q30：Agent 互相改同一个文件？¶

用 worktree 隔离；
文件所有权清单；
共享文件只由架构 Agent 改；
冲突时停止，人工/架构 Agent 解决；
不要让 Agent 自动选 ours/theirs。

Q31：Agent 说完成，但功能不能用？¶

按 DoD 检查：

单测过了吗？
集成/E2E 过了吗？
有证据吗？
契约一致吗？
前端状态齐全吗？

“单测通过”不等于“功能完成”。

Q32：上下文太长，AI 开始胡说？¶

一个故事一个会话；
/clear；
先读 CLAUDE.md + 契约；
用子 Agent 搜索；
把已完成内容写成摘要文件；
不要贴大段日志/HTML。

Q33：多个 Agent 的 token 成本太高？¶

机械任务用快速模型；
架构/审查用强模型；
子 Agent 做搜索/摘要；
精确引用文件，不要全仓库读；
截图不回读模型；
减少无效重试。

8. 测试 / Word 报告¶

Q34：E2E 很脆，怎么办？¶

用 data-testid，不用样式类；
轮询等待，不固定 sleep；
测试数据唯一前缀；
测试前检查登录态；
等待关键请求完成；
失败保留现场。

Q35：截图太多，token 爆炸？¶

storeBase64: false；
只截关键步骤；
用 JS 断言代替看图；
图片只给人看，不给模型看。

Q36：Word 报告图片不显示？¶

路径相对于 qa-root；
用绝对路径解析；
检查文件是否存在；
中文路径 UTF-8；
生成后统计图片数。

Q37：AI 把失败步骤标成 pass？¶

断言必须有 expected/actual；
审查 manifest，不只看 result；
执行 Agent 和审查 Agent 分开；
人工抽查关键步骤。

Q38：人工走查太慢？¶

先看 Word 封面和摘要；
只看失败/高风险步骤；
用批注而不是重新描述问题；
让 AI 按批注修，不要口头描述；
修完只重跑失败故事。

9. 部署 / 线上¶

Q39：本地能跑，线上 500？¶

环境变量；
迁移；
IAM/网络；
时区/编码；
依赖版本；
看 request_id 和日志。

Q40：AWS 登录态总过期？¶

用 SSO；
Syncthing 同步 sso/cache（短期 token）；
不要同步 credentials；
过期就重新登录；
不要让 AI 自动重试到锁定。

Q41：生产测试污染数据？¶

专用测试租户；
数据前缀；
测完清理；
只读优先；
不测不可逆操作；
审批。

Q42：发布后要不要马上删旧版本？¶

不要。保留至少一个可回滚版本，确认线上稳定后再清理。

Q43：AI 能直接操作生产吗？¶

可以执行，但必须：

人工批准；
最小权限；
操作白名单；
审计日志；
备份/回滚；
不允许自动绕过凭证过期。

10. 组织与流程¶

Q44：这套流程对一个人是不是太重？¶

可以从轻量版开始：

spec + CSV + 故事细节；
OpenAPI + schema；
单 Agent 开发 + 测试；
Chrome MCP E2E + Word 报告；
手动部署。

熟练后再加多 Agent、worktree、CI/CD。

Q45：团队不接受 AI 写代码怎么办？¶

先从一个低风险模块试点；
用证据说话（测试、报告、缺陷率）；
人保留审查和验收权；
建立代码规范和门禁；
不把 AI 当“替代人”，而当“加速器”。

Q46：怎么衡量有没有提效？¶

看：

故事周期时间；
需求返工率；
缺陷逃逸率；
人工评审时间；
token 成本/故事。

不要只看代码行数。

Q47：AI 生成的代码风格不一致？¶

CLAUDE.md 写规范；
lint/format 自动修复；
代码审查；
模板/示例代码；
统一组件库和错误模型。

Q48：需求、设计、代码、测试的版本对不上？¶

所有产物进 Git；
每个故事记录 commit/branch；
CSV 记录报告和 manifest 路径；
发布记录版本号；
契约变更走 CR。

11. 十个最危险的反模式¶

#	反模式	后果	解药
1	没有验收标准就开工	做完发现不是想要的	G1 + Given/When/Then
2	契约没冻结就并行	合并地狱	G4
3	多个 Agent 改同一文件	覆盖/冲突	worktree + 文件所有权
4	删除测试让 CI 变绿	质量崩塌	零容忍 + 审查
5	截图全读回模型	token 爆炸	文本/JS 优先
6	生产测试用真实数据	数据污染/事故	测试租户 + 前缀
7	长期密钥同步到多机	泄露	SSO + 短期 token
8	生产部署无审批	不可控	G7 + 人工批准
9	上下文不清理	AI 变糊涂	一故事一会话
10	把“AI 说完成”当完成	交付不可信	证据链 + 人工验收

12. 一张排查顺序图¶

功能不对
  │
  ├─ 编译/类型错误？ → 修代码
  ├─ 单测失败？ → 修实现或测试
  ├─ 集成失败？ → 查 DB/事务/契约
  ├─ API 返回不对？ → 查 OpenAPI/日志/request_id
  ├─ 前端显示不对？ → 查状态/类型/接口
  ├─ E2E 失败？ → 保留截图/manifest，定位层
  ├─ 线上才失败？ → 查环境/配置/迁移/网络
  └─ 用户觉得不好用？ → 回需求/设计，不要只改代码

下一章：附录 A：Chrome MCP / CDP 实战手册 —— 把浏览器自动化用到极致。