16gagent/patterns/best-practices.md

Best Practices — 从实际任务提取

来源: reflections/ + 日常开发经验 每次任务完成后更新 Promotions: 1st→reflection, 2nd→pattern, 3rd→here, 4th→AGENTS.md checklist, 5th→hard rule

---

代码质量

1. 写完即测，不等集成 — 每个模块 run 一次确认输出正确
2. 边界用例覆盖 — 空输入、超大输入、非法输入都要测
3. 零依赖优先 — 核心算法不自带 npm 依赖（例外: better-sqlite3 等已安装的稳定库）
4. CLI + Library 双接口 — node module.js 和 require('./module') 都要能用
5. passthrough 是默认 — 任何操作失败时返回原始输入，不丢数据

架构设计

6. Phase Isolation — 分析/设计/实现三阶段不交叉
7. 先 MVP 再扩展 — 1-3h 出第一个可用版本，验证后扩展
8. 策略可插拔 — 用分发模式，新增策略不碰核心逻辑
9. 降级路径明确 — 每个操作至少 2 条降级路径
10. 配置可覆盖 — 全局默认 → 项目覆盖 → 运行时参数

调试与排查

11. FK 约束用 ON CONFLICT DO UPDATE — SQLite 的 REPLACE = DELETE+INSERT
12. 检测需多重信号 — 启发式规则必须 2+ 个信号同时匹配
13. WAL 模式开 — 多进程读不阻塞写
14. 大文件分批处理 — 每 250 文件回收一次 WASM/内存
15. stderr 和 stdout 分离 — 元数据用 stderr，数据用 stdout

JavaScript / TypeScript 陷阱

16. || vs ?? — 用 ?? 处理数字 0 — value || default 把 0/''/false 当 falsy。数字类用 value ?? default。已犯 2 次（Agent Evolution FK索引 + Cross-Agent Certification 评分排序）
17. 模板字面量反引号 — 模板内嵌反引号用 ` 转义或改用字符串拼接。不输出裸反引号到生成代码
18. 类型单数化 — entity 复数→单数（Albums→Album, Pets→Pet），但不碰 status/bus 等不可变词根

Generator / Builder 陷阱

19. Next.js 路径：app/ 不是 src/app/ — Next.js App Router 默认 pages in app/。生成器必须输出到 app/ 目录
20. DDL CONSTRAINT 泄露 — schema.ts 生成时 PRIMARY KEY / FOREIGN KEY / CONSTRAINT 行不能被解析为 TS interface 字段
21. CreateInput 完整性 — generateTypes 必须包含所有实体（包括 User）→ CreateUserInput 不能缺失
22. JSX 三元嵌套 — {a ? {b} : {c}} 错误。改为 {a ? b : c} 或 {a ? (<Comp />) : null}

Agent 编排

23. 子 agent 并行分析 — 3 个项目同时 spawn，2-3 分钟完成
24. 子 agent 用 Pro 模型 — 代码/方案决策用 DeepSeek V4 Pro
25. 任务描述要包含完整输出路径 — 子 agent 不需要父 agent 上下文也能工作
26. 用 sessions_yield 等完成 — 不 poll loop

CI / Release

27. Exit code 规范 — PASS/WARN→0, FAIL→1。不要 PASS 也 exit 1
28. 向后兼容 — 新增参数用 optional，不改既有函数签名。所有 PR 遵守零修改约束

记忆管理

29. 每完成一个 Phase 写 daily — 不等到全部做完
30. 提取模式后立即写 patterns/ — "mental notes 不存活"
31. MEMORY.md 尽量不动 — 在缓存线以上，每次改动全缓存爆炸
32. Reflection 必须结构化 — 含 Pattern Class + Future Trigger + Checklist，禁止"以后注意"