AI 效能工具最佳实践

基于实际使用经验总结的 AI 辅助开发效能提升指南，持续迭代中。

---

1. 会话独立与连接

每个会话保持独立，同时通过机制建立连接。

Do ✅	Don't ❌
单次会话聚焦一个主题，避免上下文污染	在一个会话中频繁切换无关话题
通过 Memory 文件在会话间传递关键信息	依赖聊天历史作为持久记忆
使用 CLAUDE.md 或项目级配置固化项目上下文	每次会话从头解释项目背景
一个任务完成后开启新会话，保持上下文清爽	长会话积累无关历史，稀释注意力
Memory 中记录 Why 和 How to apply	只记结论不记原因，后续无法复用

核心思想：会话如函数 —— 单一职责，通过持久化状态（Memory）解耦。会话是短命的，Memory 是长命的。

实践举例

❌ 错误：一个会话里先问 API 设计，再问部署脚本，再问代码审查
✅ 正确：会话 A 搞定 API 设计 → Memory 记录设计决策 → 会话 B 基于 Memory 写代码

---

2. 提示词保持精简

少即是多，精准描述需求。

Do ✅	Don't ❌
说清楚「做什么」和「为什么」，不纠结「怎么做」	写出 200 字的步骤清单（那是 AI 该做的）
一次一个明确目标，完成后再推进下一步	一句话塞入 3 个需求，结果哪个都没做好
善用已有文档引用（参考 xxx.md）	每次把相同上下文重新打一遍
用「结果长什么样」来约束输出格式	用「你必须按以下 15 步执行」来约束过程

核心思想：把 AI 当 senior developer 沟通 —— 说目标和约束，让它自己规划路径。好的 prompt 是指南针，不是导航仪。

实践举例

❌ 冗长：帮我写一个函数，先用 fetch 请求 /api/users，然后遍历返回的 JSON 数组，
   提取 name 和 email 字段，按 name 排序，过滤掉没有 email 的项，最后渲染成表格...

✅ 精简：写一个用户表格组件，数据从 /api/users 获取，只展示有邮箱的用户，按姓名排序。

---

3. 文档细腻度拆分

大文档拆小，按需加载。上下文窗口有限，按需检索远胜全量加载。

Do ✅	Don't ❌
一个文件一个主题（api-conventions.md）	单体 README.md 塞入所有规范
Memory 一个文件一条事实，方便精准检索	一个 Memory 文件记 10 条不相关的事
用 MEMORY.md 做索引，文件名即摘要	无索引，全靠 AI 自己搜
文档之间通过 [[link]] 互相引用	重复内容出现在多个文档中

核心思想：文档如微服务 —— 高内聚低耦合，按需检索组装。AI 不需要读完你的所有文档，只需要在最合适的时机读到最相关的那个。

实践举例

❌ 粗放：PROJECT_DOCS.md（8000 行，涵盖架构、API、部署、测试...）
✅ 细腻：
   ├── architecture.md       （架构决策）
   ├── api-conventions.md    （API 设计规范）
   ├── error-handling.md     （错误处理约定）
   ├── testing-strategy.md   （测试策略）
   └── MEMORY.md             （索引：每个文件的摘要 + 链接）

---

4. Skills 数量控制在 12 个以内

少而精，聚焦高频场景。Skill 越多，触发歧义越大，维护成本越高。

Do ✅	Don't ❌
每个 Skill 覆盖一类明确的高频任务	为一次性任务创建 Skill
优先封装重复性操作（review / deploy / test）	Skill 功能重叠（两个 Skill 都能触发同一需求）
定期清理不再使用的 Skill	只增不减，最终臃肿失控
Skill 内部保持简单，复杂逻辑交给 AI 即时判断	Skill 写成几百行的 SOP 文档

核心思想：Skill 是快捷键，不是菜单。Ctrl+C 人人用，Ctrl+Shift+Alt+F12 没人按。

推荐的高频 Skill 清单

优先级	Skill	触发场景
P0	code-review	每次提交前
P0	init	新项目初始化
P1	deploy / run	运行和部署
P1	test / verify	验证变更
P2	security-review	安全敏感变更
P2	simplify / refactor	代码优化

---

5. 独立并行任务使用子代理

能并行的不串行，能委托的不自己干。主会话保持决策视角。

Do ✅	Don't ❌
多文件搜索、多维度审查同时启动子代理	一个文件一个文件顺序读
子代理只返回结论和数据，主会话做决策	子代理做决策（它缺少全局上下文）
独立的验证、调研任务并行扇出	有依赖关系的任务强行并行
任务描述写清楚期望产出格式	给子代理模糊指令，返回一堆无用内容

核心思想：主会话 = 大脑（决策），子代理 = 手（执行）。大脑的价值是判断，不是搬运。

并行 vs 串行 决策树

这个任务能不能拆成互不依赖的子任务？
├── 是 → 用子代理并行执行 → 主会话汇总决策
└── 否 → 主会话直接执行，保持上下文连贯

典型并行场景

