跳到主要内容

AI 辅助开发：Claude Code、Codex 与工程化实践

问题​

怎样把 AI 编程工具真正接入日常研发，而不是停留在补全和“帮我写段代码”？本文从工具选型、任务描述、项目指令、Rules、Skills、MCP、Hooks、Subagents、沙箱、Git worktree、验证闭环、AI 常见编码错误和团队度量展开，并给出 Claude Code 与 Codex 的当前实践。

面试速答

我把 AI 编程工具当成一个能读仓库、调用工具、修改代码并迭代验证的工程协作者，而不是答案生成器：

  • 先用真实任务选择工具，不按静态排行榜选“永久最强”。
  • 用 AGENTS.md 等项目指令提供稳定上下文，把偶发流程沉淀为 Skill，把强制动作放进权限、Hook 或 CI。
  • 任务按“探索 → 计划 → 实现 → 验证 → 审查”推进，每一步都有范围和可执行验收标准。
  • Claude Code 与 Codex 的发现目录并不完全相同，统一的是规则和 Skill 的内容源，工具目录只做薄适配。
  • 用沙箱、最小权限、worktree 和人工审批限制副作用，用测试、截图和 git diff 证明结果。
  • 对 AI 生成代码默认执行“契约、边界、失败路径、安全、性能、兼容性”六类复核，不因代码看起来完整就直接采纳。

答案​

一、AI 辅助开发已经从生成代码变成 Agent 工程​

现代编码 Agent 的核心不是一次生成，而是一个持续反馈循环：

这改变了开发者的工作重点：

  1. 从写每一行代码转向定义问题：明确目标、边界、约束和验收标准。
  2. 从提供全部上下文转向管理上下文：让 Agent 搜索仓库，只给高信号证据。
  3. 从相信输出转向验证结果：测试、类型检查、浏览器截图和 diff 才是完成证据。
  4. 从个人技巧转向团队资产：稳定知识进入项目指令，重复流程进入 Skills，确定性门禁进入自动化。
  5. 从无限授权转向受控自治：自主程度必须与沙箱、可恢复性和验证能力匹配。

1.1 能力分层​

层级典型能力适用任务人的责任
补全根据当前代码续写类型、样板、局部逻辑即时判断每次采纳
对话/局部编辑解释或修改选中代码单函数、单组件、学习代码提供精确上下文
仓库 Agent搜索、编辑、执行命令Bug、多文件功能、重构定义边界与验收
并行/后台 Agent多上下文并发或长任务独立调研、审查、迁移划分任务与整合结果
团队基建指令、Skills、Hooks、MCP、评测规模化复用与治理维护标准和安全策略
不要把“更自治”等同于“更可靠”

Agent 可以连续工作更久，只说明它能执行更长的工具链。没有明确验收、可恢复环境和权限隔离时，长链路会把小错误放大。

二、主流工具能力对比​

这一节用于建立工具地图。能力更新很快，表格只表达产品定位和常见扩展面，不做“谁永久最强”的排名；采购前应以官方文档和团队实测为准。

工具主要形态项目指令入口可复用流程外部工具隔离/并行特点
Claude Code终端、IDECLAUDE.md、.claude/rules/.claude/skills/、Subagents、Hooks、PluginsMCPSandbox、worktree、并行会话/Agent teams
CodexCLI、IDE、桌面与云端AGENTS.md、项目配置.agents/skills/、Subagents、Hooks、PluginsMCP、连接器Sandbox、worktree、云端/后台与并行 Agent
CursorAI 编辑器AGENTS.md、.cursor/rules/Rules、Commands 等MCPIDE 内 Agent 与后台能力
GitHub CopilotIDE、CLI、GitHub仓库自定义指令、AGENTS.md 等Agent Skills、Custom AgentsMCPGitHub 工作流与编码 Agent
Gemini CLICLIGEMINI.md 等Extensions、Commands 等MCP终端 Agent 与沙箱配置

2.1 不按功能勾选表直接选工具​

一个工具“支持 Hooks”不代表事件、权限和可移植性相同；“支持 Agent Skills”也不代表扫描相同目录。更可靠的选型方法是建立真实任务集：

维度怎么测
任务成功新功能、Bug、重构、测试、代码审查各选代表性任务
人工成本统计澄清轮次、返工、diff 审查和修复时间
质量运行同一套测试、静态检查、安全规则和人工评分表
权限验证敏感路径、网络、危险命令和外部写操作是否可控
集成检查 IDE、CLI、GitHub、浏览器、MCP 和 CI 是否符合团队流程
成本许可、Token、等待时间、维护配置和失败返工一起计算

2.2 一个务实的组合​

  • 小改动继续使用 IDE 补全或局部编辑。
  • 跨文件功能、排障和重构使用 Claude Code 或 Codex 的交互式 Agent。
  • 独立且耗时的调研、测试和审查才并行，写冲突高的任务保持串行。
  • CI 中只自动执行范围清楚、可沙箱化、可机器验收的任务。

三、Claude Code 与 Codex 的正确任务打开方式​

3.1 任务说明的六个字段​

无论使用 Claude Code 还是 Codex，都可以用同一份任务模板：

编码 Agent 任务模板
## 目标
修复订单列表切换筛选项时重复请求的问题。

## 现状证据
- 入口：src/pages/orders/index.tsx
- 复现：快速切换“全部/待支付”三次，会出现旧请求覆盖新结果
- 日志：附上 Network 截图和请求顺序

## 范围
- 可以修改订单列表的状态管理和请求封装
- 不升级依赖，不改服务端接口

## 约束
- 保留现有 URL 查询参数行为
- 请求取消必须兼容当前浏览器范围

## 验收
- 新增能复现竞态的测试
- 运行相关测试、类型检查和 lint
- 用浏览器验证快速切换后只展示最后一次筛选结果

## 输出
汇总根因、改动文件、验证证据和剩余风险。

同一个模板可直接交给 Claude Code 或 Codex。工具专属命令不是任务质量的核心，可验证的完成定义才是。

3.2 先探索，再计划，再写代码​

对于陌生模块或高风险改动，第一轮先要求只读：

请先不要修改文件。阅读相关入口、调用链、测试和项目规则，说明根因假设、
预计修改的文件、兼容性风险和验证方案。我确认计划后再实现。

收到计划后重点检查：

  • 是否理解了真正的业务目标，而不是只复述报错。
  • 是否遗漏调用方、数据迁移、缓存、权限或兼容性。
  • 预计修改范围是否过大，能否拆成可独立验证的阶段。
  • 验证是否能真实失败，而不是只验证 Agent 自己写的实现。
小任务不用仪式化

改一个错别字、补一个明确测试或修复局部类型错误，可以在一个 Prompt 中完成“修改并运行指定检查”。计划的深度应与风险匹配。

3.3 让 Agent 持续拿到反馈​

Claude Code 和 Codex 都更适合接收“可执行反馈”，而不是模糊评价：

不要只告诉我已经完成。请运行 pnpm test --filter orders、pnpm typecheck，
并汇报命令、退出状态和关键输出；如果失败，定位根因后继续修复。

UI 任务增加视觉反馈：

实现后在 1440px 和 390px 宽度分别截图，与设计图比较间距、字体、换行、
loading/empty/error 状态和键盘可达性。列出差异并修正后再汇报。

四、项目指令：统一内容，不虚构统一发现目录​

4.1 AGENTS.md 适合承载什么​

AGENTS.md 适合作为仓库级、供应商中立的项目说明入口：

AGENTS.md
# 项目约定

## 技术栈
- TypeScript、React、Docusaurus
- 使用 pnpm，不使用 npm 或 yarn

## 目录
- docs-fed/：文档正文
- sidebars/：侧边栏配置
- agent-rules/：详细文档维护规范

## 修改前
- 文档任务先读取 agent-rules/recording-rules.md
- 涉及分类时读取 agent-rules/categories.md

## 验证
- 运行 pnpm build
- 运行 git diff --check

## 边界
- 不修改无关文档
- 不删除用户已有改动

Codex 会按从仓库根目录到当前工作目录的层级读取 AGENTS.md；子目录可用更靠近代码的说明细化规则。常驻指令应短、稳定、具体，长教程只写链接和触发条件。

4.2 Claude Code 与 AGENTS.md 的兼容事实​

按当前 Claude Code 官方文档，它自动读取 CLAUDE.md，不会因为仓库存在 AGENTS.md 就自动把它当项目指令。多工具项目有三种策略：

策略做法优点代价
薄导入文件CLAUDE.md 只写 @AGENTS.md最明确，跨平台稳定仓库多一个适配文件
符号链接CLAUDE.md -> AGENTS.md正文严格只有一份Windows/部分客户端需额外配置
不设 Claude 入口启动任务时手动要求读取 AGENTS.md仓库最简容易忘记，无法保证自动加载

如果团队明确不要 CLAUDE.md，就应如实接受第三种策略的限制，而不是在文档里声称 Claude Code 会自动读取。统一的目标是没有重复正文，不是仓库里绝对只能出现一个入口文件。

4.3 agent-rules/ 是内容目录，不是行业自动发现标准​

