easysdd-architecture-gen

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

easysdd-architecture-gen

easysdd/architecture/

是项目的"地图"——feature-design 写方案前读它定位，issue-analyze 做根因时读它理解模块边界，新人读它知道系统大致长什么样。但这份地图不会自己长出来：需要有人在合适的时候把脑子里 / 代码里隐含的结构沉淀成文字。本技能就是专门干这件事的。

地图的价值在于准、稳、可查。AI 写架构文档最常翻的几种车都直接砸这三点：

凭空造系统——文档里写了
```
AuthManager 协调 TokenService
```
，代码里根本没
```
AuthManager
```
这层。
替用户拍板架构决策——悄悄选了某种分层方式，读者以为这是既定事实。
把文档写成代码复述——每节都只说"这里有什么"，不说"为什么这么分"，读完和
```
ls -R
```
的信息量一样。

下面整套规则都是为了让这三种车开不起来。

共享路径与命名约定看
easysdd/reference/shared-conventions.md
。

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

有一个子系统 / 模块缺架构文档，想补一份
代码演进了，已有架构文档和现实脱节，要刷新
```
easysdd/architecture/DESIGN.md
```
本身需要更新（新加索引 / 新加一节关键架构决定）
feature-design 阶段发现"应该有但没有"的一块架构 doc，先停下来补上再继续

不适用：

用户要写的是单次 feature 的方案 → 转
```
easysdd-feature-design
```
用户要拍板一条长期规约 → 转
```
easysdd-decisions
```
用户要检查已有架构 doc 是否自洽 / 是否和代码对得上 → 转
```
easysdd-architecture-check
```
用户要写外部读者看的"怎么用"文档 → 转
```
easysdd-guidedoc
```
用户要写库公开接口的逐条目参考 → 转
```
easysdd-libdoc
```

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

每次只动一份文档，二选一：

new：起草一份新架构文档（
```
easysdd/architecture/{slug}.md
```
，或更新
```
DESIGN.md
```
本身）
update：按代码最新状态 + 用户新素材刷新一份已有架构文档

为什么不允许一次写两份？架构文档的价值在于每份都被读过——一次吐一堆 AI 起草稿，用户没精力逐份仔细 review，最后要么全部粗糙合入、要么全部放着不看。单目标 + 逐份确认是强制 review 的机制。

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：锁定目标

Phase 1: Lock the Target

确认三件事：

模式（
```
new
```
/
```
update
```
）
目标文档（new：新 slug + 受众 + 范围；update：已有文档路径）
本次覆盖的范围（整份 / 某几节）

范围不收敛就问用户收敛——一份架构文档要是要"全模块重写"，往往意味着底下其实有多个相对独立的子系统，应该拆成多份分别做。

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：读取材料

Phase 2: Read Materials

共同必读：

```
AGENTS.md
```
```
easysdd/architecture/DESIGN.md
```
（总入口）
```
easysdd/architecture/
```
下的其他架构文档（用于判断"这份 doc 是不是要和它们互相引用"、"有没有重复描述同一块"）
目标模块 / 子系统的代码入口和核心文件（由用户指认或你先 grep 后汇报候选让用户确认）

按情况读：

用户提供的素材（口述、散落文档、白板照片转述）

Phase 3：一次性起草

Phase 3: One-Time Drafting

按下文"文档结构"写出完整初稿，不分批吐半成品。分批 review 会让用户看不到全局一致性——第 2 节描述的结构和第 4 节记录的决策经常有跨节矛盾，只有放在一起才看得出来。

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：自查清单（起草完就地跑一遍）

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

用户 review 前，自己先把下面这组信号过一遍。每一条都是一次"AI 默认会翻的车"的截停点：

