easysdd-architecture-gen

easysdd/architecture/

is the "map" of the project — read it to position before writing feature-design plans, read it to understand module boundaries during issue-analyze for root cause analysis, and new team members read it to get a general understanding of the system. But this map won't form on its own: someone needs to document the implicit structure in their minds / code into text at the right time. This skill is specifically designed for this task.

The value of the map lies in accuracy, stability, and traceability. The most common mistakes AI makes when writing architecture documents directly violate these three points:

Inventing systems out of thin air — the document says
```
AuthManager coordinates TokenService
```
, but there is no
```
AuthManager
```
layer in the code at all.
Making architecture decisions on behalf of users — quietly choosing a certain layering method, leading readers to think this is an established fact.
Writing documents as code retellings — each section only says "what's here" instead of "why it's divided this way", resulting in the same amount of information as
```
ls -R
```
.

The entire set of rules below is designed to prevent these three types of mistakes.

See
easysdd/reference/shared-conventions.md
for shared paths and naming conventions.

Applicable Scenarios

An architecture document for a subsystem / module is missing and needs to be supplemented
The code has evolved, and the existing architecture document is out of sync with reality and needs to be refreshed
```
easysdd/architecture/DESIGN.md
```
itself needs to be updated (add new indexes / add a section on key architecture decisions)
During the feature-design phase, it is found that a piece of architecture doc "should exist but is missing", so stop to supplement it before proceeding

Not applicable:

The user wants to write a one-time feature plan → redirect to
```
easysdd-feature-design
```
The user wants to finalize a long-term specification → redirect to
```
easysdd-decisions
```
The user wants to check whether the existing architecture doc is self-consistent / consistent with the code → redirect to
```
easysdd-architecture-check
```
The user wants to write "how to use" documents for external readers → redirect to
```
easysdd-guidedoc
```
The user wants to write item-by-item references for public library interfaces → redirect to
```
easysdd-libdoc
```

Single-Target Rule

Only modify one document at a time, choose one of the two:

new: Draft a new architecture document (
```
easysdd/architecture/{slug}.md
```
, or update
```
DESIGN.md
```
itself)
update: Refresh an existing architecture document based on the latest code status + new user materials

Why is writing two documents at once not allowed? The value of architecture documents lies in each document being reviewed — spitting out a bunch of AI drafts at once means users don't have the energy to review each one carefully, and in the end, either all are roughly merged or all are left unread. Single-target + per-document confirmation is a mandatory review mechanism.

Workflow

Phase 1: Lock the Target

Confirm three things:

Mode (
```
new
```
/
```
update
```
)
Target document (new: new slug + audience + scope; update: existing document path)
Scope covered this time (entire document / specific sections)

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

Phase 2: Read Materials

Mandatory reading for all cases:

```
AGENTS.md
```
```
easysdd/architecture/DESIGN.md
```
(main entry point)
Other architecture documents under
```
easysdd/architecture/
```
(to determine whether "this doc should reference them" and "whether there are duplicate descriptions of the same part")
Code entry and core files of the target module / subsystem (identified by the user or you first grep and report candidates for user confirmation)

Conditional reading:

Materials provided by the user (oral accounts, scattered documents, whiteboard photo transcripts)

Relevant compound deposits:

bash

python easysdd/tools/search-yaml.py --dir easysdd/compound --filter doc_type=decision --filter status=active --query "{module keywords}"
python easysdd/tools/search-yaml.py --dir easysdd/compound --filter doc_type=explore --query "{module keywords}"
python easysdd/tools/search-yaml.py --dir easysdd/compound --filter doc_type=learning --query "{module keywords}"

Existing feature plans related to this module (to understand the recent design evolution of this module)

Additional mandatory reading for update mode: Full text of the current version of the document + code changes after

last_reviewed

in the document's frontmatter (a quick scan of commit information for involved files via

git log

is sufficient, no need to diff each one).

Phase 3: One-Time Drafting

Write a complete first draft according to the "Document Structure" below, do not spit out semi-finished products in batches. Batch reviews prevent users from seeing global consistency — the structure described in Section 2 and the decisions recorded in Section 4 often have cross-section contradictions, which can only be seen when placed together.

Phase 4: Self-Check List (Run Immediately After Drafting)

Before user review, go through the following set of checks yourself. Each item is a checkpoint to stop "mistakes AI would normally make":

