easysdd-architecture

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

easysdd-architecture

easysdd/architecture/

是项目的"地图"——feature-design 写方案前读它定位、issue-analyze 做根因时读它理解模块边界、新人读它知道系统大致长什么样。这份地图不会自己长出来，也不会自己保持准确——有人在合适的时候起草、刷新、体检。本技能就是这三件事的统一入口。

架构文档的价值在于准、稳、可查。AI 写架构文档和查架构文档时最容易出的几种问题都直接破坏这三点：

凭空造系统——文档里写了
```
AuthManager 协调 TokenService
```
，代码里根本没
```
AuthManager
```
这层。
替用户拍板架构决策——悄悄选了某种分层方式，读者以为这是既定事实。
把文档写成代码复述——每节都只说"这里有什么"，不说"为什么这么分"，读完和
```
ls -R
```
的信息量一样。
检查时"看一眼感觉没问题"——没给出具体位置证据，用户无从判断是不是真的 ok。

下面整套规则就是为了不让这几种情况发生。

共享路径与命名约定看
easysdd/reference/shared-conventions.md
。文档结构模板、check 覆盖项清单、报告格式看同目录
reference.md
。

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

启动时先判断模式，三选一——AI 根据用户说的话自动判断，不让用户选菜单：

用户说什么	模式
"补一份架构 doc"、"起草 {模块} 的架构文档"、"把这块结构写下来"	`new`
"刷新 {某文档}"、"代码变了，把架构 doc 同步一下"、"把 architecture 目录更新到最新"	`update`
"检查一下 design 自洽吗"、"方案和代码对得上吗"、"architecture 几份文档有没有打架"、"做架构体检"	`check`

判断不出来就问用户一句，不要硬猜。

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

每次只跑一个模式，且该模式内只锁定一个目标：

```
new
```
：起草一份新架构文档（
```
easysdd/architecture/{type}-{slug}.md
```
，或更新
```
DESIGN.md
```
本身）
```
update
```
：按代码最新状态 + 用户新素材刷新一份已有架构文档
```
check
```
：三个子目标之一
- ```
design-internal
```
  — 一份 feature design 文档内部一致性
- ```
design-vs-code
```
  — 一份 feature design 与代码的一致性
- ```
architecture-folder-internal
```
  —
```
easysdd/architecture/
```
  下多份架构文档之间的一致性

为什么不允许一次做多件？起草时一次吐多份 AI 稿用户 review 不过来；检查时三个子目标的视角和读取材料完全不同，同时做会导致每边都不深、问题混在一起说不清责任。用户提多个目标就让 TA 选一个，其余留到下次。

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)

所有模式走六个阶段，细节按模式分流：

Phase 1：锁定目标
Phase 2：读取材料
Phase 3：执行（new/update = 起草；check = 检查）
Phase 4：自查（new/update）或 输出报告（check）
Phase 5：用户 review
Phase 6：落盘（new/update）或 等用户拍板下一步（check）

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：锁定目标（所有模式）

Phase 1: Lock Target (All Modes)

确认三件事：

模式（
```
new
```
/
```
update
```
/
```
check
```
）
目标对象：
- ```
new
```
  ：新 slug + 受众 + 范围
- ```
update
```
  ：已有文档路径
- ```
check
```
  ：子目标 + 检查对象（feature 名 / architecture 子范围）
本次覆盖的范围（整份 / 某几节 / 哪几份文档）

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

architecture/

目录出来的报告读起来反而抓不到重点。

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

Phase 2: Read Materials

共同必读：

```
AGENTS.md
```
```
easysdd/reference/shared-conventions.md
```
```
easysdd/architecture/DESIGN.md
```
（总入口）
```
easysdd/architecture/
```
下的其他架构文档（判断要不要互相引用、有没有重复）

new / update 额外必读（见

reference.md

的"读取清单"）：

目标模块 / 子系统的代码入口和核心文件（由用户指认或你先 grep 后汇报候选让用户确认）
用户提供的素材（口述、散落文档、白板照片转述）
相关的 compound 沉淀（decision / explore / learning）
和本模块相关的已有 feature 方案
update 专项：当前版本文档全文 + 该文档
```
last_reviewed
```
之后的代码变更（
```
git log
```
粗扫）

check 额外必读（按子目标不同，详见

reference.md

）：

```
design-internal
```
/
```
design-vs-code
```
：方案 doc 全文 + 架构中心目录相关文档
```
design-vs-code
```
再额外：与 design 第 2/3 节直接对应的代码文件
```
architecture-folder-internal
```
：用户圈定的那几份
```
easysdd/architecture/**/*.md
```
（或某个 type 下的全部同类文档） + 索引 + 顺藤摸到的被引用文档（不扩展到代码）

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：执行

Phase 3: Execute

new / update 模式：按

reference.md

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

check 模式：按

reference.md

的"检查覆盖项"（三个子目标各 6 类）逐条执行。每条不一致都要记录可定位位置（

file:line

或

design 第X节

）+ 现象 + 影响 + 修复建议。

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：自查（new/update）或输出报告（check）

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

new / update：按

reference.md

的"自查清单"（7 条）就地跑一遍，发现问题就在交给用户 review 前处理掉（删掉 / 标 TODO / 改写）。自查结果简短汇报给用户——发现问题就说发现了、怎么处理，不要当成"走过场"隐形步骤。

check：按

reference.md

