和 AI 一起写代码：五条心智 + Review 四维

用 AI 写代码时先想清楚问题与基础，再谈权衡与沟通；Review 时盯边界、异常、性能与安全，避免「能跑就算完」。

和 AI 一起写代码

AI 很会「往前冲」：补全快、脚手架全、看起来也很像成品。真正容易翻车的，往往不是语法，而是问题没找准、基础没对齐、权衡没说清、沟通含糊、缺少系统视角。

这篇备忘录分两块：

五条心智 — 动手前先过一遍
Review 四维 — 边界 / 异常 / 性能 / 安全，合代码前再过一遍

可和 AI 代码 Review 的三个时机、开发规范链一起用。

一、五条心智

1. 理解真正要解决的问题

先问「用户 / 业务到底卡在哪」，再问「要不要写代码」。

现象 ≠ 根因：报错、慢、点不动，可能只是表象；先复现、再定位、最后才改。
可验收：成功长什么样？失败怎么暴露？明确非目标（这次不做啥）。
约束写清楚：环境、兼容、权限、截止时间、能否动库表 / API。
给 AI 的输入：背景 + 目标 + 约束 + 相关文件路径；少说「帮我优化一下」这种空话。

提示词里若说不清「真正要解决的问题」，模型只会优化它以为的问题。

2. 掌握基础知识

AI 不能替你承担「懂不懂」的责任。基础越扎实，越能鉴别胡说。

语言与运行时：异步、类型、错误传播、模块边界。
框架约定：Nuxt / Vue 的生命周期、SSR / CSR、数据获取与缓存。
协议与数据：HTTP 状态、鉴权、幂等、一致性；别只会调 SDK。
读得懂 diff：说不出「这段为什么这样写」，就不要合。

没有基础时，AI 输出看起来「高级」，实际可能是过时 API、错误抽象或安全漏洞包装成最佳实践。

3. 做出权衡

工程没有唯一正解，只有在约束下的取舍。让 AI 给方案时，逼它说出代价。

维度	常见张力
速度 vs 正确	先上线再修，还是门禁先过？
简单 vs 扩展	多一个配置项，还是先写死再抽？
一致 vs 特例	跟现有模式走，还是这次破例？
性能 vs 复杂度	缓存 / 预计算值不值得多一层？

写进 PR / 对话里：选了什么、没选什么、为什么。权衡说不清的改动，Review 成本会指数上升。

4. 交流沟通

人和 AI、人和人，吃的都是同一套沟通质量。

对人：意图、范围、风险、验证步骤写在 PR Summary / Test plan 里。
对 AI：分步、可贴上下文、指出「不要改哪些文件」；一次一事，少塞整仓愿景。
反馈闭环：哪里不对，标具体文件与期望行为，避免「感觉不太对再改改」。
术语对齐：同一概念不要混用三套名字（尤其鉴权、缓存、环境）。

沟通越清晰，返工越少；含糊的一句「再优化」，往往换来另一坨无关重构。

5. 系统思维

改一处，要想整条链路。

上下游：谁调用、谁依赖、失败谁兜底。
状态与时间：并发、重试、幂等、过期、时钟。
观测：日志、指标、告警；坏了能不能看见。
回滚：合并后如何撤；配置能否快速关掉。
一致性：本地 / CI / 预发 / 生产是否同一套假设。

AI 擅长局部最优；系统债往往出在「局部都对、拼起来不对」。

二、Review 四维

自动 Review 和人工 Review，都可以按这四维扫。不是每条必改，但该想过却没想过就要标出来。

1. 边界（Boundary）

输入、状态、环境的「边上」会不会炸。

空值、空数组、超长字符串、非法枚举
分页极限：第 0 页、最后一页、总数为 0
权限边界：未登录、越权、过期 token
配置缺失：环境变量没配时是失败还是静默错误行为
兼容边界：旧客户端、旧数据形态、灰度开关关/开

自问： 最小输入、最大输入、错误输入，三条路径都有明确行为吗？

2. 异常（Exception）

失败是常态，要设计「坏掉时的样子」。

错误是否分类：可重试 / 不可重试 / 用户可修复
是否吞异常：catch 空、返回假成功、只 console.log
用户是否看得到可理解提示（别只剩 500）
下游超时、限流、部分失败怎么处理
事务 / 多步写入：中途失败是否留下脏数据

自问： 这条路径失败时，系统停在哪、用户看到什么、日志里有没有线索？

3. 性能（Performance）

先找「会不会在真实数据量下变慢」，再谈微优化。

N+1 查询、循环里请求、无分页的大列表
热点路径是否多余 await、重复计算、同步堵事件循环
缓存：键、失效、穿透；别缓存不该缓存的私有数据
前端：大包、阻塞渲染、无虚拟列表的超长列表
流式 / 大文件：内存是否被整包拖垮

自问： 数据乘 100、并发乘 10，哪里先塌？有没有测量而不只是感觉？

4. 安全（Security）

默认不信任输入，也不信任「看起来像内部」的调用。

注入：SQL / NoSQL / 命令 / 模板 / 富文本 XSS
鉴权与授权：能看 ≠ 能改；IDOR、水平越权
密钥与会话：硬编码、日志泄露、弱会话密钥、Preview 密钥进生产
SSRF、开放重定向、不安全反序列化
依赖与供应链：来历不明的脚本、过宽的 CORS、多余的公开接口

自问： 攻击者只改一个参数，能读到或改到不该碰的数据吗？

三、怎么用在日常

接到需求
  → 五条心智过一遍（问题 / 基础 / 权衡 / 沟通 / 系统）
  → 让 AI 出方案或补丁
  → 自己读 diff
  → Review 四维扫一遍（边界 / 异常 / 性能 / 安全）
  → CI +（可选）PR 自动 Review
  → 人工确认意图与 Test plan 后再合

给 AI 的短清单（可直接贴进对话）：

请先确认：真正要解决的问题、约束与非目标。
方案需写明权衡（选了什么 / 放弃了什么）。
改动请说明上下游影响与回滚方式。
自检：边界、异常、性能、安全各至少想一条。
不要无关重构；信息不足先问，不要猜。

四、把约束写进仓库：`AGENTS.md`

心智和 Review 清单只有写进仓库，Agent 才会稳定遵守。根目录 AGENTS.md 就是给编码 Agent 的操作手册（命令、约定、禁止事项、目录地图），和给人看的 README / 详细架构 CLAUDE.md 分工不同。

本仓库已有根级 AGENTS.md：强调先读再写、先复用再新增、最小改动，避免另起一套平行实现。

写 / 改 AGENTS.md 时，可参考 GitHub 对 2500+ 仓库的归纳：命令要可执行、边界要写清、堆栈要具体、少写空泛口号。

→ How to write a great agents.md: Lessons from over 2,500 repositories