每个结构化断言能不能锚到代码？——"A 模块通过 X 调用 B"、"Y 持有 Z 的状态"、"所有写入经 W"——每一条在文档的"代码锚点"节或节内注释里能不能给出
```
file:line
```
支撑？锚不到的断言要么删掉、要么标
```
TODO: 待确认
```
交给用户。
有没有替用户拍板？——"关键决策"节里的条目是"引用已有 decision + 简述原文结论" / "引用用户素材里用户说过的原话"，还是 AI 自己编的选型理由？后者一律不许进文档——停下来问用户。
有没有变成代码复述？——每节至少一句话说"为什么这么分"，没有这一句的节基本就是
```
ls
```
贴文字。
术语冲突检查做了吗？——新引入的架构术语做一遍 grep（代码、
```
easysdd/architecture/
```
下所有文档、
```
easysdd/compound/
```
）。冲突了就换名字或在第 0 节明确"本文里 X 指 Y，和代码里的 X' 不是一个东西"。
是否和现有 architecture / decision 冲突？——写的过程中如果发现和某条 decision 或其他架构文档描述的事实对不上，不许"写自己的那版"，要么引用那条、要么停下来问用户"是不是那条也该更新了"。
单节长度——每节超过 1 屏就该砍或拆。架构文档是给人快速定位的，不是用来读一遍的。
update 模式专项：本次新加 / 改动的段落是否都有对应的代码变化作为依据？纯凭空"加一句听起来更完整的描述"是漂移的开端。

自查结果简短汇报给用户——发现问题就说发现了、怎么处理（删掉 / 标 TODO / 改写），不要当成"走过场"隐形步骤。

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：用户 review

Phase 5: User Review

把初稿完整贴给用户，提示 review。用户提意见就改，反复直到用户明确"这份 doc 可以了"。用户放行后才进入 Phase 6。

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：落盘 + 索引更新

Phase 6: Finalize + Index Update

new 模式：写入

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

（命名规则见

easysdd/reference/shared-conventions.md

第 0 节），frontmatter

status: current

，

last_reviewed

填当天

update 模式：覆盖已有文件，
```
last_reviewed
```
更新为当天；如果结构性改动大，在文档末尾
```
变更日志
```
节加一条"YYYY-MM-DD：{一句话描述}"
同类聚合检查（落盘前必跑）：按
```
easysdd/reference/shared-conventions.md
```
的"架构 doc 的分组规则"判断本次落盘后某个 type 在
```
architecture/
```
根目录是否达到 ≥6 份
- 命中阈值：本次操作要把这一类全部搬进
```
architecture/{type}/
```
  子目录、去掉文件名前缀，并同步改
```
DESIGN.md
```
  里所有相关链接；搬迁清单（旧路径 → 新路径列表 + DESIGN.md 改动）必须在 Phase 5 一并给用户 review
- 未命中：按平铺路径落盘
- 已经在子目录里的同类直接就地新增 / 更新，不需要再判
索引更新：打开
```
easysdd/architecture/DESIGN.md
```
，检查有没有对本文档的引用链接
- new 模式下必定要加链接——新架构 doc 如果不进入总入口，等于写了没人会读
- update 模式下只在 scope 或 summary 变化影响索引描述时更新
- DESIGN.md 的修改同样给用户 review，不要直接悄悄改

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: {英文描述，连字符分隔；和文件名一致}
scope: {一句话说清楚这份 doc 覆盖的范围}
summary: {一句话总结这块架构的要点}
status: current | draft | outdated
last_reviewed: YYYY-MM-DD
tags: []
depends_on: []   # 其他 architecture doc 的 slug，可选
---

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

undefined

markdown

undefined

0. 术语

0. Terminology

本文里首次引入的专有名词简要定义，外加和相近名词的区分（"本文里 X 指 Y，和代码里的 X' 不是同一个东西"）。没有新术语就省略本节。

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. 定位与受众

1. Positioning and Audience

本 doc 描述的是项目里哪一块（模块 / 子系统 / 跨模块关注点）
谁会读这份 doc（feature-design / issue-analyze / 新人上手……）
读完能干嘛（定位到对应代码 / 了解对外接口 / 知道约束）

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. 结构与交互

2. Structure and Interaction

模块怎么划分、依赖方向
对外接口（别人怎么用这块）、对内接口（这块怎么用别人）
跨模块契约（数据格式 / 调用协议 / 状态归属）
模块 ≤ 2 或关系线性时不画图；否则建议 Mermaid

每条结构化断言后附

file:line

锚点，或在节末尾的"代码锚点"小节集中给。

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. 数据与状态

3. Data and State

关键类型 / 核心数据结构（简述 + 定义位置 file:line）
所有权归属（谁写、谁读）
持久化边界（内存 / 本地 / 数据库 / 外部服务）

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

4. 关键决策

4. Key Decisions

不是决策全文，是引用——每条一两行：

结论一句话

引用：

easysdd/compound/YYYY-MM-DD-decision-{slug}.md

