dev-docs

Dev Docs — 项目文档记录规范

开发期维护项目文档时按本规范执行。极简项目（单文件/无依赖）不建文档体系；有文档体系的项目按本规范执行。

文档分层

docs/需求文档.md          需求（唯一意图真相源）：项目定位、功能清单、范围边界、验收标准
.easymint/todos.json      用户待办（唯一清单源）：想法/计划，UI「待办」面板或 todo_user 工具维护
docs/开发记录.md          导航页（唯一真相源）：头部「当前进度快照」+「开发记录索引」
docs/开发记录/<日期>.md   按日期分文件的进度明细（只增不改，带提交 hash）
CHANGELOG.md              正式发布日志（Keep a Changelog，只记用户可见变更）
docs/技术架构.md          架构设计（只追加，记录技术选型与关键决策）

分工：需求文档管「要做什么」，用户待办管「想做还没做的」，导航页管「现在在哪」，明细管「每天发生了什么」，CHANGELOG 管「发布了什么」，技术架构管「系统怎么设计」——各载体不重复记录同一内容。

接手/恢复工作时按序核实：开发记录快照（现在在哪）→ 需求文档（要做什么）→ 技术架构（怎么设计）→ task.json + git log/diff（任务真实进度，不盲信 status）。

docs/需求文档.md（需求文档）

产品需求的唯一意图真相源——「要做什么、为什么做、怎么算做完」，与进度类文档分离：

• 记录内容：
  • 项目定位与目标（一句话 + 面向谁）
  • 功能清单（按 P0 必需 / P1 核心 / P2 增强 标注优先级）
  • 范围边界（明确不做什么，防蔓延）
  • 验收标准（Evaluator 对照检查的依据，每条功能对应可验证的完成定义）
• 更新时机：需求变更时先同步需求文档，再拆任务——用户新增/修改需求 → 先更新需求文档反映最新意图 → 再拆 task.json（需求变更不更新文档直接拆任务，会导致 Builder 按过期意图开发）
• 与 task.json 分工：需求文档管「全部意图」，task.json 管「当前批次任务的执行状态」——任务完成后需求文档保留（产品全貌），task.json 是执行快照
• 简单档项目可精简（定位 + 功能清单即可），极简项目不建（见文档分层开头）

.easymint/todos.json（用户待办清单）

用户想法/计划的唯一清单源（跨会话、人机共写）——有想法、发现改进点但不立刻做时记录于此，避免靠记忆或散落对话丢失。UI 入口：输入卡片「待办」按钮面板（用户增删改查）；文件结构：

{ "updatedAt": 0, "todos": [ { "id": 1, "title": "标题（≤200 字）", "note": "补充说明（可空）", "status": "open" | "done", "createdAt": 0, "doneAt": null } ] }

Mint 侧规则（统一走 todo_user 工具，不裸写文件——结构/校验/面板广播由工具保证，本文件不再贴格式细节）：

• 新增：todo_user add——用户让「记一下/记个想法」、会话中出现「以后/之后要做 xx」的未落任务事项时记入；工具自管 id 递增，title ≤200 字符
• 完成：todo_user toggle（先 list 找到 id）——勾选完成或重新打开；面板与工具共用同一清单，随时同步
• 禁止全量替换/批量删除——清单属用户（面板可能正打开编辑）；仅用户明确点名的条目才 remove/update
• 与开发记录分工：用户待办管「想做还没做的」，开发记录管「已发生的」——新想法先落待办，动手做之后才进开发记录
• 清单为空时不建文件也行（面板/首次写入时自动创建）；不要把它当正式任务——正式任务进 task.json

docs/开发记录.md（导航页）

本文件是项目进度与交接的唯一真相源，会话交接时更新。两部分：

头部「当前进度快照」

记录当前状态，每次会话交接时更新（本区可改）：

### 当前版本
- **vX.Y.Z**（日期发布：一句话变更摘要）

### 最近工作
**日期 变更主题**（详见 docs/开发记录/<日期>.md）：
- 本次变更要点（2-4 条，可追溯明细）

### 接下来安排
1. 未完成的待办（按优先级）