大海
64 lines
3.3 KiB
Markdown
64 lines
3.3 KiB
Markdown
# 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，禁止"以后注意"
|