或用户原话出处

为什么引用到这份架构 doc 里（和本模块的关系）

没有已落档的决策就省略本节，或记

TODO: 某决定应沉淀为 decision

。

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. 代码锚点

5. Code Anchors

集中列一份"想看代码从哪看"的清单：

入口文件 / 关键函数 / 关键类型定义

格式：

{file}:{function/class} — 一行说明

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. 已知约束 / 边界情况

6. Known Constraints / Boundary Cases

本模块现在有哪些"不能动 / 动了要小心"的硬约束，以及它们的来源（来自 AGENTS.md / 某条 decision / 某次 learning）。

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. 相关文档

7. Related Documents

依赖的其他 architecture doc
相关 decision / learning / trick / explore 的链接
使用本模块的代表性 feature design

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

变更日志（update 模式才有）

Change Log (Only for Update Mode)

YYYY-MM-DD：{一句话描述}

---

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

---

硬性边界

Hard Boundaries

只锚代码，不造系统——每条结构化断言必须能锚到
```
file:line
```
；锚不到就标
```
TODO: 待确认
```
，不允许"根据命名推测"。
不替用户拍板决策——关键决策节的实质内容必须来自用户或可追溯的 decision 文档。AI 只起草结构和串联语言。
单目标——一次只动一份文档（含
```
DESIGN.md
```
本身也算一份）。
不改代码、不动 spec——本技能只写架构 doc，发现代码 / 方案 doc / decision 有问题就记为"观察项"交给用户决定是否另开工作流处理。
不发散——用户描述的范围外问题一律不扩展，记成观察项即可。

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

已锁定单一模式（new / update）和单一目标文档
Phase 4 自查清单逐条跑过，并已汇报处理结果
文档 frontmatter 完整，
```
doc_type: architecture
```
、
```
status
```
、
```
last_reviewed
```
都填了
每个结构化断言要么有
```
file:line
```
锚点、要么标了
```
TODO: 待确认
```
落盘前已按"分组规则"判断同类是否 ≥6 份，命中则搬迁清单已和用户 review 过
new 模式：
```
DESIGN.md
```
已加指向新文档的链接（或用户明确决定暂不加）
update 模式：如有结构性改动，
```
变更日志
```
节已加一条
用户明确 review 通过
没有顺手修改代码 / 方案 doc / decision 文档
没有范围外的额外文档改动

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

方向	关系
`easysdd-feature-design` 上游	design 写到"本 feature 和哪块架构对接"时读本技能产出的 doc
`easysdd-feature-acceptance` 下游	验收时如果发现 feature 对某块架构有实质影响 → 可触发本技能 `update` 模式刷新那份 doc
`easysdd-decisions` 配合	拍板一条架构决策后，本技能 `update` 可把引用补进相关架构 doc 的第 4 节
`easysdd-architecture-check` 配合	本技能写完后如果想确认"doc 内部自洽 / doc 和代码对得上"，触发 `architecture-check` 做一次体检
`easysdd-issue-analyze` 读者	根因分析阶段读本技能产出的 doc 定位模块边界
`easysdd-onboarding` 创建者	onboarding 阶段建 `DESIGN.md` 占位，之后由本技能填实 / 扩充

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

凭空造系统：文档里出现了一个代码里并不存在的"协调层 / 中枢 / 管理器"
替用户拍板架构决策：关键决策节里的选型理由其实是 AI 编的
代码复述：每节都只列"这里有什么"，没说"为什么这么分"
起草分批吐半成品：用户看不出跨节矛盾，review 不深
术语冲突：新引入的名字和代码 / 其他 architecture doc / compound 里已有的东西冲突了还不自知
一次写 / 改多份文档：审不过来，最后全部粗糙合入
和已有 decision 冲突不停下：自己写了一版和既定 decision 相悖的说法
new 模式落盘后忘记在
```
DESIGN.md
```
加索引：写了没人能发现
update 模式加了新内容但没有代码依据：只是"读起来更完整"，这是漂移开端
顺手把代码 / 方案 doc 一起改了：越界，本技能只动架构 doc
同类已经 ≥6 份还继续往根目录平铺：触发了分组规则却没搬迁，下次再加只会更乱
文件名没遵循
```
{type}-{slug}.md
```
：未来同类聚不起来，分组规则形同虚设

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