generar-tech-design

技术设计文档生成器（交互式）

目标

生成生产级技术设计文档（TDD）及其配套的架构决策记录（ADR，MADR 格式）——内容详尽，足以指导实际实施；同时具有可追溯性，能够向未来的维护者说明设计依据。这不是一个轻量级草稿生成器。

此技能通过对话进行，而非一次性生成。 切勿一次性生成完整的 TDD。应逐一引导用户做出每项架构决策，提供真实的备选方案及其权衡，询问用户选择哪种方案（或是否另有想法），然后才能撰写反映其实际决策的 ADR。Agent 在未征求用户意见的情况下独自决定并撰写 ADR，意味着此技能未能履行职责。

输入

• PRD.md —— 必需。包含问题、用户、范围和产品层面的验收标准。若缺失，请停止并索要；不要编造 PRD 内容，本技能只负责架构决策。
• Design.md —— 可选但建议提供。若存在，应将其作为数据模型决策的主要输入：界面所暗示的具体数据（折扣字段、状态徽章、筛选器）往往能揭示仅凭 PRD 无法发现的模型需求。若不存在，则继续处理，并在 TECH-DESIGN.md 中注明未提供 Design.md——不要因此阻塞流程。

步骤 0 — 项目类型

在开始任何其他工作之前，先询问用户：这是绿地项目（从零开始）还是棕地项目（已有代码库）？

• 绿地项目： 直接进入下文的工作流——无需协调既有约束。
• 棕地项目： 索要现有仓库／组件的路径，以及任何现有文档（README、CLAUDE.md、之前的 ADR 或技术设计文档）。在做出任何决策前，先阅读这些资料。已有选型并非一张白纸：
  • 如果某个决策领域已由现有代码确定（例如，技术栈已经是 Node.js 和 Postgres），则为该领域撰写 ADR，将其标记为 Estado: Aceptado (heredado)，在 Decision 中记录现有选型，并跳过该领域的访谈——除非用户明确希望重新考虑；若如此，则按常规的新决策处理，但应在 Consequences 中注明这会改变既定选型。
  • 切勿提出与现有仓库实际做法相悖、却不说明这一点的架构决策。如果 PRD 中的新需求与现有架构冲突，应明确向用户指出冲突，而不是擅自解决。

工作流

1. 阅读 PRD.md（必需）、Design.md（如存在），以及——对于棕地项目——步骤 0 中识别出的现有仓库和文档。
2. 根据 assets/decision-areas.md，确定适用于本项目的决策领域（组件／仓库、数据模型、API 契约、各组件的技术栈、状态管理、弹性／错误处理，以及 PRD 强制要求但未列入清单的其他事项）。对于棕地项目，根据步骤 0 标记哪些领域已经确定。
3. 对于每个新的决策领域（尚未由继承的选择确定），逐个执行： a. 说明背景：解释为什么需要作出此决策，并引用 PRD／Design.md 中的相关内容。 b. 提出 2～3 个实际可行的备选方案，并说明具体权衡（不能制造虚假的选择——每个选项都必须真正适用于本项目）。 c. 询问用户选择哪一项，或是否有其他想法。等待用户回答后再继续。 d. 立即使用 assets/adr-template.md 编写 ADR：将所选方案写入 Decision，将其他方案及未选原因写入 Alternatives considered，并在 Consequences 中至少包含所选方案的一项实际权衡，而不只是优点。
4. 记录完所有决策后，针对 PRD 中的每个关键流程推导验收标准，细化程度应高于 PRD 自身的标准。如果某项标准需要主观判断，定稿前先与用户确认。
5. 根据 assets/tech-design-template.md 编写 TECH-DESIGN.md，引用每个 ADR 的编号，包括继承的 ADR。
6. 写入以下文件：
   • 在项目根目录创建 TECH-DESIGN.md。
   • 为每项决策（新决策或继承的决策）各创建一个文件：adrs/0001-{slug}.md、adrs/0002-{slug}.md，依此类推，按记录顺序连续编号。

质量门槛

结束前，静默检查：

• 每个 ADR 都包含 Context、Decision、Consequences，且 Consequences 至少包含一项实际成本或权衡；新决策还必须至少包含一个被否决的备选方案。继承的 ADR（Aceptado (heredado)）无需满足备选方案要求，因为它们记录的是现有方案。
• 任何架构决策都不得与 PRD 的“No alcance”部分或现有棕地代码库相矛盾；如有冲突，必须先向用户说明。
• Design.md（如存在）中每个暗示数据的 UI 元素，都必须有对应的数据模型决策。
• 验收标准必须可验证，不能使用模糊的形容词。
• TECH-DESIGN.md 中的每个新决策都必须得到用户实际回答确认，不能因为跳过提问而由 Agent 擅自决定。

参考资料

• assets/decision-areas.md——需要逐一讨论的决策，以及何时添加清单中未列出的决策。
• assets/adr-template.md——每个 ADR 使用的 MADR-lite 格式，包括继承决策的状态。
• assets/tech-design-template.md——用于汇总并引用 ADR 的 TDD 文档。