Spec

一句话区别 ADR（Architecture Decision Record，架构决策记录）回答 「为什么这么定」——记录一个决策和它的理由，拍板后基本不动。 Task Spec（任务规格）回答 「要做什么、怎么做、做到什么算完」——指导一次具体落地，随实施更新，是活文档。 一个朝后看（沉淀已做的决策），一个朝前看（驱动待做的执行）。 ADR 是什么 ADR 记录一个「架构上重要」的决策：背景、考虑过的方案、最终选择、以及由此带来的后果。它的价值在于把「当初为什么选 A 而不是 B」留存下来，避免几个月后自己或他人重新踩坑、甚至无意推翻。 典型结构（Michael Nygard 的经典五段）： # ADR-0001: 标题 ## 状态 Accepted / Proposed / Superseded ## 背景 什么力量/约束逼出了这个决策 ## 决策 我们选了什么 ## 后果 接受了哪些代价、带来哪些影响 关键特性： 不可变：决策变了不要改旧文件，而是新写一条 ADR，引用并标记旧的为 superseded。删除会抹掉历史，正是它要避免的。 短小：通常 200–500 字，只讲决策本身，不写实现细节。 进版本库：和代码放一起（常见 docs/adr/），让「为什么」就在工程师能找到的地方。 Task Spec 是什么 Task Spec 描述一个待完成任务的规格：目标、范围（含「不做什么」）、接口/行为契约、约束、验收标准。它是给「这次要做的事」立一个清晰的「完成」定义，让人和 AI 都按同一份契约推进。 ## 目标 实现用户登录 API ## 范围 - 包含：POST /api/login、JWT 签发 - 不包含：注册、OAuth ## 约束 - 密码不得明文记录 ## 验收 - [ ] 正确凭证返回 JWT - [ ] 错误凭证返回 401 关键特性： ...