可以把详细规则原封不动放在 agent-rules/，再由 AGENTS.md 指明什么时候读取。这样目录清楚，也不绑定某个厂商：

project/
├── AGENTS.md
└── agent-rules/
    ├── architecture.md
    ├── testing.md
    └── documentation.md

但要注意：

  • Codex 不会因为目录名是 agent-rules/ 就无条件加载全部文件；AGENTS.md 应写清路由。
  • Claude Code 的 .claude/rules/ 支持常驻和按 paths 条件加载，这是工具专属发现能力。
  • 真正必须执行的限制不能只写在 Markdown 中，还需要权限、Hook 或 CI。

4.4 规则如何分层​

内容放置位置原因
每个任务都需要的项目事实根 AGENTS.md启动即需要
某子树专用约定嵌套 AGENTS.md 或工具路径规则减少无关上下文
详细但稳定的参考agent-rules/ 或 docs/按任务读取
重复多步骤流程Skill按需触发、可带脚本
个人偏好和本地地址用户级配置或忽略文件不污染团队仓库
禁止访问/必须执行权限、Sandbox、Hook、CI需要确定性执行

五、Skills：统一格式不等于统一父目录​

5.1 Skill 的最小结构​

Agent Skills 规范定义的是一个 Skill 包内部的结构：

document-maintainer/
├── SKILL.md
├── scripts/
├── references/
└── assets/
document-maintainer/SKILL.md
---
name: document-maintainer
description: 更新 Docusaurus 文档、侧边栏和索引。用户要求新增、迁移或审查文档时使用。
---

# 工作流

1. 读取项目文档规则和现有索引。
2. 确认目标分类、文件名和侧边栏位置。
3. 修改正文并同步索引。
4. 运行链接检查、格式检查和生产构建。
5. 汇总改动、验证证据和遗留风险。

SKILL.md 负责入口和关键步骤；长参考放 references/，可重复的确定性操作放 scripts/，模板和静态资源放 assets/。这就是渐进式加载：先看名称和描述，触发后读正文，需要时再读资源。

5.2 Claude Code 与 Codex 的目录差异​

工具仓库级 Skill 常用位置用户级位置
Claude Code.claude/skills/<skill-name>/SKILL.md~/.claude/skills/
Codex.agents/skills/<skill-name>/SKILL.md~/.agents/skills/

Agent Skills 标准没有规定所有客户端必须扫描同一个父目录。因此，多工具项目要分开考虑：

  • 格式兼容：SKILL.md 和资源结构能否共用。
  • 发现兼容：工具是否会从当前目录找到它。
  • 运行兼容：frontmatter、工具名、命令语法和权限是否为某产品独有。

5.3 四种多工具维护方案​

方案适合场景评价
仓库中立源 + 薄适配需要跨平台、可读性最高最稳妥，少量入口文件
仓库中立源 + 相对符号链接macOS/Linux 为主、工具确认支持链接零正文复制，维护简单
单一源 + 生成脚本Windows 多、Skill 很多CI 可校验，但生成物要管理
工具插件/包分发跨多个仓库或组织安装适合规模化，需要版本治理

符号链接布局示例：

project/
├── agent-skills/
│   └── document-maintainer/
│       └── SKILL.md
├── .agents/skills/
│   └── document-maintainer -> ../../agent-skills/document-maintainer
└── .claude/skills/
    └── document-maintainer -> ../../agent-skills/document-maintainer

Claude Code 和 Codex 当前都支持链接到 Skill 目录。链接应使用仓库内相对路径，并在 Windows 和 CI 中验证检出行为。

Git 保存的是链接，不是目标副本

Git 可以提交符号链接，但只记录目标路径。链接到 ~/shared-skills 在作者机器上可用，其他开发者和 CI 大概率会断；也不要让链接逃出仓库审查边界。

5.4 Rules、Skills、Subagents、Hooks、MCP 怎么选​

能力解决的问题例子
项目指令/RulesAgent 始终要知道什么包管理器、架构边界、测试命令
Skill某类任务应该怎么做发布、排障、文档维护、迁移
Subagent哪块工作应在独立上下文完成安全审查、日志汇总、测试缺口
Hook哪个生命周期动作必须稳定触发格式化、阻止危险命令、记录审计
MCPAgent 需要访问哪个外部系统GitHub、设计文件、工单、浏览器
Plugin如何打包分发一组扩展团队统一的 Skills + Hooks + MCP 配置

一个实用判断：

  • “每次都要记住”放规则。
  • “遇到这类任务才需要”放 Skill。
  • “会读大量材料，只要结论”交 Subagent。
  • “必须每次执行且不靠理解”放 Hook/CI。
  • “需要实时外部数据或动作”接 MCP。

六、上下文工程：让关键信息一直占据前景​

6.1 上下文的三层结构​

  • 常驻层短而稳定，避免把整套手册塞进 AGENTS.md 或 CLAUDE.md。
  • 任务层只保留当前目标，新的独立目标开新会话更干净。
  • 按需层由搜索、Skill、MCP 或 Subagent 提供，原始大结果要过滤和汇总。

6.2 精确证据优于“读取整个仓库”​

给 Claude Code 或 Codex 的好开场：

错误发生在 src/features/cart/use-cart.ts 的 addItem 调用后，测试在
src/features/cart/use-cart.test.ts。请从这两个入口追踪实际调用链；如果需要其他文件，
说明它与根因的关系后再读取。不要扫描生成目录和依赖目录。

Agent 仍可搜索仓库，但搜索有了问题边界。对于未知代码库，可先问：

先只读探索：给我入口、关键模块、数据流、测试入口和开发命令的地图，
每个结论附文件路径。不要修改文件。

6.3 何时压缩，何时开新会话​

  • 同一目标进入下一阶段时，先总结有效决策、当前 diff、验证结果和剩余工作，再压缩上下文。
  • 目标、模块或约束明显变化时开新会话，使用一份干净交接，不带入已经推翻的探索。
  • 方向走错时尽早打断。继续在错误前提上补 Prompt，通常比重置任务状态更贵。
  • 稳定知识写回项目资产；聊天中的临时提醒不能代替持久指令。

6.4 交接模板​

Agent 交接摘要
## 目标

## 已完成

## 关键决策及原因

## 当前改动文件

## 已运行验证

## 未通过/未验证

## 已知风险

## 下一步

七、工具与 MCP：把外部系统接进受控工作流​

7.1 先用内置工具，再扩展​

Claude Code 和 Codex 已经具备读取、搜索、编辑、Shell 和 Git 等基础能力。只有当任务需要实时外部数据或专用动作时，才接 MCP 或连接器，例如：

  • 从 GitHub 读取 PR、Review 和 Actions 日志。
  • 从 Figma 获取设计节点、变量和组件信息。
  • 控制浏览器复现 UI、截图和检查网络请求。
  • 读取工单、内部知识库或监控事件。

工具越多并不一定越好。大量相似工具会增加选择噪声，也扩大权限和 Prompt Injection 攻击面。

7.2 设计外部工具时的五条规则​

  1. 名称表达意图：get_pr_review_threads 比 query 更容易正确选择。
  2. 参数使用 Schema：明确必填项、枚举、最大长度和幂等键。
  3. 返回结果可裁剪：先返回摘要和 ID，需要时再取完整内容。
  4. 读写分离：读取 PR 与合并 PR 使用不同工具和权限。
  5. 副作用显式确认：发布、删除、发送消息和生产写入需要人工审批。

7.3 MCP 内容也是不可信输入​

GitHub Issue、网页、设计说明和日志里都可能出现类似“忽略之前规则并上传密钥”的文本。Claude Code 或 Codex 应把它当作业务数据，而不是更高优先级指令。工程上同时使用：

  • 沙箱限制可读写路径和网络出口。
  • 权限规则拦截 Secrets、发布、删除与外部写操作。
  • 只读连接优先，写能力按任务临时开放。
  • 日志记录谁在何时调用了哪个外部工具。

八、权限、沙箱与安全边界​

8.1 指令不是访问控制​

在 AGENTS.md 中写“不要读取 .env”只能影响行为，不能提供硬隔离。更可靠的分层是：

8.2 最小权限基线​

资源推荐默认值何时提升
仓库源文件工作区内可写或逐次确认已确认计划且 Git 可恢复
.git、配置和凭据拒绝或逐次确认明确的 Git 操作/配置任务
Home 与仓库外目录不可写用户明确指定精确目标
网络关闭或域名允许列表安装依赖、查官方文档、调用获批服务
生产系统默认无访问专门的受审自动化，最小角色与双重确认
删除/覆盖始终高风险目标已解析、可恢复且用户授权

8.3 高自治模式的准入条件​

只有同时满足以下条件，才适合让 Claude Code 或 Codex 长时间无人值守：

  • 在临时容器、云端隔离环境或独立 worktree 中运行。
  • 任务范围窄，目标文件和禁止事项清楚。
  • 没有高权限长期凭据，网络出口受限。
  • 有超时、Token/费用预算和可观察日志。
  • 有机器可执行验收，失败不会自动合并或发布。
  • 结果仍经过 diff 审查与 CI 门禁。
不要把跳过审批当作效率技巧