Can each structured assertion be anchored to code? — "Module A calls B via X", "Y holds the state of Z", "All writes go through W" — can each assertion provide
```
file:line
```
support in the "Code Anchors" section of the document or in-section comments? Assertions that cannot be anchored should either be deleted or marked
```
TODO: To be confirmed
```
and handed over to the user.
Have you made decisions on behalf of the user? — Are the entries in the "Key Decisions" section "citing existing decisions + briefly summarizing the original conclusion" / "citing the user's exact words from user materials", or are the selection reasons made up by AI? The latter is strictly prohibited from being included in the document — stop and ask the user.
Have you turned it into a code retelling? — Each section must have at least one sentence explaining "why it's divided this way"; sections without this sentence are basically just text from
```
ls
```
.
Have you checked for term conflicts? — Grep newly introduced architecture terms (code, all documents under
```
easysdd/architecture/
```
,
```
easysdd/compound/
```
). If there is a conflict, either change the name or clearly state in Section 0: "In this document, X refers to Y, which is not the same as X' in the code".
Does it conflict with existing architecture / decisions? — If you find inconsistencies with a decision or the facts described in other architecture documents during writing, do not "write your own version"; either cite that decision or stop and ask the user "whether that decision should also be updated".
Section length — If a section exceeds one screen, it should be cut or split. Architecture documents are for quick positioning, not for reading through in one go.
Special check for update mode: Is each new / modified paragraph supported by corresponding code changes? Adding a sentence that "sounds more complete" out of thin air is the beginning of drift.

Report the self-check results to the user briefly — if problems are found, state what was found and how it was handled (deleted / marked TODO / rewritten), do not treat it as a "perfunctory" invisible step.

Phase 5: User Review

Post the complete first draft to the user and prompt review. Revise according to the user's feedback until the user clearly states "this doc is acceptable". Only proceed to Phase 6 after user approval.

Phase 6: Finalize + Index Update

new mode: Write to

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

(see Section 0 of

easysdd/reference/shared-conventions.md

for naming rules), set frontmatter

status: current

, and fill

last_reviewed

with the current date

update mode: Overwrite the existing file, update
```
last_reviewed
```
to the current date; if there are structural changes, add an entry "YYYY-MM-DD: {one-sentence description}" in the "Change Log" section at the end of the document
Similar Document Aggregation Check (must run before finalizing): Judge whether the number of documents of the same type in the
```
architecture/
```
root directory reaches ≥6 after this finalization according to the "Architecture Doc Grouping Rules" in
```
easysdd/reference/shared-conventions.md
```
- Threshold hit: Move all documents of this type into the
```
architecture/{type}/
```
  subdirectory, remove the filename prefix, and synchronously modify all relevant links in
```
DESIGN.md
```
  ; the relocation list (old path → new path list + DESIGN.md changes) must be reviewed by the user in Phase 5
- Threshold not hit: Finalize according to the flat path
- Documents of the same type already in the subdirectory can be added / updated in place without re-judgment
Index Update: Open
```
easysdd/architecture/DESIGN.md
```
and check if there is a reference link to this document
- For new mode, must add a link — a new architecture doc is equivalent to being unread if it doesn't enter the main entry
- For update mode, only update the index description when scope or summary changes affect it
- Modifications to DESIGN.md must also be reviewed by the user, do not make changes quietly

Document Structure

frontmatter

yaml

---
doc_type: architecture
slug: {English description, hyphen-separated; consistent with filename}
scope: {One sentence explaining the scope covered by this doc}
summary: {One sentence summarizing the key points of this architecture}
status: current | draft | outdated
last_reviewed: YYYY-MM-DD
tags: []
depends_on: []   # Slugs of other architecture docs, optional
---

Body Sections

markdown

## 0. Terminology

Brief definitions of proper nouns first introduced in this document, plus distinctions from similar nouns ("In this document, X refers to Y, which is not the same as X' in the code"). Omit this section if there are no new terms.

## 1. Positioning and Audience

- Which part of the project this doc describes (module / subsystem / cross-module concern)
- Who will read this doc (feature-design / issue-analyze / new team member onboarding...)
- What readers can do after reading (locate corresponding code / understand external interfaces / know constraints)

## 2. Structure and Interaction

- How modules are divided and dependency directions
- External interfaces (how others use this part), internal interfaces (how this part uses others)
- Cross-module contracts (data format / calling protocol / state ownership)
- No need to draw diagrams if there are ≤2 modules or linear relationships; otherwise, Mermaid is recommended

Attach `file:line` anchors after each structured assertion, or provide them centrally in the "Code Anchors" subsection at the end of the section.

## 3. Data and State

- Key types / core data structures (brief description + definition location file:line)
- Ownership (who writes, who reads)
- Persistence boundaries (memory / local / database / external services)

## 4. Key Decisions

Not the full decision text, but **citations** — one or two lines per entry:

