Agent Skills
› NeverSight/learn-skills.dev
› generar-tech-design
generar-tech-design
GitHub交互式生成生产级技术设计文档及MADR格式ADRs。通过PRD逐步访谈用户决策，区分绿场/棕场项目，结合现有代码约束，逐一确认架构选项与权衡，确保文档可追溯且符合实际业务需求。
触发场景
用户要求生成技术设计文档、系统架构或架构决策记录(ADRs)
用户提供PRD并请求进行技术架构规划
安装
npx skills add NeverSight/learn-skills.dev --skill generar-tech-design -g -y
SKILL.md
Frontmatter
{
"name": "generar-tech-design",
"description": "Genera el Technical Design Document + ADRs (formato MADR) + criterios de aceptación de un proyecto, entrevistando al usuario decisión por decisión a partir de su PRD (y opcionalmente su Design.md o un repo existente). Use when the user asks to generate, draft, or create a technical design document, system architecture, or architecture decision records (ADRs) for a project, greenfield or brownfield."
}
Technical Design Document Generator (Interactive)
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.
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 inTECH-DESIGN.mdthat no Design.md was available — do not block on it.
Step 0 — Project type
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.
- 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
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.mdfromassets/tech-design-template.md, referencing every ADR by number, including inherited ones. - Write to disk:
TECH-DESIGN.mdat 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.
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.mdwas actually answered by the user — not filled in solo by the agent because a question was skipped.
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.
版本历史
- c3c0a1e 当前 2026-07-23 10:54