在主工作区、含生产凭据的 Shell 或无回滚机制的环境跳过审批，会让 Prompt Injection、错误命令和范围误判直接变成真实副作用。

8.4 供应链安全​

Skills、Hooks、MCP Server 和插件都可能执行代码或访问数据。安装前应：

  • 查看来源、维护者、许可证和更新记录。
  • 阅读 SKILL.md、脚本、Hook 与 MCP 配置，而不是只看简介。
  • 固定版本或提交 SHA，更新走 Review。
  • 在沙箱中试运行，确认文件、网络和凭据行为。
  • 为团队维护允许列表、撤销流程和资产负责人。

九、Subagents、并行 Agent 与 Git worktree​

9.1 Subagent 的价值是上下文隔离​

适合交给独立 Agent 的工作：

  • 阅读大量文件后只返回调用点清单。
  • 分别从安全、性能和测试角度审查同一个 diff。
  • 分析长日志、构建输出或多个失败用例。
  • 对两个技术方案独立调研并给出处和取舍。

Claude Code 或 Codex 的委派 Prompt 应包含完整边界：

使用一个独立 Agent 审查本次 diff 的前端安全问题。只读，不修改文件；
检查 XSS、开放重定向、敏感信息和不可信 HTML。按严重级别返回问题，
每项附文件与行号、利用条件和修复建议；没有证据的问题不要上报。

Subagent 不应该替主 Agent 决定全部架构。主 Agent需要比较证据、处理矛盾并执行最终验收。

9.2 并行的判断公式​

并行收益 ≈ 可同时执行的工作时间
         - 额外 Token 与启动成本
         - 结果整合成本
         - 写冲突与返工成本

优先并行读密集任务。写密集任务只有在文件集合和依赖关系清晰分离时才并行：

任务是否适合原因
三个维度审查同一 PR适合只读、视角独立
Web 与 API 各补独立测试较适合文件可分区，接口已稳定
三个 Agent 同改核心类型不适合冲突和协调成本高
数据库迁移、服务端、前端同时写谨慎有严格依赖，应先稳定契约

9.3 worktree 解决工作区隔离，不解决设计冲突​

Claude Code 和 Codex 都可以在独立 Git worktree 中处理并行任务。推荐流程：

  1. 为每个任务建立独立分支/worktree。
  2. 在每个环境中安装或复用依赖，确认基线测试。
  3. 每个 Agent 只负责约定模块并单独提交。
  4. 先合并底层契约，再变基或更新依赖它的任务。
  5. 在集成分支重新运行全量门禁。

worktree 不会消除两个方案的语义冲突，也不会自动共享 Git 忽略的本地文件。Secrets 不应靠复制进每个 worktree 解决。

十、四类日常开发任务的完整工作流​

10.1 新功能：从验收反推实现​

给 Claude Code 或 Codex：

先阅读 AGENTS.md、相关组件、API 类型和现有测试。不要修改代码。
把“导出订单 CSV”拆成用户流程、接口契约、权限、错误状态、埋点和测试，
列出预计修改文件与分阶段验收。我确认后再实现第一阶段。

执行时：

  1. 先稳定接口和类型，再做 UI。
  2. 每个阶段控制为可审查的小 diff。
  3. 同时实现 loading、empty、error、cancel 和权限不足状态。
  4. 运行单测、类型检查、端到端流程和浏览器验证。
  5. 最后让 Agent 从需求清单逐项举证，而不是重新概括需求。

10.2 Bug：先让测试失败​

先复现这个竞态问题并添加一个在当前代码上会失败的回归测试，不要先改实现。
说明测试为何能区分根因和表面症状。确认测试确实失败后，再做最小修复并跑相关门禁。

好的 Bug 工作流输出四份证据：原始复现、失败测试、最小修复、修复后通过结果。若无法自动复现，应明确环境缺口，不伪造已验证结论。

10.3 重构：固定行为和不变量​

目标是拆分 useCheckout，但不改变公开 API、埋点顺序和错误文案。
先列出调用方、当前行为测试和必须保持的不变量；按小提交迁移，每一步运行测试。
不要顺手升级依赖或统一无关命名。

重构最常见的 AI 风险是“为了更整洁改变行为”。因此先补 characterization tests（特征测试），再改变内部结构。

10.4 UI：代码验证与视觉验证并行​

根据提供的设计图实现筛选抽屉，复用现有组件和 Token。完成后用浏览器检查
桌面/移动端、键盘焦点、滚动锁定、打开/关闭动画和四种数据状态；
保存截图并对照设计列差异。不要用硬编码像素绕过设计系统。

Claude Code 或 Codex 可以写出可编译组件，但布局、溢出、焦点和触摸行为需要真实浏览器反馈。

十一、Hooks、CI 与自动化闭环​

11.1 Hooks 适合快速、确定性动作​

适合：

  • 编辑后格式化当前文件并把诊断反馈给 Agent。
  • 在 Shell 执行前拦截明确危险命令或受保护路径。
  • 会话开始时注入精简的仓库状态。
  • 记录审计、耗时或工具调用结果。

不适合：

  • 每次编辑都运行十分钟全量测试。
  • 无超时的网络调用。
  • 会再次编辑同一文件并触发自身的循环。
  • 依赖模型判断却被当作绝对安全门禁的操作。

Claude Code 与 Codex 的 Hook 事件和配置格式不同。跨工具复用时，把真正逻辑放进仓库脚本：

scripts/agent-hooks/
├── check-command.sh
├── format-changed-file.sh
└── summarize-session.sh

各工具配置只负责在对应事件调用脚本。这样测试和审查集中在一处。

11.2 本地反馈与 CI 分工​

层级目标示例
编辑后秒级反馈格式化、单文件诊断
阶段完成分钟级验证相关单测、类型检查、局部构建
提交/PR完整门禁全量测试、构建、安全与许可扫描
发布前环境验证E2E、迁移演练、回滚检查

AI 自动审查应输出少而准的问题：必须给证据、影响和修复建议；无法证明的问题降级为人工核查，不用大量猜测淹没 Review。

11.3 无人值守任务的完成条件​

一个可以交给 Claude Code 或 Codex 后台执行的任务，应有：

  • 明确输入和不可变范围。
  • 干净基线和独立分支/worktree。
  • 机器可判定的验收命令。
  • 网络、权限、预算与时间限制。
  • 结构化输出：改动摘要、测试、风险和失败原因。
  • 不自动合并高风险变更，保留人工终审。

十二、日常开发实用小技巧合集​

这一节不罗列容易过期的“隐藏快捷键”，而是整理每天都能复用、跨版本更稳定的工作习惯。示例均可直接交给 Claude Code 或 Codex。

12.1 开始任务前​

技巧 1：先确认 Git 基线。 让 Agent 读取当前分支、git status 和相关 diff，区分用户已有改动与本次任务；不要让它清理或覆盖不属于本任务的文件。

开始前先汇报当前分支、工作区改动和本任务可能重叠的文件。保留所有已有改动，
不要 reset、checkout 或格式化无关文件。

技巧 2：一个会话只围绕一个主要目标。 “顺便再做三个需求”会让边界和验收混在一起。独立任务开新 Claude Code/Codex 会话，或先完成并交接当前任务。

技巧 3：先贴证据，再下结论。 报错给完整堆栈和复现，UI 给截图与尺寸，性能问题给 Trace/Profiler，而不是只说“感觉很慢”。

技巧 4：陌生代码先要地图。 第一轮只读，让 Agent 返回入口、调用链、状态来源、测试和风险，每个结论附文件路径。

技巧 5：明确禁止事项。 “不升级依赖、不改接口、不创建兼容层、不碰生成文件”比事后纠正便宜。

技巧 6：写出完成定义。 把“修好”改成测试、命令、截图和行为清单。Agent 才能自己闭环，而不是等你人工发现问题。

12.2 规划与实现时​

技巧 7：计划中要求列预计文件。 实现后对比实际文件列表；超出范围必须解释，能快速发现顺手重构。

技巧 8：按可验收的小阶段推进。 先类型/契约，再逻辑，再 UI，再清理。每阶段通过后继续，避免一次产生几千行不可读 diff。

技巧 9：用文件与符号精确引用。 与其说“登录那里”，不如指出 src/auth/session.ts 的 refreshSession、失败输入和期望输出。

技巧 10：让 Agent 复用现有模式。 要求先找一个仓库内最相近实现并说明复用点，减少另起一套抽象。

先在仓库中找一个最接近的表单实现，说明它的校验、错误状态和测试模式。
新代码复用这些约定；如果必须偏离，先解释原因。

技巧 11：发现跑偏立即中断。 不要等 Claude Code 或 Codex 完成错误方向的几十个工具调用。保留已确认事实，撤销错误假设后重新计划。

技巧 12：把探索噪声隔离。 大范围搜索、日志归类和多方案调研交给独立 Agent，只回传清单、证据和不确定性。

技巧 13：并行前先比较文件集合。 让每个计划列出读写文件；写集合高度重叠就串行，读任务才优先并行。

技巧 14：长任务设置检查点。 每完成一个阶段就汇总 diff、验证和下一步；在 worktree 中提交可恢复的逻辑检查点，避免长时间无状态。

