cs-arch

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

cs-arch

codestable/architecture/

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

architecture 是累积的、自给自足的系统地图。它不是某一次 feature 的详细方案，而是所有已落地 feature 沉淀下来的"系统现在长什么样"的总图。读者打开它应该能看懂系统整体结构，而不需要频繁跳回某份历史 design 才能补齐理解。design 是临时的增量详细稿，架构里稳定下来的名词 / 编排 / 约束由 acceptance 阶段提炼回这里；design 文件本身归档，只在追究具体决策细节时才翻。

architecture 只记现状，不记计划。默认只在 feature-acceptance 阶段跟着代码同步更新，必要时才由本技能主动 new / update。不写"未来会加什么层"、"下一步打算拆出 X 模块"——那些属于

cs-roadmap

的规划层。用户抛出"我想重构成 X 架构"这种目标态描述时，先走 roadmap 拆成若干 feature，每次 feature acceptance 把实际达到的阶段性结构提炼回 architecture。

这意味着 architecture 的详略判据是"够不够让读者不跳转就读懂系统"——不是"写得越少越好"，也不是"把 design 里所有细节都搬过来"。系统里稳定、跨 feature 可见的那一层要写全；某个模块内部的循环、辅助函数、一次性实现决定不进来。

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

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

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

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

codestable/architecture/

is the "map" of the project — read it to locate before writing feature-design plans, understand module boundaries when conducting issue-analyze for root causes, and new team members read it to grasp the general structure 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.

Architecture is an accumulated, self-sufficient system map. It is not the detailed plan for a single feature, but an overall map of "what the system looks like now" accumulated from all delivered features. Readers should be able to understand the overall system structure without frequently jumping back to historical design documents to fill in gaps. Design documents are temporary detailed incremental drafts; stable terms, orchestration, and constraints refined from the architecture are incorporated back here during the acceptance phase; design files themselves are archived and only referenced when investigating specific decision details.

Architecture only records the current state, not plans. By default, it is only updated in sync with code during the feature-acceptance phase; active

new

update

via this skill is only done when necessary. Do not write "what layers will be added in the future" or "plan to split out module X next" — those belong to the planning layer of

cs-roadmap

. When a user proposes a target-state description like "I want to refactor to X architecture", first break it into several features via roadmap, then refine the actual phased structure achieved after each feature acceptance back into the architecture.

This means the criterion for the level of detail in architecture documents is "whether readers can understand the system without jumping" — not "the fewer words the better" nor "moving all details from design documents here". Stable, cross-feature visible layers of the system should be fully documented; internal loops, helper functions, and one-time implementation decisions within a module are excluded.

The value of architecture documents lies in accuracy, stability, and searchability. Several common issues when AI writes or reviews 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 — quietly 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" without explaining "why it's divided this way", resulting in the same amount of information as
```
ls -R
```
.
During checks, "it looks okay at a glance" — no specific location evidence is provided, leaving users unable to judge if it is truly okay.

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

See
codestable/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 user input, no menu selection required:

User Input	Mode
"Fill in an architecture doc", "Draft the architecture document for {module}", "Write down this structure"	`new`
"Refresh {document}", "The code has changed, sync the architecture doc", "Update the architecture directory to the latest"	`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 the mode cannot be determined, ask the user instead of guessing.

单目标规则

Single-Target Rule

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

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

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

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

```
new
```
: Draft a new architecture document (
```
codestable/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-objectives
- ```
design-internal
```
  — Consistency within a single feature design document
- ```
design-vs-code
```
  — Consistency between a feature design and code
- ```
architecture-folder-internal
```
  — Consistency among multiple architecture documents under
```
codestable/architecture/
```

Why is doing multiple things at once not allowed? When drafting, AI generating multiple documents at once makes it impossible for users to review thoroughly; during checks, the three sub-objectives have completely different perspectives and reference materials, doing them simultaneously leads to superficial checks and unclear responsibility for mixed issues. If the user proposes multiple targets, ask them to choose one and leave the rest for later.

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