✅ 代码审查：正确性 / 安全性 / 性能 / 可维护性 → 4 个子代理并行
✅ 调研任务：搜文档 / 搜代码 / 搜 issue → 3 个方向并行
❌ 不适合：先设计 Schema → 再写 API → 再写前端（有顺序依赖）

---

6. 奖罚分明，形成长期记忆

正确行为强化，错误行为纠正。沉默接受 = 默许重复。

Do ✅	Don't ❌
输出符合预期 → 明确说「这个方向是对的，记住」	满意但沉默，AI 不知道这次对了
输出偏离预期 → 指出问题 + 记录到 Memory	不满意但凑合用，同样的问题下次重现
Memory 记录附带 Why 和 How to apply	只写「不要用 X」，不解释原因
同类反馈更新已有 Memory，保持信息收敛	散落在多个 Memory 文件中互相矛盾

核心思想：Memory 是 AI 的「肌肉记忆」—— 每次反馈都是一次训练。不反馈 = 不训练 = 永远停留在默认水平。

反馈模板

---
name: prefer-foo-over-bar
description: 项目统一使用 foo 方案处理认证
metadata:
  type: feedback
---

认证逻辑统一使用 foo 方案，不要用 bar。

**Why:** foo 更契合我们现有的 JWT 体系，bar 引入了不必要的 session 依赖。
**How to apply:** 任何涉及认证的新功能，默认选择 foo。看到 bar 时主动建议迁移。

---

7. 先规划后执行

复杂任务先确认方案，再动手写代码。写代码是最后的 20%。

Do ✅	Don't ❌
涉及 3+ 文件或架构决策时，先进入 Plan Mode	拿到需求直接写代码
方案中明确：改哪些文件、数据流、边界情况	边写边想，写完发现方向错了
方案经用户确认后一气呵成	写一半发现理解有误，推倒重来

核心思想：慢就是快。 花 5 分钟对齐方案，省下 30 分钟返工。

---

8. 验证闭环

每次变更必须有可观测的验证结果。不盲写，不猜测。

Do ✅	Don't ❌
代码变更后立即运行、测试、review	写完说「应该没问题」就结束
用 /verify 或 run skill 端到端验证	只跑单元测试，不验证实际行为
验证失败 → 修复 → 再验证，形成闭环	验证失败 → 换个思路重写 → 不验证第二版

核心思想：没有观测的变更等于没有变更。 代码的实际行为才是真相。

---

9. 上下文预算意识

Token 是有限资源，精打细算。上下文越长，AI 注意力越稀释。

Do ✅	Don't ❌
长会话中及时开启新会话重置上下文	一个会话从早聊到晚
不需要的文件不读，读了不用的信息是噪音	把整个项目文件全部读一遍
用 Grep / Glob 精准定位，而非打开文件浏览	为了找一行代码打开 5000 行的文件
关键结论写入 Memory，下次不用重读	每次都重新翻代码确认相同的事情

核心思想：上下文是 AI 的工作记忆，不是硬盘。 放进去的每一条信息都在消耗注意力。

---

10. 渐进式交付

小步快跑，每步验证。一口吃不成胖子。

Do ✅	Don't ❌
大需求拆成独立可交付的小任务	一次要求实现完整功能模块
第一步交付 MVP → 反馈 → 迭代	追求一步到位，结果方向偏了全白做
每个小任务结束时有可展示的结果	做了很多但中间没有任何可见产出

核心思想：交付是迭代出来的，不是一次性造出来的。 每次只前进一步，但每一步都踩实。

---

总结矩阵

#	原则	一句话	反模式	关键词
1	会话独立	一个会话一件事，Memory 串联	把聊天记录当持久记忆	解耦
2	提示精简	说目标，不说步骤	200 字操作清单	指南针
3	文档细拆	一个文件一个主题，按需加载	8000 行单体文档	微服务
4	Skill 精炼	≤12 个，只覆盖高频场景	为一次性任务创建 Skill	快捷键
5	子代理并行	独立任务委托执行，主会话决策	主会话陷入文件搬运	大脑+手
6	奖罚分明	好就记住，错就纠正	沉默接受不满意结果	训练
7	先规划后执行	方案确认再动手，慢就是快	边写边想，推倒重来	对齐
8	验证闭环	每次变更必须可观测验证	写完不管，猜测运行	真相
9	上下文预算	Token 有限，精打细算	无节制读文件，会话无限长	注意力
10	渐进交付	小步快跑，每步踩实	一步到位，方向全偏	迭代

---

原则速记卡

📌 会话 = 函数   │  短命会话 + 长命 Memory
📌 提示 = 指南针 │  说目标，AI 找路
📌 文档 = 微服务 │  拆细、索引、按需检索
📌 Skill = 快捷键│  ≤12 个，高频优先
📌 子代理 = 手   │  并行执行，大脑决策
📌 反馈 = 训练   │  不反馈 = 不进步
📌 规划 = 对齐   │  5 分钟方案 > 30 分钟返工
📌 验证 = 真相   │  代码行为是唯一标准
📌 上下文 = 注意力│  放进去的都是成本
📌 交付 = 迭代   │  小步走，步步实