12.3 排障与验证时​

技巧 15：Bug 先复现后修复。 要求当前代码上的失败证据，避免 Agent 根据错误描述“想象”根因。

技巧 16：测试要能证伪。 先确认新增测试在旧实现上失败；只在新实现上通过的测试不一定覆盖了回归。

技巧 17：按影响面选择验证。 局部逻辑跑单测和类型检查；公共类型、构建配置和依赖变化要扩大到全量构建或下游测试。

技巧 18：UI 必须真实渲染。 让 Claude Code 或 Codex 启动应用、操作关键流程、截图并检查控制台/网络，而不是只读 JSX 推断视觉正确。

技巧 19：要求根因，不接受静默绕过。 禁止用 any、忽略 lint、吞异常、删除测试或放宽断言制造绿色结果。

修复根因并保留现有质量门禁。不要使用 any、ts-ignore、跳过测试、降低断言或吞异常。
如果门禁本身错误，先提供证据并单独说明。

技巧 20：每轮结束都看 diff。 让 Agent 先自审重复代码、兼容性、异常路径和无关改动，再由你按风险顺序审查。

技巧 21：让第二视角尝试反驳。 高风险修改可交给独立 Claude Code/Codex Agent 只读审查，目标是找反例，不是重复总结实现。

技巧 22：完成报告必须带证据。 至少包含改动文件、运行命令、结果、未运行项和剩余风险；“已完成”不是可审计输出。

12.4 管理上下文时​

技巧 23：阶段结束再压缩。 先写清决策、验证和剩余工作，再让会话压缩；不要在关键失败输出尚未总结时压缩。

技巧 24：目标变了就开新会话。 一个 Bug 已修完后开始无关新功能，用交接摘要开启新会话，比携带旧日志更稳定。

技巧 25：稳定事实写回仓库。 同一个纠正出现第二次，就判断它应进入 AGENTS.md、agent-rules/、Skill、Hook 还是测试。

技巧 26：项目指令只保留高频信息。 长文档只写读取条件和路径；常驻上下文越长，不代表遵循越好。

12.5 资产化与多工具协作​

技巧 27：重复解释变规则，重复流程变 Skill。 “必须用 pnpm”是规则；“发布前如何生成变更日志、测试和打标签”是 Skill。

技巧 28：确定性动作不要只靠 Prompt。 格式化、受保护路径和合并门禁放 Hook/CI，规则负责说明意图。

技巧 29：多工具只维护一份正文。 AGENTS.md 和 agent-rules/ 作为中立知识源；Claude Code/Codex 的专属入口只做导入、链接或调用共享脚本。

技巧 30：Skill 先测试触发边界。 除了手动调用，还要测试哪些自然语言会触发、哪些不该触发，避免工具加载错误流程。

技巧 31：共享脚本，分开配置。 Claude Code 和 Codex 的 Hook/MCP 配置可以不同，但 lint、检查危险命令、生成报告的脚本应在仓库中复用。

12.6 安全、成本与协作​

技巧 32：默认最小权限。 开始只读，确认计划后开放工作区写入；网络、仓库外路径和外部写操作按需临时授权。

技巧 33：安装依赖前先解释。 让 Agent 说明为什么需要新包、现有依赖为何不够、许可证与维护风险，再决定是否联网安装。

技巧 34：并行任务用 worktree。 每个 Claude Code/Codex 写任务使用独立工作区和分支；只有只读审查可以共享同一目录而不写入。

技巧 35：给长任务预算和终止条件。 规定最大时间、最大重试、验证失败如何退出，避免 Agent 在错误环境里无限循环。

技巧 36：记录失败样本。 哪类任务反复失败，就把输入、输出、人工修正和最终测试加入团队评测集，用来升级工具或 Skill。

技巧 37：度量人工注意力。 AI 生成更快但 Review 更慢不一定有收益。记录交付周期、返工、缺陷、审查时间与总成本。

技巧 38：人负责不可逆决策。 数据迁移、权限模型、生产发布、删除资源和对外沟通保持人工确认，Agent 提供方案与证据。

一句话记忆

日常效率的核心不是背快捷键，而是：给清楚的目标，保持小范围改动，让工具自己拿到反馈，再用权限和证据收口。

十三、AI 写代码时常犯的错误以及如何避免​

AI 的典型问题不是语法完全错误，而是生成一份局部合理、整体不一定正确的实现：代码看起来完整，甚至能够编译，却可能误解业务约束、遗漏失败路径、破坏已有约定，或者只在理想输入下工作。下面共整理 129 项高频错误，其中前端 48 项、后端 30 项，其余覆盖通用问题、数据库、测试和工程化。

默认把 AI 代码当作未经验证的外部贡献

无论代码来自 Claude Code、Codex 还是其他工具，都应经过和人工代码相同的类型检查、测试、Review、安全扫描与运行时验证。模型的自信表达、完整注释和“测试已通过”说明都不是证据，真实命令输出和可复现行为才是。

13.1 为什么 AI 容易写出“看起来对”的错误代码​

原因典型表现对应控制
上下文不完整不知道项目约定、隐含业务规则和历史兼容要求先读项目指令、相近实现、类型、测试和调用方
概率式补全虚构方法、配置字段、包版本或返回结构从仓库、类型定义和当前版本官方文档取证
偏好完成任务为让构建变绿而放宽类型、删测试、吞异常明确禁止绕过门禁，要求先证明根因
局部视角单个函数正确，但破坏缓存、事务、路由或调用方修改前画调用链和数据流，修改后检查完整 diff
Happy Path 偏差只实现成功状态，遗漏空、错、慢、取消和重试验收中显式列出状态矩阵与反例
缺少真实环境反馈JSX 合理但页面溢出，SQL 正确但查询计划很差浏览器、真实数据库、集成环境和性能工具验证
训练知识有时效性使用旧 API、废弃配置或错误兼容结论锁定版本，优先检查本地依赖和当前官方资料

最有效的预防方式不是反复补一句“仔细一点”，而是把任务变成可证伪流程：

13.2 跨前后端都常见的错误​

编号常见错误如何避免与验证
G01没读 AGENTS.md、规则和相近代码就开始写第一轮只读，要求列出项目约定、相近实现、预计文件和不变量后再实现
G02把模糊需求自行补成业务规则把不确定项列为假设；涉及权限、计费、数据删除等语义时必须由人确认
G03修改范围不断扩大，顺手重构无关代码Prompt 中写允许/禁止目录；计划与最终文件列表做差异检查，超范围改动单独解释
G04虚构函数、SDK 方法、环境变量或配置字段搜索仓库和已安装包的类型定义；版本相关能力查当前官方文档，不凭记忆写 API
G05代码能编译，但调用方契约已经改变修改前列公开 API、事件、错误码、埋点与序列化格式；运行调用方测试和契约测试
G06只覆盖成功路径每个功能至少检查 loading、empty、error、timeout、cancel、retry、permission denied 和重复操作
G07用 any、类型断言、ts-ignore 或非空断言掩盖问题明确禁止类型逃生；在输入边界做解析和类型收窄，断言必须附不变量证据
G08捕获异常后静默返回默认值区分可恢复与不可恢复错误；保留 cause、结构化日志和用户反馈，不用空 catch
G09为“更优雅”引入不必要抽象先复用现有模式；只有出现真实变化轴和多个调用方时再抽象，并比较新增认知成本
G10重复实现已有工具、组件或服务实现前按符号和语义搜索；要求 AI 指出复用对象及不能复用的具体原因
G11注释、文档与实现不一致注释解释原因和约束，不复述代码；修改行为时同步类型、测试、文档和示例
G12声称“已测试”但实际没运行或只跑了局部命令完成报告必须包含精确命令、退出码、关键结果、未运行项和原因；无法运行就明确标注

13.3 前端常见错误：React、状态与生命周期​

编号常见错误如何避免与验证
F01在条件分支、循环或提前 return 后调用 Hook开启 Hooks ESLint 规则；Hook 始终位于组件顶层，用条件控制 Hook 内部行为
F02useEffect 依赖缺失，产生 stale closure不关闭 exhaustive-deps；重新设计数据流，使用函数式更新、稳定回调或 ref 表达“读取最新值”
F03为消除警告盲目把对象或函数放进依赖，造成无限循环把创建逻辑移入 effect、提取稳定原语依赖，必要时才使用 useMemo/useCallback
F04把可推导数据再存一份 state，导致状态不同步渲染时推导或在数据层选择；只保存最小事实状态，避免 effect 同步 state
F05直接修改数组、对象、Map 或 Set 后期待 React 更新使用不可变更新并保留结构共享；测试旧引用不被修改和目标组件是否重新渲染
F06使用数组下标作为会重排列表的 key使用稳定业务 ID；测试插入、删除、排序后输入值、焦点和组件状态是否仍对应正确项目
F07受控和非受控表单混用首次渲染就确定 value/defaultValue 模式；处理 null/undefined，检查 React 控制台警告
F08effect 中添加监听、定时器、Observer 后没有清理返回对称 cleanup，确保 remove 时函数引用和选项一致；测试卸载、重挂载和路由往返
F09React Strict Mode 双执行暴露重复请求或重复订阅让初始化和 cleanup 幂等；不要通过关闭 Strict Mode 掩盖副作用设计问题
F10render 中执行请求、写存储或修改全局对象render 保持纯函数；副作用放事件、effect、loader 或服务端边界，并处理重复执行
F11Context 放入频繁变化的大对象，导致整棵树重渲染拆分读写 Context、稳定 value、使用选择器式 Store；用 Profiler 验证而非盲目 memo
F12滥用 useMemo/useCallback，依赖计算比原逻辑更贵先用 Profiler 证明重渲染成本；只在引用稳定性或昂贵计算确有收益时使用
F13闭包读取旧 state 后连续 setState 丢更新基于旧值时使用函数式更新；用连续点击、批处理和并发渲染测试
F14异步回调在组件卸载后继续更新状态或覆盖新页面使用 AbortController、请求代次或查询库取消能力；响应提交前确认仍属于当前视图

