generar-tech-design

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Technical Design Document Generator (Interactive)

Technical Design Document Generator (交互式)

Goal

目标

Produce a production-grade Technical Design Document (TDD) and its supporting Architecture Decision Records (ADRs, MADR format) — thorough enough to guide real implementation and traceable enough to justify itself to a future maintainer. This is not a light draft generator.

This skill is conversational, not one-shot. Never generate the full TDD in a single pass. Walk the user through each architecture decision one at a time, present real alternatives with trade-offs, ask which one they choose (or if they have a different idea), and only then write the ADR reflecting their actual decision. An ADR the agent decided alone, without the user's input, is a failure of this skill.

生成生产级别的技术设计文档（TDD）及其配套的架构决策记录（ADRs，采用MADR格式）——内容详尽到足以指导实际开发，且可追溯性强，能向未来的维护者说明决策依据。这并非轻量级草稿生成工具。

本技能为对话式，而非一次性生成。 绝不要一次性生成完整的TDD。需逐个引导用户完成每个架构决策，提供带有实际权衡的真实备选方案，询问用户的选择（或是否有其他想法），之后再撰写反映用户实际决策的ADR。若Agent未获取用户输入就自行决定ADR内容，则视为本技能使用失败。

Input

输入

```
PRD.md
```
— required. Problem, users, scope, product-level acceptance criteria. If missing, stop and ask for it — do not fabricate PRD content, only architecture decisions belong to this skill.
```
Design.md
```
— optional but desirable. If present, use it as a primary input for data model decisions: the concrete data the interface implies (a discount field, a status badge, a filter) often reveals model requirements the PRD alone doesn't. If absent, proceed without it and note in
```
TECH-DESIGN.md
```
that no Design.md was available — do not block on it.

```
PRD.md
```
—— 必填。包含问题、用户群体、范围、产品级验收标准。若缺失，需停止操作并向用户索要——不得编造PRD内容，本技能仅负责架构决策相关内容。
```
Design.md
```
—— 可选但推荐提供。若存在，将其作为数据模型决策的主要输入：界面所隐含的具体数据（如折扣字段、状态标识、筛选器）往往能揭示PRD未提及的模型需求。若不存在，可继续操作，并在
```
TECH-DESIGN.md
```
中注明未获取到Design.md——无需因缺失此文件而停滞。

Step 0 — Project type

步骤0 —— 项目类型

Before anything else, ask the user: is this greenfield (from scratch) or brownfield (existing codebase)?

Greenfield: proceed directly to the Workflow below — no prior constraints to reconcile.
Brownfield: ask for the path(s) to the existing repo(s)/components and any existing documentation (
```
README
```
,
```
CLAUDE.md
```
, prior ADRs or tech design docs). Read them before making any decision. Existing choices are not blank slates:
- If a decision area is already settled by the existing code (e.g., the stack is already Node.js and Postgres), write its ADR with
```
Estado: Aceptado (heredado)
```
  , documenting the existing choice as the Decision and skipping the interview for that area — unless the user explicitly wants to reconsider it, in which case treat it as a normal new decision but note in Consequences that it changes an established choice.
- Never propose an architecture decision that silently contradicts what the existing repo(s) already do. If a new requirement from the PRD conflicts with the existing architecture, surface the conflict to the user explicitly instead of resolving it unilaterally.

在开始任何操作前，询问用户：这是greenfield（从零开始的新项目）还是brownfield（基于现有代码库的遗留项目）？

Greenfield：直接进入下方工作流——无需协调任何前置约束。
Brownfield：索要现有仓库/组件的路径，以及任何现有文档（
```
README
```
、
```
CLAUDE.md
```
、过往ADRs或技术设计文档）。在做出任何决策前需阅读这些内容。现有选择并非空白 slate：
- 若某决策领域已由现有代码确定（如技术栈已采用Node.js和Postgres），则撰写对应的ADR并标记
```
Estado: Aceptado (heredado)
```
  ，将现有选择记录为决策内容，跳过该领域的访谈——除非用户明确要求重新考量，此时需将其视为正常新决策处理，但需在“后果”部分注明该决策会变更已确立的选择。
- 绝不要提出与现有仓库内容暗中矛盾的架构决策。若PRD中的新需求与现有架构冲突，需明确向用户指出该冲突，而非单方面解决。

Workflow

工作流

