# 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，禁止"以后注意"