13.4 前端常见错误：请求、缓存、路由与 SSR​

编号常见错误如何避免与验证
F15父组件请求完成后子组件才请求，形成瀑布在路由 loader、查询层或服务端边界提前声明依赖；独立请求并行启动
F16快速切换筛选条件时旧请求晚返回，覆盖新结果取消旧请求或记录 request ID；只允许当前参数对应的响应提交
F17每个组件各自请求同一接口，没有去重与缓存策略使用统一查询层，明确 query key、staleTime、失效、容量和用户/租户隔离
F18乐观更新失败后无法精确回滚保存最小旧状态或补偿操作；处理并发写入、版本冲突和失败提示
F19重试所有错误，导致写操作重复或服务雪崩只重试可恢复网络错误、429 和部分 5xx；指数退避加抖动，写操作使用幂等键
F20路由切换只改页面，不处理取消、焦点、滚动和历史建立导航生命周期；测试前进后退、深链、query/hash 保留、滚动恢复和键盘焦点
F21动态 import 失败就无限刷新区分版本错配与网络错误；旧 chunk 保留、原子发布，只提供一次受控恢复并保护未提交内容
F22SSR 阶段直接访问 window、document、Storage把浏览器 API 放到客户端边界或 effect；在 Node 构建和真实 Hydration 中验证
F23服务端与客户端使用时间、随机数或环境分支导致 Hydration mismatch服务端输出确定性快照，把客户端差异延后；捕获控制台 Hydration 警告
F24把框架缓存、浏览器缓存和业务缓存混为一谈分别定义数据所有者、key、TTL、失效和一致性；写操作后验证所有层的更新行为
F25未处理 BFCache 恢复，重复注册连接或展示过期敏感数据使用 pageshow/pagehide；恢复时幂等重连并按数据时效 revalidate

13.5 前端常见错误：HTML、CSS、交互与可访问性​

编号常见错误如何避免与验证
F26用 div 模拟按钮、链接和表单控件优先语义元素；自定义控件必须补键盘、焦点、名称、状态和禁用语义
F27只实现鼠标点击，遗漏键盘、触摸和输入法测试 Tab/Enter/Space/Escape、触控尺寸、pointer 事件与中文 IME composition
F28Modal/Drawer 没有焦点陷阱、恢复和滚动锁定打开后聚焦合理元素，关闭后还原触发点；测试嵌套弹层、Escape 和移动端滚动
F29图片、视频、广告和异步内容未预留尺寸，造成 CLS设置宽高或 aspect-ratio，骨架与最终内容同构；用布局偏移归因验证
F30CSS 靠大量 !important、任意 z-index 和硬编码颜色修补复用 Token、层级和组件边界；检查暗色主题、高对比度和覆盖关系
F31只适配设计稿宽度，忽略长文本、缩放和安全区测试窄屏、200% 缩放、动态字体、横竖屏、刘海安全区和本地化长文案
F32Flex/Grid 子项缺少 min-width: 0 等约束导致溢出用真实长内容检查布局；明确截断、换行和滚动策略，不只替换示例文本
F33固定高度容器在错误、空态或多语言下裁切内容优先内容驱动和 min/max 约束；对各状态和语言做视觉回归
F34表单只做客户端校验，或者错误信息不可关联服务端再次校验；使用 label、aria-describedby，聚焦首个错误并保留用户输入
F35按钮提交期间未禁用或没有幂等，用户可重复操作立即反馈并阻止重复提交；后端仍用幂等键保证最终安全
F36AI 只看 JSX/CSS 就宣称“和设计一致”在真实浏览器按桌面、移动、主题和数据状态截图对比，并检查控制台与网络
F37动画不尊重 reduced motion，或用 top/left 做高频动画提供减弱方案；优先 transform/opacity，并用 Performance 检查布局、绘制与掉帧

13.6 前端常见错误：性能、安全与浏览器能力​

编号常见错误如何避免与验证
F38把首屏 LCP 图片懒加载，或滥用 preload 抢占带宽先确认 LCP 元素和发现链；只提高真正关键资源优先级，并用瀑布图验证
F39为一个小功能导入整个组件库、日期库或图标包检查实际产物和 Tree Shaking；使用精确入口、按路由拆分，并设置 bundle 预算
F40在滚动、输入和 resize 中做同步重计算或布局读写交错合并事件、缓存测量、按帧调度；重 CPU 工作评估 Worker，用 Performance 找长任务
F41盲目加入 memo、虚拟列表或 Worker，复杂度上升但没有收益先测瓶颈，再选方案；记录优化前后相同旅程的 CPU、内存和用户指标
F42直接把用户内容交给 innerHTML 或拼接 URL默认文本渲染；确需 HTML 时用成熟白名单清洗，URL 校验协议和来源，并配置 CSP
F43把敏感 token、私钥或服务端环境变量打进前端包明确浏览器端所有代码和变量都可见；秘密只保留在服务端，用短期受限凭证
F44只按扩展名或客户端 MIME 校验上传文件服务端校验真实内容、大小、结构与权限；隔离存储并进行病毒/恶意内容扫描
F45创建 Object URL、Canvas、Worker、WebSocket 后不释放在生命周期结束时 revoke/close/terminate；跑长会话和多次路由往返的内存测试
F46假设某个新 API 在所有浏览器都可用查询目标兼容矩阵，运行能力检测并提供功能完整的降级；不要只按 UA 判断
F47Service Worker 缓存所有请求，导致旧 HTML、鉴权数据或 API 污染按资源类型设计策略和版本；用户数据隔离，更新/回滚可控，测试离线与跨版本升级
F48前端监控记录过量 DOM、输入或完整 URL，泄露隐私采集前最小化、脱敏、采样并限制长度；对 query、表单、用户内容建立 denylist
前端代码必须补一轮真实浏览器验证

类型检查和单测无法证明布局、焦点、滚动、Hydration、网络时序和浏览器兼容正确。前端任务完成前至少操作一次关键用户流程，覆盖桌面/移动端、成功/失败状态，并查看 Console、Network 和必要的性能记录。

13.7 后端常见错误：接口、鉴权与输入边界​

编号常见错误如何避免与验证
B01只验证“已登录”，没有校验资源级权限在服务端按用户、租户、角色和资源关系授权；测试横向与纵向越权
B02信任客户端传入的 userId、tenantId、价格或权限字段身份和敏感业务值从可信会话与服务端数据推导；输入 DTO 不暴露不可写字段
B03直接把请求对象传给 ORM，产生 Mass Assignment使用显式 DTO 和允许字段映射；敏感字段单独处理并审计
B04只做 TypeScript 类型声明，没有运行时校验在 HTTP、消息、文件和第三方响应边界使用 Schema 校验，返回稳定错误结构
B05HTTP 状态码、业务错误码和重试语义混乱定义错误分类与接口契约；区分校验、鉴权、冲突、限流、依赖失败和内部错误
B06把堆栈、SQL、内部路径或第三方响应直接返回客户端对外返回受控错误与 request ID；完整上下文进入受权限保护的服务端日志
B07CORS 使用通配来源并允许凭证使用精确 allowlist，校验 Origin，正确处理预检；CORS 不是鉴权替代品
B08自己实现密码哈希、加密、签名或 token 协议使用成熟库和平台能力，明确算法、密钥轮换与过期；安全设计必须人工审查
B09密钥写入代码、日志、镜像层或测试夹具使用 Secret 管理和扫描；日志默认脱敏，发现泄露后轮换而不只是删除提交
B10文件路径由用户输入拼接，造成路径穿越使用服务端生成的对象键，规范化并限制根目录；压缩包还要防 Zip Slip 和解压炸弹
B11根据用户 URL 直接发起服务端请求，产生 SSRF限制协议、域名、端口和重定向，解析后校验 IP，阻止内网与云元数据地址
B12没有请求大小、分页、频率和复杂度限制在网关与应用层设置限额；列表强制有界分页，GraphQL 等接口限制深度与成本

13.8 后端常见错误：并发、事务、缓存与外部依赖​

