{slug}-design.md

{slug}-checklist.yaml

See

easysdd/reference/shared-conventions.md

for shared paths and naming conventions. Generally, the feature directory has already been created by brainstorm; if not, create it in this step.

{slug}-design.md

1. Trim or split any section longer than one screen. If a section can't fit on one screen, readers will lose their sense of orientation.
2. Lock down terms first. Run a grep for all new terms before writing, covering code, architecture directory, and design documents of all features. The cost of term conflicts is that others will look in the wrong place when checking code — the cost of prevention is far lower than sorting it out afterwards.
3. Examples take precedence over definitions. Describe interface behavior with specific examples first (input→output for APIs, Props→rendering/Events examples for components), then supplement with formal types if complex. Readers build a mental model faster from specific input-output than abstract descriptions.
4. Progress by "feature visibility" instead of code file order. Start with the minimal closed loop (an end-to-end working path), then add details. This way, each step can be verified independently, and only one step is lost if a deviation is found along the way.
5. New logic goes into new files by default. Create independent files for new cohesive logic units by default, instead of appending to existing files. Mark each item in the change plan as "New file" or "Append to existing file (reason)". The reason is that larger files make it harder to distinguish responsibilities, and adding to old files forces future maintainers to read irrelevant changes when checking git blame.
6. Each piece of information appears only once in its most natural position. Repetition makes readers repeatedly confirm "Are these two the same thing?", which is more annoying than missing one.
7. Separate process from template. Complete the process below first, then fill in the template content — don't switch between writing and process.

• State assumptions: Every judgment not explicitly stated by the user (input boundaries, error handling, edge cases) should be written as "Assumption: ...", allowing the user to refute precisely.
• Present options instead of choosing: If there are 2-3 reasonable approaches for a point, list all candidates first, then explain your preference, so the user can switch during review.
• Mention simpler alternatives: If the user's direction can achieve the same goal with a lighter approach, explicitly say "There's a simpler approach: ..., should we rule it out first?" Don't stay silent just because the user has given a direction.
• Stop if you don't understand: If you're not sure you've understood the requirement correctly, directly say "I'm not sure about this section" instead of guessing and writing.

• Don't use weak standards like "Make it work". Phrases like "Complete feature X" / "Handle errors properly" / "Smooth user experience" essentially shift the verification responsibility downstream. Rewrite them as "Return B when input is A", "Show prompt Y when error X occurs".
• Every step in the progress sequence has an exit signal. Just writing "Implement XX" is not enough; write "After completion, pass {specific test / operation steps}".
• "Explicitly not doing" must also be verifiable. "Not doing XX" should be specific enough to be checked reversely via grep or tests, not empty phrases like "Avoid over-design".

1. Is this a continuation of previous work — First glob

   easysdd/features/{feature}/{slug}-design.md

   to see if there's a design document with the same name:
   • No → Jump to item 2
   • Yes, but it's an empty template or only has frontmatter → Treat as new creation, jump to item 2
   • Yes,

     status=draft

     and all sections are basically complete → Last time you finished writing but didn't get reviewed, directly jump to step "5. Overall review" in this process
   • Yes, some sections are missing → Report "The previous design was written up to section X, I'll complete the rest and send it to you for review uniformly", only fill in the missing sections, don't rewrite completed ones
   • Yes,

     status=approved

     → Don't overwrite silently; ask the user whether to continue modifying or create a new slug
2. Is the requirement input clear — Confirm at least four items: user goals, core behavior, success criteria, and explicitly excluded scope. Fill in any missing items; if the user can't clarify, go back to brainstorm.
3. Read prerequisite materials — Before writing, you must read

   AGENTS.md

   , the project architecture entry point, architecture index, existing code related to the requirement, and subsystem architecture docs. This step ensures your design connects with existing code; writing without reading will likely result in a design that's disconnected from reality.
