yzr-sys-design-doc

yzr-sys-design-doc

Constrain "writing a system design document" intoconsistent in structure, review-friendly, and practically executabledeliverables: route to the full / lite two-tier templates according to the scale of change——the full tier produces a design document + implementation task brief (a living document during execution), and the lite tier produces a single design description. The chapter structure, what to write in each section, and the division of labor within sections are governed by the assets/ template files; the "why" of cross-section principles is governed by the execution principles in this file as the SSOT, and the templates do not repeat them (the only exception:assets/template-tasks.md must be readable standalone by executors apart from this skill, and the discipline section is intentionally self-contained)

Input and Output

• Input: the user's natural language requirements (possibly including the current state of the system, tech stack, constraints, review timing); optional: code repository path / related existing documents
• Output: the full tier producestwo local Markdown files——the design document <功能slug>-design.md(a review artifact, stable after review) + the implementation task brief <功能slug>-tasks.md(a living document during execution, in which progress / issues / design changes flow); the lite tier produces only <功能slug>-design.md. The path is specified by the user or is the current working directory; the body text is in Chinese, and technical terms remain in English

Execution Principles

The first is a meta-principle, and the rest are ordered by document lifecycle: tier determination → requirements layer → solution layer → implementation layer

• The reader is the reviewer (meta-principle): before writing each section, ask "what decision can the reviewer make by reading this section"——a section that cannot answer that is just padding. All structure (current state first / decisions leave a trace / "considered" options leave evidence) serves one thing: letting the reviewer make the judgment of "approve / send back / supplement where" in the shortest time
• Size matches scale: applying the full template to a small change = the reviewer reads a dozen sections to find one field change; using lite for a large change = missing impact surface and rollback. Determine the tier according toWorkflowStep 1's tier table (Sections); when the user explicitly states the tier, follow the user
• Current state first: the primary scenario is adding to or modifying an existing system——the document must first clearly explain "how it is done now", then explain the change. The reviewer's biggest information gap is the current state, not the solution; skipping the current state and writing the solution directly = verbally filling it in from scratch at the review meeting
• The current state has a source: assertions about the current state / existing behavior must be able to point to a basis——code location, configuration item, online data, user's verbal statement (marked "user-stated"). What cannot point to a basis is conjecture, not the current state: it goes into the assumptions list and is not written in a factual tone. Making up the current state from imagination = the foundation of the entire document is false, and all subsequent design is wrong along with it
• Requirements layer first (full tier): the five sections of Background and Current State / Goals and Non-Goals / Feature Breakdown / Feature Specifications and Constraints / Scenario Breakdown are the requirements layer,independent of implementation——when these five sections are finished, no technical selection should yet have been made; if the implementation solution is changed, these five sections still hold. The appearance of specific technical selections in requirements-layer sections ("use Redis to store...") = solution-layer content crossing layers, move it to the detailed design
• Full decomposition (full tier): Exhaust before designing—break requirements into a feature point list and problems into a full scenario table (main flow / branches / exceptions). These two tables are the baseline for completeness: every feature point / scenario must have a landing point in the solution; rows with an empty landing point are design gaps. The scenario table is also the source of acceptance criteria
• Verifiability: Every goal / spec / scenario expected behavior must be able to answer "how do we count it as done"—items for which no judgment method can be written are unqualified ("improve experience" is not verifiable, "selecting a coupon goes from 3 steps to 0 steps" is verifiable). Since the scenario table is the source of the acceptance checklist, every row must be able to be objectively judged true / false
• Make assumptions explicit: When information is insufficient, do not ask the user a chain of questions—give reasonable assumptions, write them into an "assumptions" list in the document, and confirm during review. Only ask the user when there is a key decision fork (affecting the direction of the solution)
• Quantify and label the basis: Use numbers instead of adjectives whenever possible—"oversell rate 3 per thousand" > "frequent overselling", "P99 < 200ms" > "low latency". Adjectives have their own scale for everyone; a number has only one; estimates may be rough, but are not allowed to be absent. Numbers must be labeled with their basis (measured / obtained from reading code / estimated / assumed); estimates are written as "estimated", assumptions go into the assumptions list—fabricated precision is more dangerous than acknowledged unknowns: reviewers will take unlabeled estimates as facts for capacity and scheduling decisions. Vague quantifiers and open endings (often / a large amount / relatively high / basically / probably / "etc.") must be rewritten on sight: change to numbers when possible, enumerate when possible, and put what cannot be determined into the assumptions list
• Consistent basis: The same rule / number / term has only one formulation throughout the document—rules are stated at a single point in the "Functional Specs and Constraints" section, and references elsewhere do not copy them again; the same concept has the same name throughout (do not call it "cooling-off period" in one place and "freeze period" in another); numbers across sections must be the same (if "Functional Specs and Constraints" says TTL 30 minutes, "Detailed Design" cannot say 1 hour). If a reviewer catches two places with conflicting bases, they will discount the credibility of the whole document
• Keep a record of design decisions: Put selection and trade-offs in the "Alternative Solutions" section. A solution is selected not because it is obvious, but because the alternatives were explicitly rejected—when looking back three months later or when a newcomer takes over, this section is the only record of "why it was decided this way at the time". Trade-offs scattered in footnotes in the main text = not written
• Separate engineering rollback from business cancellation: The rollback section only writes "how to back out if an online problem occurs after launch" (switch / rollback version / fix script); "how users cancel an operation" is business process design and belongs in the solution design section. What the lite tier most often misses is engineering rollback
• Design SSOT, task book as a living document (full tier): The design document remains stable after review; the task book only acts as a pointer and does not copy the design, execution feedback (progress / issues) is written only in the task book; to change the design, first revise the design document, then sync the task book— reverse flow (bypassing the design to change the implementation) will invalidate both documents at the same time