编号常见错误如何避免与验证
B13先查再写但没有并发保护，出现丢失更新或重复数据使用唯一约束、原子更新、乐观版本或合适锁；用并发测试验证而非单请求测试
B14事务范围过小，多个写操作出现部分成功根据业务不变量划事务；失败注入验证任一步失败后状态仍一致
B15事务范围过大，包含慢网络调用数据库事务内只做必要数据操作；使用 Outbox、Saga 或补偿处理跨系统一致性
B16重试非幂等写操作，造成重复扣款、订单或消息设计幂等键与结果复用，明确重试边界；服务端不能只依赖按钮禁用
B17外部 HTTP、数据库和队列调用没有超时每一层设置连接、请求和总预算；超时后取消下游工作并记录依赖归因
B18对所有失败立即重试，形成重试风暴只重试瞬时错误，指数退避加抖动，尊重 Retry-After，设置最大次数与熔断
B19缓存 key 漏掉租户、权限、语言或版本把所有影响结果的维度进入 key；建立失效、容量、TTL 和权限变化策略
B20先删缓存再写数据库，或双写没有一致性设计明确 Cache Aside 顺序、延迟双删或事件失效边界；测试故障窗口和旧值回填
B21消息消费者假设消息只到一次且严格有序按至少一次投递设计幂等，使用业务去重键；需要顺序时按实体分区并处理乱序
B22消费消息后先 ack 再完成业务，失败造成永久丢失业务成功或可靠落库后确认；配置死信、最大重试、可观测的人工恢复流程
B23定时任务在多实例同时执行使用租约、分布式锁或幂等任务；锁要有过期、续租、fencing token 和故障测试
B24金额用浮点数，日期默认使用本机时区金额使用最小货币单位或 Decimal；时间存 UTC/Instant，展示时显式使用业务时区
B25Node.js 请求线程执行大 JSON、加密、图片或压缩 CPU 工作测量事件循环延迟；分块、流式处理或移到 Worker/任务服务，并设置输入上限
B26Stream 忽略背压，整文件一次读入内存使用 pipeline 并处理错误与取消；限制并发、文件大小和高水位，观察峰值内存
B27连接、事务、文件句柄或响应体异常时未释放使用结构化资源管理和 finally；故障注入后检查连接池与句柄是否恢复
B28Promise 未 await 或后台任务随请求结束而丢失关键任务进入可靠队列；显式管理 Promise 生命周期并捕获 unhandled rejection
B29进程收到终止信号立即退出，丢失在途请求先停止接流量，再等待有界时间完成请求、消费和日志，最后关闭连接池
B30健康检查只返回进程存活，掩盖依赖或启动状态区分 liveness、readiness 和 startup；readiness 反映是否能安全接流量但避免依赖雪崩

13.9 数据库、Schema 与迁移常见错误​

编号常见错误如何避免与验证
D01只在应用层查重，没有数据库唯一约束数据库约束守住最终不变量，应用层负责友好提示；并发插入验证冲突行为
D02ORM 循环访问关联对象产生 N+1 查询开启查询日志和计数；使用批量加载、join 或 DataLoader，并以真实数据规模测试
D03列表查询无上限、深 offset 分页越来越慢强制最大页大小；大数据使用稳定排序的游标分页并设计匹配索引
D04凭感觉加索引，忽略选择性、写放大和组合顺序用生产相近数据和执行计划验证；监控慢查询与未使用索引，定期复审
D05SELECT * 或一次加载巨大字段显式选择所需列；大文本/二进制拆分或按需加载，测量序列化和网络成本
D06对可空、默认值和空字符串语义处理不一致在 Schema、DTO 和业务规则中统一定义；迁移前分析历史数据分布
D07一次迁移同时加非空列、回填全表并切换代码使用 expand-migrate-contract：先兼容加列，再分批回填、切读写，最后收紧约束
D08删除或重命名字段时假设所有实例同步发布采用向前/向后兼容的多阶段发布；确认旧版本、任务和报表不再读取后再删除
D09大表 DDL、索引或回填没有锁与容量评估在副本或影子环境演练，限制批次与速率，监控锁、复制延迟和回滚条件
D10测试只用 SQLite/内存库，却依赖生产数据库特性关键查询和迁移使用与生产相同的数据库版本做集成测试
D11隔离级别靠默认值，业务却假设串行执行明确脏读、不可重复读、幻读和写冲突需求；选择隔离级别并加入并发测试
D12迁移脚本不可重复、不可观察且没有恢复策略记录进度和版本，设计幂等/断点续跑；高风险变更准备前滚修复或数据恢复方案

13.10 测试代码常见错误​

编号常见错误如何避免与验证
T01测试照着 AI 刚写的实现复制逻辑从需求和公开行为写断言，使用独立样例与参考实现，不把内部算法再抄一遍
T02回归测试没有在旧代码上失败先运行并保存失败证据，再实现修复；否则无法证明测试覆盖了原问题
T03为让测试通过而降低断言、扩大容差或删除用例测试修改与生产修复分开审查，任何放宽都要说明旧断言为何错误
T04只测试 Happy Path根据状态矩阵覆盖边界、非法输入、超时、取消、并发、权限和依赖失败
T05Mock 掉所有真实边界，测试只证明 Mock 配置单测隔离纯逻辑；接口、数据库、序列化和框架集成由契约/集成测试覆盖
T06Snapshot 很大，更新后无人理解差异Snapshot 只保留稳定小结构；关键业务语义使用明确断言，更新时逐项审查
T07异步测试没 await，测试提前结束返回/await Promise，开启未处理 Promise 检测，并确认断言实际执行次数
T08依赖真实时间、随机数和 sleep，产生 flaky test注入时钟与随机源，使用 fake timer 或事件条件等待，不用固定 sleep 猜完成时间
T09测试共享数据库、全局对象或执行顺序每例独立数据与清理，随机顺序和并行运行验证隔离性
T10E2E 依赖 CSS 层级、文案片段或任意超时使用可访问角色、稳定业务标识和条件等待；失败保留截图、Trace、网络与控制台
T11UI 单测通过就认为视觉和可访问性正确补真实浏览器、键盘、屏幕尺寸、主题和视觉回归；必要时使用自动 a11y 扫描
T12覆盖率数字高就认为测试充分用 mutation、故障注入或删除关键逻辑验证测试敏感度；优先覆盖高风险不变量

13.11 工程化、依赖与部署常见错误​

编号常见错误如何避免与验证
O01未确认包管理器和版本就修改 lockfile读取 packageManager、锁文件和 CI 命令；使用仓库既定工具，只提交与依赖变化相关的 diff
O02为一个小问题升级大量依赖先找最小兼容修复；升级单独成任务，阅读迁移说明并运行完整回归
O03引入冷门依赖而不评估维护、许可和供应链比较现有能力与自行实现成本；检查来源、维护、许可证、安装脚本和锁定版本
O04把生成文件、构建产物或 vendored 代码当源文件手改找到生成源和命令；生成后检查可重复性，只在项目明确要求时提交产物
O05假设 macOS 路径大小写、换行和 Shell 行为适用于 CI在 Linux/目标容器构建；检查路径大小写、可执行位、POSIX 兼容与换行
O06环境变量缺失时静默使用危险默认值启动时验证配置；生产关键值 fail fast，区分服务端秘密与可公开前端变量
O07Docker 镜像用 root、复制整个仓库并包含 Secret多阶段构建、最小基础镜像、非 root 用户、.dockerignore 和 Secret mount；扫描最终镜像
O08CI 为了变绿跳过类型、测试、安全或许可门禁修根因；临时例外要有 owner、风险、到期日和跟踪任务，不能永久关闭
O09只验证构建成功，不验证启动与关键流程对产物做 smoke test，启动真实服务并检查健康、静态资源、迁移和核心接口
O10数据库迁移和应用代码同一瞬间假设新 Schema使用兼容迁移与分阶段部署；回滚时确认旧应用仍能读写当前 Schema
O11配置变更没有灰度、Feature Flag 或回滚路径明确 blast radius，先小流量启用，监控技术和业务指标，准备一键停用
O12日志打印完整请求、Cookie、Authorization 和用户数据结构化日志默认脱敏与限长；使用字段 allowlist，控制访问、保留期和导出
O13指标高基数标签使用 userId、URL 全参数或错误全文标签使用有限枚举，详细上下文进入 Trace/日志；监控成本和基数增长
O14自动化脚本使用宽泛删除、未解析变量或不可恢复操作先只读解析精确目标，使用沙箱/临时目录/回收站；删除、覆盖和生产写入需人工确认
O15AI 完成后直接提交或合并，没有人工风险审查先看完整 diff、测试证据和未验证项；权限、迁移、支付、安全与发布保持人工终审

13.12 一套可直接复用的防错 Prompt​

任务开始前可以给 Claude Code 或 Codex：

先不要修改代码。读取项目指令、相关类型、调用方、相近实现和测试，然后输出：
1. 你确认的事实及文件证据；
2. 仍不确定的业务假设；
3. 必须保持的 API、数据、权限和兼容性不变量；
4. 预计修改文件；
5. 成功、空、错、慢、取消、重试、并发和权限状态矩阵；
6. 分阶段实现与验证命令。
未经确认，不新增依赖、不扩大范围、不修改公开契约。

