easysdd-architecture

easysdd/architecture/

is the "map" of the project — read it for positioning before writing a feature-design plan, read it to understand module boundaries during issue-analyze root cause analysis, and new team members read it to get a general understanding of the system. This map won't generate or maintain accuracy on its own — someone needs to draft, refresh, and audit it at the right time. This skill serves as the unified entry point for these three tasks.

The value of architecture documents lies in accuracy, stability, and searchability. Several common issues when AI writes or checks architecture documents directly undermine these three points:

Inventing systems out of thin air — the document states "AuthManager coordinates TokenService", but there is no
```
AuthManager
```
layer in the code at all.
Making architecture decisions on behalf of users — secretly choosing a certain layering approach, leading readers to believe it is an established fact.
Writing documents as code retellings — each section only says "what's here" instead of "why it's divided this way", providing the same amount of information as
```
ls -R
```
after reading.
"Glancing and feeling it's okay" during checks — no specific location evidence is provided, leaving users unable to judge if it's actually okay.

The entire set of rules below is designed to prevent these situations.

See
easysdd/reference/shared-conventions.md
for shared paths and naming conventions. See
reference.md
in the same directory for document structure templates, check coverage lists, and report formats.

Mode Diversion

First determine the mode at startup, choose one of three — AI automatically judges based on what the user says, no menu selection required for users:

What the user says	Mode
"Fill in an architecture doc", "Draft the architecture document for {module}", "Write down the structure of this part"	`new`
"Refresh {a certain document}", "The code has changed, sync the architecture doc", "Update the architecture directory to the latest version"	`update`
"Check if the design is internally consistent", "Does the plan match the code?", "Are there conflicts among several architecture documents?", "Conduct an architecture health check"	`check`

If unable to determine, ask the user instead of guessing.

Single-Target Rule

Run only one mode each time, and lock only one target within that mode:

```
new
```
: Draft a new architecture document (
```
easysdd/architecture/{type}-{slug}.md
```
, or update
```
DESIGN.md
```
itself)
```
update
```
: Refresh an existing architecture document based on the latest code status + new user materials
```
check
```
: One of three sub-goals
- ```
design-internal
```
  — Internal consistency of a single feature design document
- ```
design-vs-code
```
  — Consistency between a single feature design and code
- ```
architecture-folder-internal
```
  — Consistency among multiple architecture documents under
```
easysdd/architecture/
```

Why not allow multiple tasks at once? When drafting, users can't review multiple AI-generated documents at once; during checks, the three sub-goals have completely different perspectives and reference materials, doing them simultaneously will lead to shallow coverage and unclear responsibility for mixed issues. If the user proposes multiple targets, ask them to choose one and leave the rest for next time.

Workflow Skeleton (Shared by Three Modes)

All modes go through six phases, with details diverging by mode:

Phase 1: Lock Target
Phase 2: Read Materials
Phase 3: Execute (new/update = draft; check = inspect)
Phase 4: Self-Review (new/update) or Output Report (check)
Phase 5: User Review
Phase 6: Finalize (new/update) or Wait for User's Next Decision (check)

Phase 1: Lock Target (All Modes)

Confirm three things:

Mode (
```
new
```
/
```
update
```
/
```
check
```
)
Target object:
- ```
new
```
  : New slug + audience + scope
- ```
update
```
  : Path of existing document
- ```
check
```
  : Sub-goal + inspection object (feature name / architecture sub-scope)
Scope covered this time (full document / specific sections / specific documents)

If the scope is not converged, ask the user to converge — if an architecture document requires "full module rewrite", it often means there are multiple relatively independent subsystems underneath, which should be split into separate tasks; a report covering the entire

architecture/

directory at once is hard to focus on key points.

Phase 2: Read Materials

Mandatory reading for all modes:

```
AGENTS.md
```
```
easysdd/reference/shared-conventions.md
```
```
easysdd/architecture/DESIGN.md
```
(main entry point)
Other architecture documents under
```
easysdd/architecture/
```
(judge whether to cross-reference or if there are duplicates)