的"报告模板"输出完整报告，包含检查摘要 / 不一致清单（表格，带严重级别）/ 观察项（范围外）/ 一致性良好项 / 建议下一步。

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

Phase 5: User Review

new / update：把初稿完整贴给用户，提示 review。用户提意见就改，反复直到用户明确"这份 doc 可以了"。

check：报告给用户，等用户确认结论——是否接受、要不要再补一类检查、还是直接进入用户自己决定的下一步。本技能不替用户拍板。

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：落盘（new/update）或结束（check）

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

new 模式：

写入

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

（命名规则见

easysdd/reference/shared-conventions.md

第 0 节），frontmatter

status: current

、

last_reviewed

填当天

同类聚合检查（落盘前必跑）：按 shared-conventions 的"架构 doc 的分组规则"判断本次落盘后某个 type 在
```
architecture/
```
根目录是否达到 ≥6 份——命中阈值就把这类全部搬进
```
architecture/{type}/
```
子目录、去掉文件名前缀、同步改
```
DESIGN.md
```
所有相关链接；搬迁清单必须在 Phase 5 一并给用户 review
索引更新：打开
```
easysdd/architecture/DESIGN.md
```
加对新文档的引用链接——new 模式下必定要加，不加等于写了没人会读；DESIGN.md 改动同样给用户 review，不要偷偷改

update 模式：

覆盖已有文件，
```
last_reviewed
```
更新为当天
结构性改动大的话在文档末尾
```
变更日志
```
节加一条"YYYY-MM-DD：{一句话描述}"
DESIGN.md 只在 scope 或 summary 变化影响索引描述时更新

check 模式：不落盘，结束。用户可能基于报告决定触发

new

update

或别的工作流——那是下一轮的事。

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

只锚代码，不造系统（new / update）——每条结构化断言必须能锚到
```
file:line
```
；锚不到就标
```
TODO: 待确认
```
，不允许"根据命名推测"。
不替用户拍板决策（new / update）——关键决策节的实质内容必须来自用户或可追溯的 decision 文档。AI 只起草结构和串联语言。
只检查，不修复（check）——禁止改 design / 代码 / 配置。check 和修复分开做，用户才能看到完整不一致清单后整体决定优先级。
证据化（check）——每条不一致都要有可定位位置（
```
file:line
```
或
```
design 第X节
```
）。
可执行建议（check）——具体到"改哪里、怎么改"，但不落盘。
单目标（所有模式）——一次只跑一个模式，该模式内只锁定一个目标。
不改代码、不动 spec（所有模式）——本技能只写架构 doc 或出检查报告。发现代码 / 方案 doc / decision 有问题就记为"观察项"交给用户决定是否另开工作流处理。
不发散（所有模式）——用户描述的范围外问题一律不扩展，记成观察项即可。

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

所有模式共通：

已锁定单一模式和单一目标
用户明确 review 通过（new / update）或确认本轮检查结论（check）
没有顺手修改代码 / 方案 doc / decision 文档
没有范围外的额外文档改动

new / update 额外：

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

check 额外：

已完成对应子目标的检查项覆盖（见
```
reference.md
```
）
报告含不一致清单 + 修复建议
报告未包含任何实际修复动作

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

方向	关系
`easysdd-requirements` 配合	requirement 描述"为什么要有这个能力"、本技能描述"用什么结构实现"；architecture doc 的 frontmatter `implements` 反向链到承载的 req slug
`easysdd-feature-design` 上游	design 写到"本 feature 和哪块架构对接"时读本技能产出的 doc；design 写完后可触发 check 模式做一次自洽体检
`easysdd-feature-acceptance` 下游	验收阶段实际去更新本技能产出的 doc（acceptance 自己做归并，不回调本技能 new/update）；想确认实现和 design 对得上时触发 check 模式 `design-vs-code`
`easysdd-decisions` 配合	拍板一条架构决策后，本技能 `update` 可把引用补进相关架构 doc 的第 4 节
`easysdd-issue-analyze` 读者	根因分析阶段读本技能产出的 doc 定位模块边界
`easysdd-onboarding` 创建者	onboarding 阶段建 `DESIGN.md` 占位，之后由本技能填实 / 扩充

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

new / update 常踩的：

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

check 常踩的：

一次同时做多个子目标（design-internal / design-vs-code / architecture-folder-internal 只能选一个）

architecture-folder-internal

顺手读代码去验证——那是

design-vs-code

的事

发现问题就顺手改代码或文档
只说"这里不太对"，不给证据位置
建议过于抽象（"优化一下架构"）
从一个目标无限扩展到全仓库审计

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

Original

Translation

easysdd-architecture

easysdd-architecture

模式分流

Mode Diversion

单目标规则

Single-Target Rule

工作流骨架（三模式共用）

Workflow Skeleton (Shared by Three Modes)

Phase 1：锁定目标（所有模式）

Phase 1: Lock Target (All Modes)

Phase 2：读取材料

Phase 2: Read Materials

Phase 3：执行

Phase 3: Execute

Phase 4：自查（new/update）或 输出报告（check）

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

Phase 5：用户 review

Phase 5: User Review

Phase 6：落盘（new/update）或 结束（check）

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

硬性边界

Hard Boundaries

退出条件

Exit Conditions

和其他工作流的关系

Relationship with Other Workflows

常见错误

Common Mistakes

Phase 4：自查（new/update）或输出报告（check）

Phase 6：落盘（new/update）或结束（check）