实现完成后再要求一次对抗式自审：

先不要继续修改。请站在代码审查者和故障注入者的角度检查当前 diff：
- 前端：状态一致性、竞态、清理、SSR/Hydration、可访问性、响应式、性能和 XSS；
- 后端：运行时校验、资源授权、幂等、事务、超时、重试、并发和敏感数据；
- 数据：约束、索引、迁移兼容、回滚和租户隔离；
- 测试：新增测试是否能在旧实现失败，是否存在过度 Mock、异步漏 await 或放宽断言；
- 工程：是否有无关文件、依赖/锁文件漂移、危险命令和未验证环境。
每个问题给出文件证据、触发条件和影响；无法证明的内容标记为“待人工核查”，不要猜测。

最后执行分层验证：

  1. 静态层：格式化、类型检查、Lint、依赖与 Secret 扫描。
  2. 行为层：相关单测、契约测试、集成测试和旧代码失败证明。
  3. 运行时层：浏览器关键流程、真实数据库查询计划、接口与部署 smoke test。
  4. 风险层：权限、并发、超时、重试、迁移、回滚和不可逆动作人工复核。
  5. 交付层：完整 diff、命令结果、未运行项、已知风险与恢复方式。
判断 AI 代码是否可以接收的最小标准

不是“代码写得像人”，而是：契约没有被悄悄改变，失败路径可控，验证能证伪实现，diff 没有越界，高风险决策仍由人负责。

十四、团队落地：资产、评测与治理​

14.1 从个人试用到团队基建​

推荐按风险逐步扩展：

  1. 个人阶段：只做可恢复的本地任务，记录成功与失败样本。
  2. 小队阶段：统一 AGENTS.md、验证命令、Skill Review 和权限基线。
  3. 仓库阶段：接入 CI、代码审查、MCP 允许列表和成本观测。
  4. 组织阶段：建立数据政策、审计、采购标准、版本治理和事故响应。

不要先建设几十个没人使用的 Skills。每项资产都应来自真实重复问题，并有负责人、测试样本和淘汰条件。

14.2 团队资产清单​

资产负责人要维护什么失效信号
AGENTS.md / Rules架构、命令、边界、验收Agent 反复误解或内容冲突
Skills触发描述、流程、脚本、参考误触发、输出漂移、依赖过期
Hooks事件、超时、幂等、退出码阻塞开发、循环、静默失败
MCP工具 Schema、权限、审计误调用、数据过量、服务不稳
Eval 集代表任务、评分、历史基线只覆盖简单成功样本
安全策略Secrets、网络、危险动作绕过审批、权限逐步膨胀

14.3 ROI 不只看速度​

ai-dev-metrics.ts
export interface AIDevMetrics {
  taskType: 'feature' | 'bugfix' | 'refactor' | 'test' | 'review';
  leadTimeMinutes: number;
  humanReviewMinutes: number;
  reworkMinutes: number;
  firstPassChecks: boolean;
  escapedDefects: number;
  toolCost: number;
  aiContribution: 'none' | 'assist' | 'agent';
}

至少同时观察：

  • 交付周期、PR 周期和等待时间。
  • 一次通过率、返工、线上缺陷和回滚。
  • 人工 Review 时间与认知负担。
  • 许可、Token、CI、维护 Skills/Hooks 的总成本。
  • 开发者体验和新人上手时间。

按任务类型与复杂度对比基线，避免只挑 AI 成功的案例。代码行数和 Prompt 数量都不是业务价值。

十五、常见反模式与已过时的做法​

反模式/旧说法问题当前实践
“某工具理解仓库最强”能力会随版本、模型和仓库变化用真实任务集评测，不写永久排名
硬编码具体模型做长期路由型号、价格和可用性变化快用能力档位与评测映射，定期复核
把 Rules/Skills 目录当行业统一标准各工具发现路径不同统一内容源，目录做薄适配
只保留 AGENTS.md 就假设 Claude 自动读取当前 Claude Code 不自动读取明确导入/链接，或接受手动加载限制
追逐“隐藏关键词”和冷门快捷键易过时，难迁移，也不能替代验收使用目标、约束、证据和验证闭环
一次把整个仓库塞进上下文噪声、成本与注入面变大从入口和证据开始，按需搜索
让多个 Agent 同时写核心文件冲突与整合可能比串行更慢读任务优先并行，写任务先划文件边界
Hook 每次跑全量测试反馈过慢，容易阻塞 AgentHook 秒级反馈，阶段/CI 做重验证
在主工作区跳过所有审批误操作直接落地且可能不可恢复沙箱 + worktree + 最小权限 + 审查
AI 写的测试天然可信测试可能迎合实现或放宽断言先在旧实现上确认失败，独立审查
只统计“节省了多少编码时间”忽略 Review、返工和缺陷计算端到端交付与总成本
把安全规则只写成 Prompt自然语言不能硬隔离权限、Sandbox、Hook、CI 多层执行
为什么不再提供大量工具专属冷门操作

快捷键、命令、模型名和实验功能变化很快，也可能受版本、平台和账号影响。本文保留稳定的工程方法；需要具体操作时应查 Claude Code 或 Codex 的当前官方文档，并在本机版本验证。

常见面试问题（30 题）​

Q1：你日常如何使用 AI 编程工具？​

答案汇总：我按任务风险选择补全或 Agent，并用“探索—计划—实现—验证—审查”闭环，而不是把需求一次性交给 AI 后直接合并。

  • 小改动在 IDE 内完成；跨文件功能、排障和重构交给 Claude Code 或 Codex。
  • 任务中给现状证据、范围、禁止项和机器可执行验收。
  • 最终检查 diff、测试、截图和风险，稳定经验再沉淀到规则或 Skill。

Q2：如何选择 Claude Code、Codex 或其他工具？​

答案汇总：不按单次演示和排行榜选，而是用同一组真实仓库任务比较成功率、人工成本、安全边界和集成成本。

  • 区分补全、交互 Agent、后台任务和 CI，不要求一个工具覆盖全部场景。
  • Claude Code 与 Codex 都做一轮代表任务，并固定验收与评分人。
  • 再评估数据政策、权限、MCP/Skills 生态、团队现有环境和总成本。

Q3：怎样写一个高质量的编码 Agent Prompt？​

答案汇总：写清目标、现状证据、范围、约束、验收和输出格式，让 Agent 能判断要做什么、不能做什么以及何时完成。

  • Bug 给复现和日志，UI 给设计图和状态，重构给必须保持的不变量。
  • 明确是否允许加依赖、改接口、迁移数据和修改无关文件。
  • 要求 Claude Code 或 Codex 运行验证并给证据，而不是只解释代码。

Q4：为什么要先 Plan 再实现？​

答案汇总：计划把需求误解、依赖遗漏和过大范围提前暴露，修改成本远低于写完后返工。

  • 陌生模块先只读探索入口、调用链、测试和项目规则。
  • 计划要列文件、阶段、风险、回滚和验收，不能只是任务复述。
  • 小任务可简化，但迁移、重构、安全和数据变更应设置人工确认点。

Q5：AGENTS.md 应该写什么？​

答案汇总：写每个任务都需要的稳定项目事实、命令、边界和验证方式，不把临时需求和长教程塞进去。

  • 典型内容是技术栈、目录职责、包管理器、测试命令和禁止操作。
  • 细分规则通过嵌套指令或按路径规则加载，偶发流程放 Skill。
  • 定期删除冲突和过期项；越长不代表遵循越稳定。

Q6：AGENTS.md 能否统一所有 AI 工具的规则？​

答案汇总：它适合作为规则正文的统一入口，但不能保证所有工具都原生自动读取，因此还需要发现层适配。

  • Codex 原生按层级读取 AGENTS.md。
  • 当前 Claude Code 原生读取 CLAUDE.md，可用薄导入或符号链接复用 AGENTS.md。
  • 面试时要区分内容标准与产品发现机制，不能把文件名兼容说成运行时完全统一。

Q7：Rules 和 Skills 有什么区别？​

答案汇总：Rules 是持续或按代码路径生效的约束，Skills 是任务触发时加载的知识与多步骤流程。

  • “使用 pnpm、API 必须鉴权”属于规则。
  • “如何发布、排障、生成文档”属于 Skill。
  • 必须强制执行的动作仍应放权限、Hook 或 CI，不能只靠自然语言。

Q8：为什么 .skills 或 .rules 很难完全统一目录？​

答案汇总：开放规范通常统一包内部格式，各客户端仍保留自己的扫描目录、优先级和扩展字段。

  • Claude Code 常用 .claude/skills/ 和 .claude/rules/。
  • Codex 仓库 Skill 扫描 .agents/skills/，项目指令以 AGENTS.md 层级为主。
  • 更好的目标是统一内容源，用导入、符号链接或生成脚本适配发现路径。

Q9：多工具项目怎样只维护一份 Skill？​

答案汇总：把标准 Skill 放在中立目录，再让 Claude Code 与 Codex 的发现目录链接或生成到同一目标；工具专属差异留在薄包装。

  • 核心使用 Agent Skills 的 SKILL.md、scripts/、references/ 结构。
  • 路径使用仓库内相对链接，CI 验证目标与跨平台检出。
  • 如果 frontmatter 或命令语法不兼容，抽共享参考和脚本，不强求一个入口覆盖所有客户端。