4. Archive search — Whether it's worth searching and which directories to prioritize are specified in section 5 of

   easysdd/reference/shared-conventions.md

   . At least consider these two directories in this phase:
   • Precipitation directory (search once uniformly, filter by

     doc_type

     as needed):
     • Full search:

       python easysdd/tools/search-yaml.py --dir easysdd/compound --query "{关键词}"

     • Only view decisions: Append

       --filter doc_type=decision --filter status=active

     • Only view tricks: Append

       --filter doc_type=trick --filter status=active

     • Only view learnings: Append

       --filter doc_type=learning

     • Only view explorations: Append

       --filter doc_type=explore

   • Existing feature designs:

     python easysdd/tools/search-yaml.py --dir easysdd/features --filter doc_type=feature-design --query "{关键词}"

   Prioritize reuse when hits are found, and record the reference source in the design document — this way, future maintainers can trace back through the references.

• Is this something an existing module should be responsible for? If yes, extend that module instead of creating a new one outside.
• Does this span multiple modules — should we extract a common layer in the middle, or let one party lead and others depend on it?
• Does this not fit any existing module? Then we may need to create a new independent module/subsystem — we must clarify in advance where to place the new module, what it exposes externally, and how it interacts with others.
• Is there already a module doing similar things but with a different name that you didn't notice? Grep the project to avoid reinventing the wheel due to different naming.

DESIGN.md

• How long is this file now? How many responsibilities does it take on? Is the new content an extension of existing responsibilities, or the N+1th thing?
• How many methods does this class have? Is the new method a natural extension of the same responsibility, or does it push the class towards "can do everything"?
• For frontend-related work, also check if the component tree hierarchy is too deep and if state ownership is clear (local state / props passing / global store).

reference.md

{slug}-design.md

{slug}-checklist.yaml

easysdd/reference/shared-conventions.md

steps

checks

{slug}-design.md

{slug}-checklist.yaml

reference.md

• steps

  : Extract step by step from the progress sequence subsection of section 3 "Implementation Tips", one step per entry

• checks

  : Extract comprehensively from these places —
  • Each item in section 1 "Explicitly excluded scope" → Scope guard check items
  • Key interface contracts in section 2 → Interface consistency check items
  • Each test constraint in the test design subsection of section 3 "Implementation Tips" → Test verification check items

validate-yaml.py --file {slug-checklist.yaml path} --yaml-only

{slug}-design.md

{slug}-checklist.yaml

reference.md

• YAML frontmatter example
• Top-level section anchor requirements
• Complete format and status semantics of

  {slug}-checklist.yaml

• What to write in each section 0-4

reference.md

• Ran term grep to prevent conflicts and recorded the results
• YAML frontmatter exists, with

  doc_type

  /

  feature

  /

  status

  /

  summary

  /

  tags

  all filled in
• Requirement summary includes "what not to do", and no scope expansion is secretly added later
• Recorded key decisions and rejected solutions
• Each key interface has specific examples (API: input→output; component: Props→rendering / Events), covering normal paths and main error paths
• Examples are marked with source locations (file path + function / component name) via comments
• 4-8 progress steps, each independently verifiable
• Test design is organized by feature points, each feature point has test constraints / verification methods / key use case skeleton
• Recorded high-risk implementation constraints
• After user confirmation,

  status

  in frontmatter is changed to

  approved

• {slug}-checklist.yaml

  has been extracted from

  {slug}-design.md

  and passed validation via

  validate-yaml.py

• The number of steps in

  {slug}-checklist.yaml

  matches the progress sequence subsection in section 3 "Implementation Tips"

easysdd/features/{feature}/

easysdd/reference/shared-conventions.md

• Writing without reading

  AGENTS.md

  and relevant architecture docs — the design will likely not align with existing code
• Not checking for term conflicts — resolving conflicts later will take ten times longer via git blame
• Describing interface behavior in prose without giving specific examples — readers can't build a mental model and can't judge during review
• Writing the contract layer as a full-field encyclopedia — don't copy existing and unchanged interfaces repeatedly
• Forcing diagrams — if there are ≤2 modules and linear calls, diagrams will blur the focus instead
• Splitting progress steps too finely (>8 steps) — so fine that each step has no independent value
• Only giving half the document for user review first — the user can't see global consistency
• Secretly expanding scope in the requirement summary or change plan — won't match acceptance criteria later ",