Workflow

1. Tier determination: Determine full / lite according to the table below

   Signal	Tier
   New system / cross-service / changing a core path (funds, inventory, settlement, account main flow) / state machine refactor / formal review meeting	full
   Small change within a single service / no complex state transitions	lite
   User explicitly specifies the tier or scale	Follow the user
   If unsure	Default to full—in review scenarios, the cost of missing a section outweighs writing two extra sections

2. Read the template：full → assets/template-full.md；lite → assets/template-lite.md. The section structure and what each section should "write / why" are based on the template file

3. Add context: When the user provides a code repository path, first read the relevant code before writing the current-state section; the basis and assumption discipline for current-state assertions follow the execution principles'Current state has sources、Assumptions made explicitExecute (section）

4. Write according to the template: Do not change the section order or naming; when a section truly does not applyKeep the section and write "None this period + one-sentence reason"— Reviewers need to see "considered"; silently deleting sections makes it impossible to tell whether it was "not thought of" or "not needed"

5. Generate the task book (full tier only): According to assets/template-tasks.md Break out tasks from the feature point breakdown and detailed design, produce <功能slug>-tasks.md initial version (all statuses "Not started")—it is then handed to the executor (person or agent), and progress / issues / design changes flow according to the task book template's "Issue Feedback and Design Changes" loop discipline; the lite tier skips this step

6. Self-check(check item by item before delivery):

   • Metadata block is filled in (status defaults to "Draft", date is the current day)
   • Non-goals are non-empty (full tier)
   • Each item in the feature point list has a landing point in the detailed design; the "Design Landing Point" column in the scenario table has no empty rows (full tier)
   • The functional specifications and constraints section gives precise rule definitions (values / limits / default policies / hard constraints), not a vague sentence like "implement according to requirements" (full tier)
   • Goals / specifications / scenario expected behaviors are all determinable—for each one, you can write "how to count it as done" (verifiability principle)
   • Numbers and current-state assertions carry their basis (measured / code-read / estimated / assumed / user-stated)—no "precise" numbers with unlabeled sources
   • No vague quantifiers or open endings (often / a large amount / relatively high / basically / probably / "etc."); everything that can be enumerated has been enumerated
   • The same rule / term / number is consistent across sections (rules use "Functional Specifications and Constraints" as the single point; references elsewhere do not repeat them) (full tier)
   • Except for the metadata "Reviewer: TBD", there is no bare TBD / to be supplemented in the full text—undecided items are concentrated in the open questions section (full tier)
   • Each DFX sub-item (for the enumeration see template-full.md DFX section) is explicitly addressed, and non-applicable items have a basis (full tier)
   • At least 1 alternative is provided with a reason for rejection (full tier)
   • The rollback section describes engineering rollback, not business process cancellation
   • The open questions section exists (writing "None" is fine, but this section must be present to show it was considered) (full tier)
   • Task book (independent <功能slug>-tasks.md) each task carries four pointers (feature point / design landing point / acceptance scenario / dependency) and a status field; task rows do not copy design details (full tier)
   • The impact scope covers all dimensions enumerated in the template's impact scope section (full tier "Compatibility and Impact Scope" / lite tier "Impact Scope"), and dimensions with no impact are written as "None" + basis
   • Objects with state transitions have a state machine drawn (not just textual description)

Reference examples

• "Add a 'filter by status' dropdown to the backend order list; don't overcomplicate a small requirement" → lite: Background and goals / Solution design / Impact scope / Rollback and contingency plan / Self-test key points; do not write capacity assessment or scheduling
• "Add daily reconciliation file parsing and ingestion to the payment pipeline; review at end of month" → full: All sections, parsing state machine + reconciliation discrepancy table DDL + file interface agreement + existing data handling + canary rollback