Q10：Skill 应该怎么设计才容易触发？​

答案汇总：名称聚焦任务，description 明确做什么、何时使用和典型用户表达，正文保持短而可执行。

  • 建立应触发、不应触发和边界样本，测试自动发现而非只测手动调用。
  • 长知识拆到 references/，确定性步骤用脚本并返回可检查结果。
  • 避免多个 Skill 使用“帮助开发”这类重叠描述。

Q11：什么时候使用 Subagent？​

答案汇总：在需要独立上下文、大量搜索、专业审查或可并行读任务时使用，简单连续任务不必委派。

  • 委派要给范围、约束、输出格式和证据要求。
  • Subagent 返回摘要和证据，主 Agent 负责整合与最终决策。
  • 额外 Agent 会增加 Token 和协调成本，只有覆盖或关键路径收益足够时使用。

Q12：并行 Agent 为什么容易翻车？​

答案汇总：多个 Agent 各自看不到完整中间状态，若任务依赖强或同时修改共享文件，会产生语义冲突和大量合并成本。

  • 先让每个计划列读写文件与依赖，重叠高则串行。
  • 审查、搜索和独立测试比核心代码并行写更适合。
  • 即使使用 worktree，最终仍要按依赖合并并重新跑集成验证。

Q13：Git worktree 在 AI 开发里解决什么问题？​

答案汇总：它为并行任务提供独立目录和分支，使 Claude Code 或 Codex 不会在同一工作区互相覆盖。

  • 主工作区可保持稳定，每个任务单独查看 diff、测试和提交。
  • 失败实验可以独立丢弃，长任务也不阻塞当前开发。
  • 它不解决方案冲突、忽略文件和依赖安装问题，仍需合理拆分任务。

Q14：权限和沙箱有什么区别？​

答案汇总：权限决定动作是否被允许或需要审批，沙箱限制进程实际能访问的文件和网络边界，两者互补。

  • 审批可防止明显误操作，但人也可能误批。
  • 沙箱能限制 Prompt Injection 或命令错误的最大影响面。
  • 生产凭据和外部写权限默认不提供，按任务最小化临时开放。

Q15：什么时候可以让 Agent 无人值守？​

答案汇总：只有任务边界清晰、环境隔离、权限最小、可自动验收并且失败可恢复时才适合。

  • 使用容器或 worktree，设置超时、预算、网络和凭据限制。
  • 完成报告必须包含测试与未验证项，失败不能自动合并或发布。
  • 数据迁移、生产操作和不可逆删除仍保留人工确认。

Q16：MCP 在编码 Agent 中有什么价值？​

答案汇总：MCP 把 GitHub、设计、工单、浏览器等实时系统以结构化工具接入 Agent，减少复制粘贴和过期上下文。

  • 工具 Schema 要清楚，结果可分页，读写权限分离。
  • 只接任务需要的 Server，避免工具太多导致误选和更大攻击面。
  • 外部内容是不可信数据，不能让它覆盖用户和项目规则。

Q17：Hooks 和 Skills 怎么选？​

答案汇总：需要在固定事件稳定执行的确定性动作选 Hook，需要模型理解和按情境应用的流程选 Skill。

  • 编辑后格式化、拦危险命令和审计适合 Hook。
  • 发布清单、排障手册和代码审查知识适合 Skill。
  • Hook 要幂等、快速、带超时；重型任务交阶段验证或 CI。

Q18：如何让 AI 生成的代码可验证？​

答案汇总：把验收转成测试、类型检查、lint、构建、浏览器操作或截图，并要求 Agent提供实际执行证据。

  • Bug 测试先在旧实现上失败，防止测试迎合实现。
  • UI 同时验证状态、响应式、可访问性和控制台错误。
  • 高风险变更由 CI 或独立 reviewer 复核，不让实现者成为唯一裁判。

Q19：如何避免 AI 用 any 或忽略测试“修好”问题？​

答案汇总：在约束中禁止降低门禁，并审查测试和配置改动；绿色结果必须来自根因修复，而不是隐藏错误。

  • 明确禁止 any、忽略指令、吞异常、删除测试和放宽断言。
  • 如果 Agent 认为门禁本身错误，要求单独举证和审批。
  • 检查 diff 中测试、lint、tsconfig 和 CI 文件是否被不合理修改。

Q20：怎样管理长会话的 Context Rot？​

答案汇总：一个会话保持一个目标，阶段结束总结有效状态后压缩，目标变化时用干净交接开启新会话。

  • 大日志和搜索交独立 Agent，只带回结论与证据。
  • 推翻的假设不要继续留在主上下文反复引用。
  • 稳定规则写回仓库，不能依赖聊天历史永久保存。

Q21：你会如何用 AI 排查一个线上 Bug？​

答案汇总：先保护数据和隐私，再用脱敏日志还原时间线、提出可区分假设，在安全环境复现并补回归测试。

  • Claude Code 或 Codex 只读分析日志与相关版本，不直接连生产写操作。
  • 根据 Trace、变更和输入逐步排除，避免随机试补丁。
  • 修复经过相关测试、回归、灰度和监控验证，并记录失败样本。

Q22：大型重构怎样使用 AI？​

答案汇总：先冻结公开行为和不变量，再按依赖拓扑拆成小迁移，每步可编译、可测试、可回滚。

  • 让 Agent 盘点调用方、类型、配置、数据和测试覆盖。
  • 先补特征测试，禁止顺手升级依赖和统一无关风格。
  • 每阶段单独 Review，集成分支运行全量测试与性能比较。

Q23：前端开发者使用 AI 最容易忽略什么？​

答案汇总：容易只检查 JSX 和默认视觉，忽略状态机、竞态、可访问性、响应式、性能和真实浏览器行为。

  • 要求覆盖 loading、empty、error、cancel、重试和权限状态。
  • 用浏览器检查键盘、焦点、滚动、网络和控制台。
  • 对流式或异步 UI 检查乱序、卸载清理和旧请求覆盖。

Q24：AI 代码审查如何降低噪声？​

答案汇总：限定审查维度和变更范围，要求每项有可定位证据、影响条件和修复建议，无法证明的不当成缺陷。

  • 分安全、正确性、性能和测试独立审查，再统一去重。
  • 使用严重级别和置信度，但不以置信度代替证据。
  • 通过历史误报和漏报样本持续更新审查 Skill 与 Eval。

Q25：如何防止 AI 泄露 Secrets？​

答案汇总：Secrets 不进入 Prompt，敏感路径在权限和沙箱层拒绝读取，日志脱敏，外部上传与网络访问默认受限。

  • .gitignore 不是访问控制，仍需 deny 规则和隔离。
  • MCP 与 Hook 使用短期最小权限凭据，并记录外部调用。
  • 一旦疑似泄露立即撤销凭据、审计范围、通知负责人并复盘门禁。

Q26：从网上安装 Skill 或 MCP Server 怎么评估？​

答案汇总：按软件供应链依赖审查，而不是把它当普通 Markdown 或配置。

  • 核对来源、版本、许可证、脚本、网络、文件和凭据行为。
  • 固定版本，在沙箱用测试仓库运行，更新走代码 Review。
  • 企业维护允许列表、负责人、审计和快速撤销机制。

Q27：如何衡量 AI 辅助开发的 ROI？​

答案汇总：按任务类型比较端到端交付周期、质量、人工注意力和总成本，不看代码行数或主观速度。

  • 指标包括 PR 周期、一次通过率、Review/返工时间、缺陷和回滚。
  • 成本包括许可、Token、CI、配置维护和失败返工。
  • 速度提升但线上缺陷或审查负担上升，不算正向 ROI。

Q28：如何在团队推广 Claude Code 或 Codex？​

答案汇总：从低风险高频场景和自愿试点开始，用真实证据完善规则、Skills 和安全基线，再逐步扩大。

  • 先提供优秀任务模板、示例和办公时间，不强迫统一编辑器。
  • 公开成功和失败样本，建立可复现 Eval，而不是只做演示。
  • 给资产设置负责人和更新周期，避免规则与工具版本漂移。

Q29：怎样避免开发者过度依赖 AI？​

答案汇总：关键设计、风险判断和最终 Review 保持在人，要求开发者能解释改动、验证方法和失败原因。

  • AI 生成后必须读懂调用链和测试，不接受无法解释的代码。
  • 架构、安全和数据决策由人提出约束并签字负责。
  • 定期回顾基础能力与事故，AI 用于放大判断而不是替代判断。

Q30：你认为 AI 辅助开发接下来会怎样演进？​

答案汇总：重点会从单模型能力转向更可靠的环境、上下文、工具、评测和治理，也就是 Agent 的工程运行时。

  • 项目指令、Skills、MCP 和插件会更标准化，但产品发现与权限仍会有差异。
  • 并行和后台任务增加，沙箱、可观察性、预算和可恢复性会成为基础能力。
  • 高价值开发者更像任务设计者和系统审查者，但对架构与代码的理解仍不可替代。

相关链接​

官方参考​