- One-sentence conclusion
- Citation: `easysdd/compound/YYYY-MM-DD-decision-{slug}.md` or source of the user's exact words
- Why this decision is cited in this architecture doc (relationship with this module)

Omit this section if there are no filed decisions, or record `TODO: A certain decision should be documented as a decision`.

## 5. Code Anchors

A centralized list of "where to start reading the code":

- Entry files / key functions / key type definitions
- Format: `{file}:{function/class} — one-line description`

## 6. Known Constraints / Boundary Cases

What hard constraints this module currently has that "cannot be modified / require caution when modified", and their sources (from AGENTS.md / a certain decision / a certain learning).

## 7. Related Documents

- Dependent other architecture docs
- Links to related decisions / learnings / tricks / explorations
- Representative feature designs that use this module

## Change Log (Only for Update Mode)

- YYYY-MM-DD: {One-sentence description}

Hard Boundaries

Only anchor to code, do not invent systems — Each structured assertion must be able to be anchored to
```
file:line
```
; if it cannot be anchored, mark it
```
TODO: To be confirmed
```
, "speculating based on naming" is not allowed.
Do not make decisions on behalf of users — The substantive content in the Key Decisions section must come from the user or traceable decision documents. AI only drafts the structure and connects the language.
Single target — Only modify one document at a time (including
```
DESIGN.md
```
itself counts as one document).
Do not modify code or specs — This skill only writes architecture docs; if problems are found in code / plan docs / decision docs, record them as "observations" and let the user decide whether to start another workflow to handle them.
Do not diverge — Do not expand on issues outside the scope described by the user, just record them as observations.

Exit Conditions

Single mode (new / update) and single target document have been locked
Phase 4 self-check list has been completed item by item, and processing results have been reported
Document frontmatter is complete, with
```
doc_type: architecture
```
,
```
status
```
, and
```
last_reviewed
```
all filled in
Each structured assertion either has a
```
file:line
```
anchor or is marked
```
TODO: To be confirmed
```
Before finalizing, it has been judged whether the number of similar documents is ≥6 according to the "grouping rules"; if the threshold is hit, the relocation list has been reviewed by the user
new mode:
```
DESIGN.md
```
has added a link to the new document (or the user clearly decides not to add it temporarily)
update mode: If there are structural changes, an entry has been added to the "Change Log" section
User has clearly approved the review
No code / plan docs / decision documents have been modified incidentally
No additional document changes outside the scope

Relationship with Other Workflows

Direction	Relationship
Upstream of `easysdd-feature-design`	When writing "which architecture this feature integrates with" in design, read the doc produced by this skill
Downstream of `easysdd-feature-acceptance`	If it is found during acceptance that the feature has a substantial impact on a certain architecture → trigger the update mode of this skill to refresh that doc
Coordination with `easysdd-decisions`	After finalizing an architecture decision, the update mode of this skill can add citations to Section 4 of the relevant architecture doc
Coordination with `easysdd-architecture-check`	After writing with this skill, if you want to confirm "whether the doc is internally consistent / consistent with code", trigger `architecture-check` for a checkup
Reader of `easysdd-issue-analyze`	Read the doc 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 with this skill

Common Pitfalls

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 the Key Decisions section are actually made up by AI
Code retelling: Each section only lists "what's here" without explaining "why it's divided this way"
Spitting out semi-finished products in batches during drafting: Users cannot see cross-section contradictions, leading to in-depth review
Term conflicts: Unaware that newly introduced names conflict with existing ones in code / other architecture docs / compound
Writing / modifying multiple documents at once: Cannot be reviewed thoroughly, resulting in rough merging of all documents
Not stopping when conflicting 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 by anyone
Adding new content in update mode without code basis: Only "sounds more complete", which is the beginning of drift
Incidentally modifying code / plan docs together: Overstepping boundaries, this skill only modifies architecture docs
Continuing to place similar documents in the root directory when there are already ≥6: Triggering the grouping rule but not relocating, making it more chaotic when adding more later
Filename does not follow
```
{type}-{slug}.md
```
: Similar documents cannot be aggregated in the future, making the grouping rule ineffective

easysdd-architecture-gen

NPX Install

Tags

SKILL.md Content (Chinese)

easysdd-architecture-gen

Applicable Scenarios

Single-Target Rule

Workflow

Phase 1: Lock the Target

Phase 2: Read Materials

Phase 3: One-Time Drafting

Phase 4: Self-Check List (Run Immediately After Drafting)

Phase 5: User Review

Phase 6: Finalize + Index Update

Document Structure

frontmatter

Body Sections

Hard Boundaries

Exit Conditions

Relationship with Other Workflows

Common Pitfalls