Read
```
PRD.md
```
(required),
```
Design.md
```
(if present), and — for brownfield — the existing repo(s) and docs identified in Step 0.
Determine the decision areas that apply to this project from
```
assets/decision-areas.md
```
(components/repos, data model, API contracts, tech stack per component, state management, resilience/error handling, plus anything the PRD forces that isn't on that list). For brownfield projects, mark which areas are already settled per Step 0.
For each new decision area (not already settled by an inherited choice), one at a time: a. State the context: why this decision is needed, quoting what the PRD/Design.md implies. b. Present 2-3 real alternatives with concrete trade-offs (not a false choice — each option must be genuinely viable for this project). c. Ask the user which one they choose, or whether they have a different option in mind. Wait for the answer before continuing. d. Write the ADR immediately using
```
assets/adr-template.md
```
: the chosen option as Decision, the others as Alternatives considered (with the reason they were not chosen), and Consequences that include at least one real trade-off of the choice made, not only benefits.
After all decisions are recorded, derive acceptance criteria per key flow in the PRD, at a more granular level than the PRD's own criteria. Confirm with the user before finalizing if any criterion required a judgment call.
Assemble
```
TECH-DESIGN.md
```
from
```
assets/tech-design-template.md
```
, referencing every ADR by number, including inherited ones.
Write to disk:
- ```
TECH-DESIGN.md
```
  at the project root.
- ```
adrs/0001-{slug}.md
```
  ,
```
adrs/0002-{slug}.md
```
  , ... one file per decision (new or inherited), numbered sequentially in the order they were recorded.

阅读
```
PRD.md
```
（必填）、
```
Design.md
```
（若存在），以及——针对brownfield项目——步骤0中确定的现有仓库和文档。
从
```
assets/decision-areas.md
```
中确定适用于本项目的决策领域（组件/仓库、数据模型、API契约、各组件的技术栈、状态管理、容错/错误处理，以及PRD要求的任何未列在其中的内容）。对于brownfield项目，标记哪些领域已按步骤0的要求确定。
针对每个新决策领域（未由继承的选择确定），逐个处理： a. 说明背景：为何需要做出此决策，引用PRD/Design.md中的隐含内容。 b. 提供2-3个真实备选方案，并说明具体的权衡（不得为虚假选择——每个选项必须对本项目真正可行）。 c. 询问用户选择哪个选项，或是否有其他想法。需等待用户回复后再继续。 d. 立即使用
```
assets/adr-template.md
```
撰写ADR：将所选选项作为决策内容，其他选项作为“考虑过的备选方案”（说明未被选择的原因），“后果”部分需至少包含所选决策的一个实际权衡，而非仅提及收益。
记录所有决策后，基于PRD中的关键流程推导验收标准，粒度需比PRD自身的标准更细致。若某条标准需要主观判断，需与用户确认后再定稿。
从
```
assets/tech-design-template.md
```
组装
```
TECH-DESIGN.md
```
，按编号引用所有ADRs（包括继承的ADRs）。
写入磁盘：
- 在项目根目录生成
```
TECH-DESIGN.md
```
  。
- 在
```
adrs/
```
  目录下生成
```
0001-{slug}.md
```
  、
```
0002-{slug}.md
```
  ……每个决策（新决策或继承决策）对应一个文件，按记录顺序依次编号。

Quality Gate

质量检查

Before closing, silently check:

Every ADR has Context, Decision, Consequences with at least one real cost or trade-off, and — for new decisions — at least one rejected Alternative. Inherited ADRs (
```
Aceptado (heredado)
```
) are exempt from the alternatives requirement, since they document what already exists.
No architecture decision contradicts the PRD's "No alcance" section, or the existing brownfield codebase, without that conflict being surfaced to the user first.
Every UI element in
```
Design.md
```
(when available) that implies data has a corresponding data model decision.
Acceptance criteria are verifiable, not vague adjectives.
Every new decision in
```
TECH-DESIGN.md
```
was actually answered by the user — not filled in solo by the agent because a question was skipped.

结束前，需静默检查以下内容：

每个ADR都包含背景、决策、后果（至少包含一个实际成本或权衡），且——针对新决策——至少包含一个被否决的备选方案。继承的ADRs（标记为
```
Aceptado (heredado)
```
）无需满足备选方案要求，因为它们记录的是已存在的内容。
任何架构决策均未与PRD的“No alcance”（范围外）部分或现有brownfield代码库矛盾，除非已事先向用户指出该冲突。
若存在
```
Design.md
```
，其中每个隐含数据的UI元素都有对应的 data model决策。
验收标准可验证，而非模糊的形容词。
```
TECH-DESIGN.md
```
中的每个新决策均已得到用户答复——不得因跳过问题而由Agent自行填充内容。

References

参考资料

```
assets/decision-areas.md
```
— which decisions to walk through, and when to add ones not listed.
```
assets/adr-template.md
```
— MADR-lite format for each ADR, including the inherited-decision state.
```
assets/tech-design-template.md
```
— the TDD document that assembles and references the ADRs.

```
assets/decision-areas.md
```
—— 需完成哪些决策，以及何时添加未列出的决策。
```
assets/adr-template.md
```
—— 每个ADR采用的MADR-lite格式，包括继承决策的状态标记。
```
assets/tech-design-template.md
```
—— 用于组装并引用ADRs的TDD文档模板。