Workflow Skeleton (Shared by All 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 follow six phases, with details diverging based on the mode:

Phase 1: Lock Target
Phase 2: Read Materials
Phase 3: Execute (new/update = draft; check = inspect)
Phase 4: Self-Inspection (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-objective + inspection target (feature name / architecture sub-scope)
Scope covered this time (entire document / specific sections / specific documents)

If the scope is not converged, ask the user to narrow it down — rewriting an entire module in an architecture document often means there are multiple relatively independent subsystems underneath, which should be split into separate tasks; a check covering the entire

architecture/

directory will result in a report that is hard to focus on.

Phase 2：读取材料

Phase 2: Read Materials

共同必读：

codestable/reference/shared-conventions.md

```
codestable/architecture/DESIGN.md
```
（总入口）
```
codestable/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
```
：用户圈定的那几份
```
codestable/architecture/**/*.md
```
（或某个 type 下的全部同类文档） + 索引 + 顺藤摸到的被引用文档（不扩展到代码）

Mandatory reading for all modes:

codestable/reference/shared-conventions.md

```
codestable/architecture/DESIGN.md
```
(main entry point)
Other architecture documents under
```
codestable/architecture/
```
(to judge whether to reference each other or if there are duplicates)

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

reference.md

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

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

reference.md

for details):

```
design-internal
```
/
```
design-vs-code
```
: Full text of the plan doc + relevant documents in the architecture center directory
```
design-vs-code
```
additionally: Code files directly corresponding to sections 2/3 of the design
```
architecture-folder-internal
```
: Specific
```
codestable/architecture/**/*.md
```
documents circled by the user (or all documents of the same type under a certain type) + index + referenced documents found via tracing (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 modes: 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 — contradictions often exist between the structure described in section 2 and the decisions recorded in section 4, which can only be detected when viewed together.

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

reference.md

(6 categories for each of the three sub-objectives). 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-Inspection (new/update) or Output Report (check)

new / update：按

reference.md

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

check：按

reference.md

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

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

reference.md

on the spot, and fix issues before submitting to the user for review (delete / mark TODO / rewrite). Briefly report the self-inspection results to the user — if issues are found, state what was found and how it was 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, whether to add another type of check, or proceed to the next step decided by the user. This skill does not make decisions on behalf of the user.

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

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

new 模式：

写入

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

（命名规则见

codestable/reference/shared-conventions.md

第 0 节），frontmatter

status: current

、

last_reviewed

填当天

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

update 模式：

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

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

new

update

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

new mode:

Write to

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

(see section 0 of

codestable/reference/shared-conventions.md

for naming rules), fill in frontmatter

status: current

and

last_reviewed

with the current date

Aggregation check for similar documents (mandatory before finalization): Judge whether the number of documents of a certain type in the root directory of
```
architecture/
```
reaches ≥6 after this finalization according to the "Grouping Rules for Architecture Docs" in shared-conventions — if the threshold is met, move all such documents to the
```
architecture/{type}/
```
subdirectory, remove the filename prefix, and synchronize all relevant links in
```
DESIGN.md
```
; the relocation list must be reviewed by the user in Phase 5
Index update: Open
```
codestable/architecture/DESIGN.md
```
to add a reference link to the new document — this must be done in new mode; without it, 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
Only update DESIGN.md if changes to scope or summary 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 it cannot be anchored, mark it as
```
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 the user or traceable decision documents. AI only drafts the structure and connecting language.
Only inspect, do not repair (check) — prohibit modifying design / code / configuration. Separate inspection and repair 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 modify and how to modify", 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 docs / decisions, record them as "observation items" and leave it to the user to decide whether to start another workflow.
Do not diverge (all modes) — do not expand to issues outside the user's 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 inspection conclusion of this round (check)
No code / plan docs / decision documents have been modified without permission
No additional document changes outside the scope

Additional for new / update:

The self-inspection list in
```
reference.md
```
has been run through item by item, and the processing results have been reported
Document frontmatter is complete, with
```
doc_type: architecture
```
,
```
status
```
, and
```
last_reviewed
```
all filled in
Each structured assertion is either anchored to
```
file:line
```
or marked as
```
TODO: To be confirmed
```
Before finalization, it has been judged whether similar documents reach ≥6 according to the "Grouping Rules", and if the threshold is met, the relocation list has been reviewed by the user
new: A link to the new document has been added to
```
DESIGN.md
```
(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 inspection items corresponding to the sub-objective 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

方向	关系
`cs-req` 配合	requirement 描述"为什么要有这个能力"、本技能描述"用什么结构实现"；architecture doc 的 frontmatter `implements` 反向链到承载的 req slug
`cs-feat-design` 上游	design 写到"本 feature 和哪块架构对接"时读本技能产出的 doc；design 写完后可触发 check 模式做一次自洽体检
`cs-feat-accept` 下游	验收阶段实际去更新本技能产出的 doc（acceptance 自己做归并，不回调本技能 new/update）；想确认实现和 design 对得上时触发 check 模式 `design-vs-code`
`cs-decide` 配合	拍板一条架构决策后，本技能 `update` 可把引用补进相关架构 doc 的第 4 节
`cs-issue-analyze` 读者	根因分析阶段读本技能产出的 doc 定位模块边界
`cs-onboard` 创建者	onboarding 阶段建 `DESIGN.md` 占位，之后由本技能填实 / 扩充
`cs-roadmap` 配合	architecture 记"系统现在长什么样"，roadmap 记"接下来打算怎么把它推到下一步"。roadmap 起草时会读本技能产出的 doc 理解现状，但不改它；"目标态架构"属于规划，不进 architecture doc

Direction	Relationship
Collaboration with `cs-req`	Requirements describe "why this capability is needed", this skill describes "what structure is used to implement it"; the frontmatter `implements` of architecture docs links back to the req slug it supports
Upstream of `cs-feat-design`	When writing "which part of the architecture this feature integrates with" in design, read the docs produced by this skill; after design is completed, the check mode can be triggered to conduct an internal consistency health check
Downstream of `cs-feat-accept`	During the acceptance phase, actually update the docs produced by this skill (acceptance does the merging itself, does not call back this skill's new/update); trigger the `design-vs-code` sub-objective of check mode to confirm alignment between implementation and design
Collaboration with `cs-decide`	After an architecture decision is finalized, this skill's `update` can add references to section 4 of relevant architecture docs
Reader of `cs-issue-analyze`	Read the docs produced by this skill to locate module boundaries during root cause analysis
Creator of `cs-onboard`	Create a placeholder `DESIGN.md` during onboarding, then fill it in / expand it via this skill
Collaboration with `cs-roadmap`	Architecture records "what the system looks like now", roadmap records "how to push it to the next step". When drafting the roadmap, read the docs produced by this skill to understand the current state, but do not modify it; "target-state architecture" belongs to planning and is not included in architecture docs

常见错误

Common Mistakes

new / update 常踩的：

把"打算重构成什么样"写进来：architecture 是现状档案，目标态结构归 roadmap 规划层
凭空造系统：文档里出现了一个代码里并不存在的"协调层 / 中枢 / 管理器"
替用户拍板架构决策：关键决策节里的选型理由其实是 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 mistakes in new / update:

Writing "what it will be refactored into": Architecture is a current-state archive; target-state structure belongs to the roadmap planning layer
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 cannot see cross-section contradictions, leading to superficial review
Term conflicts: Newly introduced names conflict with existing ones in code / other architecture docs / compounds without awareness
Writing / modifying multiple documents at once: Cannot be reviewed thoroughly, resulting in rough integration of all contents
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 without code basis in update mode: Just "reads more complete", which is the start of content deviating from reality
Modifying code / plan docs along the way: Overstepping boundaries, this skill only modifies architecture docs
Continuing to place documents in the root directory when similar documents reach ≥6: Triggering the grouping rule but not relocating
Filename does not follow
```
{type}-{slug}.md
```
: Similar documents cannot be aggregated in the future, making the grouping rule ineffective

Common mistakes in check:

Doing multiple sub-objectives 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 is the task of
```
design-vs-code
```
Modifying code or documents immediately when issues are found
Only saying "something is wrong here" without providing evidence location
Suggestions are too abstract ("optimize the architecture")
Expanding infinitely from one target to full repository audit

cs-arch

Original

Translation

cs-arch

cs-arch

模式分流

Mode Diversion

单目标规则

Single-Target Rule

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

Workflow Skeleton (Shared by All 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-Inspection (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）