Additional mandatory reading for new / update (see "Reading List" in

reference.md

Code entry and core files of the target module / subsystem (identified by user or grep first then report candidates for user confirmation)
Materials provided by user (oral description, scattered documents, whiteboard photo transcription)
Relevant compound沉淀 (decision / explore / learning)
Existing feature plans related to this module
update-specific: Full text of current version document + code changes after the document's
```
last_reviewed
```
date (rough scan via
```
git log
```
)

Additional mandatory reading for check (varies by sub-goal, see

reference.md

for details):

```
design-internal
```
/
```
design-vs-code
```
: Full text of plan doc + relevant documents in architecture center directory
```
design-vs-code
```
additional: Code files directly corresponding to Sections 2/3 of the design
```
architecture-folder-internal
```
: The specified
```
easysdd/architecture/**/*.md
```
documents (or all documents of the same type under a certain type) + index + referenced documents found via links (no expansion to code)

Phase 3: Execute

new / update mode: Write a complete first draft according to the "Document Structure" in

reference.md

, do not output semi-finished products in batches. Batch review prevents users from seeing global consistency — the structure described in Section 2 and the decisions recorded in Section 4 often have cross-section conflicts, which can only be seen when presented together.

check mode: Execute item by item according to the "Check Coverage Items" in

reference.md

(6 categories for each of the three sub-goals). Record locatable positions (

file:line

or "Section X of design") + phenomenon + impact + repair suggestion for each inconsistency.

Phase 4: Self-Review (new/update) or Output Report (check)

new / update: Run through the "Self-Review List" (7 items) in

reference.md

on the spot, and fix issues before submitting to user review (delete / mark TODO / rewrite). Briefly report the self-review results to the user — state if issues were found and how they were handled, do not treat it as an invisible "formality" step.

check: Output a complete report according to the "Report Template" in

reference.md

, including inspection summary / inconsistency list (table with severity levels) / observation items (out of scope) / consistent items / suggested next steps.

Phase 5: User Review

new / update: Paste the complete first draft to the user and prompt review. Revise according to user feedback until the user explicitly confirms "this doc is ready".

check: Send the report to the user and wait for confirmation of conclusions — whether to accept, add another type of check, or proceed to the next step decided by the user. This skill does not make decisions on behalf of users.

Phase 6: Finalize (new/update) or End (check)

new mode:

Write to

easysdd/architecture/{type}-{slug}.md

(naming rules see Section 0 of

easysdd/reference/shared-conventions.md

), set frontmatter

status: current

, fill

last_reviewed

with the current date

Same-Type Aggregation Check (mandatory before finalization): Judge if the number of documents of a certain type in the
```
architecture/
```
root directory reaches ≥6 after this finalization according to the "Architecture Doc Grouping Rules" in shared-conventions — if the threshold is hit, move all documents of this type to the
```
architecture/{type}/
```
subdirectory, remove the filename prefix, and update all relevant links in
```
DESIGN.md
```
; the relocation list must be reviewed by the user together in Phase 5
Index Update: Open
```
easysdd/architecture/DESIGN.md
```
and add a reference link to the new document — this must be done in new mode; otherwise, the document will be written but never read; changes to DESIGN.md must also be reviewed by the user, do not modify secretly

update mode:

Overwrite the existing file, update
```
last_reviewed
```
to the current date
If there are major structural changes, add an entry "YYYY-MM-DD: {one-sentence description}" in the "Change Log" section at the end of the document
Update DESIGN.md only if scope or summary changes affect the index description

check mode: No finalization, end the process. Users may decide to trigger

new

update

or other workflows based on the report — that will be handled in the next round.

Hard Boundaries

Anchor only to code, do not invent systems (new / update) — each structured assertion must be anchored to
```
file:line
```
; if unable to anchor, mark
```
TODO: To be confirmed
```
, do not allow "speculation based on naming".
Do not make decisions on behalf of users (new / update) — substantive content in key decision sections must come from users or traceable decision documents. AI only drafts the structure and connects the language.
Only check, do not fix (check) — prohibit modifying design / code / configuration. Separate checking and fixing so users can see the complete inconsistency list before deciding priorities as a whole.
Evidence-based (check) — each inconsistency must have a locatable position (
```
file:line
```
or "Section X of design").
Executable suggestions (check) — specific to "what to change and how to change", but do not finalize.
Single-target (all modes) — run only one mode at a time, and lock only one target within that mode.
Do not modify code or spec (all modes) — this skill only writes architecture docs or generates inspection reports. If issues are found in code / plan doc / decision, record them as "observation items" and let users decide whether to initiate another workflow.
Do not diverge (all modes) — do not expand to issues outside the user-described scope, just record them as observation items.

Exit Conditions

Common to all modes:

Single mode and single target have been locked
User has explicitly approved the review (new / update) or confirmed the current round of inspection conclusions (check)
No code / plan doc / decision documents have been modified without permission
No additional document changes outside the scope

Additional for new / update:

The self-review list in
```
reference.md
```
has been run item by item, and the handling results have been reported
Document frontmatter is complete, with
```
doc_type: architecture
```
,
```
status
```
, and
```
last_reviewed
```
all filled
Each structured assertion either has a
```
file:line
```
anchor or is marked
```
TODO: To be confirmed
```
Before finalization, it has been judged whether the number of same-type documents is ≥6 according to the "Grouping Rules"; if hit, the relocation list has been reviewed by the user
new:
```
DESIGN.md
```
has added a link to the new document (or the user has explicitly decided not to add it for now)
update: If there are structural changes, an entry has been added to the "Change Log" section

Additional for check:

The check items corresponding to the sub-goal have been fully covered (see
```
reference.md
```
)
The report includes an inconsistency list + repair suggestions
The report does not contain any actual repair actions

Relationship with Other Workflows

Direction	Relationship
Cooperation with `easysdd-requirements`	Requirements describe "why this capability is needed", this skill describes "what structure to use for implementation"; the frontmatter `implements` of the architecture doc links back to the req slug it carries
Upstream of `easysdd-feature-design`	When writing "which architecture this feature connects to" in design, read the docs produced by this skill; after design is completed, trigger the check mode for a self-consistency health check
Downstream of `easysdd-feature-acceptance`	During the acceptance phase, actually update the docs produced by this skill (acceptance handles merging itself, does not call back this skill's new/update); trigger the `design-vs-code` sub-goal of the check mode to confirm alignment between implementation and design
Cooperation with `easysdd-decisions`	After an architecture decision is made, this skill's `update` can add references to Section 4 of relevant architecture docs
Reader of `easysdd-issue-analyze`	Read the docs produced by this skill to locate module boundaries during root cause analysis
Creator of `easysdd-onboarding`	Create a placeholder `DESIGN.md` during onboarding, then fill it in / expand it via this skill

Common Mistakes

Common pitfalls for new / update:

Inventing systems out of thin air: A "coordination layer / hub / manager" that does not exist in the code appears in the document
Making architecture decisions on behalf of users: The selection reasons in key decision sections are actually made up by AI
Retelling code: Each section only lists "what's here" without explaining "why it's divided this way"
Drafting semi-finished products in batches: Users can't see cross-section conflicts, leading to shallow review
Term conflicts: Newly introduced names conflict with existing ones in code / other architecture docs / compounds without awareness
Writing / modifying multiple documents at once: Unable to review thoroughly, resulting in rough integration
Continuing despite conflicts with existing decisions: Writing a version that contradicts established decisions
Forgetting to add an index in
```
DESIGN.md
```
after finalizing in new mode: The document is written but cannot be found
Adding new content in update mode without code basis: Just "reads more complete", which is the start of content deviating from reality
Modifying code / plan doc along the way: Overstepping boundaries, this skill only modifies architecture docs
Continuing to place same-type documents in the root directory when there are ≥6: Triggering the grouping rule but not relocating
Filename does not follow
```
{type}-{slug}.md
```
: Unable to aggregate same-type documents in the future, making the grouping rule useless

Common pitfalls for check:

Doing multiple sub-goals at once (only one of design-internal / design-vs-code / architecture-folder-internal can be selected)
Reading code to verify during
```
architecture-folder-internal
```
— that's the job of
```
design-vs-code
```
Modifying code or documents immediately after finding issues
Only saying "something is wrong here" without providing evidence location
Suggestions are too abstract ("optimize the architecture")
Unlimited expansion from one target to full repository audit

easysdd-architecture

NPX Install

Tags

SKILL.md Content (Chinese)

easysdd-architecture

Mode Diversion

Single-Target Rule

Workflow Skeleton (Shared by Three Modes)

Phase 1: Lock Target (All Modes)

Phase 2: Read Materials

Phase 3: Execute

Phase 4: Self-Review (new/update) or Output Report (check)

Phase 5: User Review

Phase 6: Finalize (new/update) or End (check)

Hard Boundaries

Exit Conditions

Relationship with Other Workflows

Common Mistakes