wyx Architecture Guardrails (Chinese)

wyx 架构护栏（中文版）

把模块边界写成规格，放在实现代码旁边，让 agent 在动手写代码之前就看见「什么可以碰、什么不可以碰」，并能定期核对规格是否已经和代码脱节。

这套方法只有两个动作：声明边界（写规格）和核对边界（查漂移）。规格是加法——覆盖的模块越多，护栏越密；从一个模块开始就有价值。

五种模式

从用户的说法判断模式，然后读取对应的参考文件再动手。参考文件是完整的执行程序，不要凭记忆执行。

模式名沿用上游 wyx 的命令名，便于与上游文档、ARCHITECTURE.md 里的提示互相对照；本技能里它们是模式，不是必须带斜杠的命令。用户说「wyx 审计」和用上游那条带斜杠的 audit 命令是一回事。

没有任何规格、也没指定模块时：先走 wyx:audit，让用户看到从哪里开始收益最大，而不是直接挑一个模块写规格。

三类规格与它们的分工

• CONCEPT.md —— 一个模块「是什么」：单一目的、自己拥有的状态、对外的动作、以及 ## interactions / ## dependencies 两段边界声明。
• PIPELINE.md —— 数据「怎么流」：来源、阶段、输出、运行时可断言的质量不变量，以及 ## data boundary 声明谁拥有输入输出数据。
• SYNCS.md —— 概念之间「怎么协同」：触发时机、数据流向、跳过条件、错误传播策略。CONCEPT.md 的 ## interactions 声明关系，SYNCS.md 描述执行机制。

三者的关系是：概念定义边界，管道在边界内保证数据质量，sync 负责跨概念的编排；架构地图是它们的合成视图，不参与护栏，只给人看。

规格放在哪里

规格必须紧贴它描述的实现代码。边界注入 hook 从被编辑文件所在目录向上走，在第一个含 CONCEPT.md 或 PIPELINE.md 的目录停下；SYNCS.md 会被列出但不终止向上查找。

src/lib/
├── orders/              # 一个概念 = 一个目录
│   ├── CONCEPT.md       # 本模块的边界声明
│   ├── service.ts
│   └── repository.ts
├── scoring/
│   ├── CONCEPT.md       # 边界
│   ├── PIPELINE.md      # 与概念同目录共存（安全）
│   ├── calculate.ts
│   └── aggregate.ts
└── syncs/
    ├── SYNCS.md         # 所有 sync 流写在同一个文件里（保持单文件）
    ├── order-to-inventory.ts
    └── order-to-scoring.ts

三个要避开的反模式：

• 根目录放 CONCEPT.md —— 它会成为所有子目录的兜底边界，把过宽的约束套到没有自己规格的模块上。
• PIPELINE.md 单独放在没有 CONCEPT.md 的子目录 —— 例如把它放进 scoring 的 transforms 子目录，会让向上查找停在 transforms 这一层；hook 能识别缺失的 CONCEPT.md 并带 [SHADOWED] 标注注入祖先边界，但这说明放置位置不理想。
• 拆分 SYNCS.md —— 协调图需要完整视图，局部图只会给出虚假的信心。

通用纪律

• 先给用户看，再落盘。 wyx:concept、wyx:pipeline、wyx:sync 都必须先呈现草案、征得同意才写文件；文件已存在时先给 diff。只有 wyx:map 例外（它完全派生自规格，可直接覆盖重写）。
• wyx:audit 全程只读。 它报告问题、输出该跑哪些命令，永远不产出规格文件。
• 漂移分两段。 第一段只做审计并呈现报告，第二段才在用户确认后改规格或改代码——不要把两段合成一步。
• 规格改了就提醒重画地图。 若项目里存在 ARCHITECTURE.md，在规格变更后提示用户跑 wyx:map。
• 既有模块优先「规格先行」。 已经有规格的模块，先改 ## actions / ## state 再改实现，这样边界注入立刻生效；回填模式（先代码后规格）只适合首次为存量代码建规格。

Agent 纪律

只在会改变路线时提问；用户已经说明或已确定的事实不要重复追问；上下文足够就直接推进；确实需要用户判断时，一次只问一个阻塞性问题。领域必需的澄清项（模块范围、要不要落盘、改规格还是改代码）仍然要问——但不要做成问卷。

边界自动注入运行时（可选）

本技能的规格与检查流程与 agent 无关，任何 agent 都能执行。而「每次编辑前后自动注入边界」是上游 wyx 的 Claude Code hooks 机制，脚本原样收录在 runtime/，未作任何改动。接线方式见 references/hooks-runtime.md。

没有这套运行时，规格依然有用（agent 按本技能主动读取规格、漂移检测照常工作）；有了它，边界会在每次写入前后被动送到模型眼前。

参考文件

来源与致谢

本技能是 jlifyio/wyx v0.26.0 的中文改写版，遵循上游 MIT 许可（见 LICENSE.upstream）。上游的思想来源：

• WYSIWID —— Meng & Jackson, "What You See Is What It Does"（MIT, Onward! 2025）：把概念规格与边界声明作为让软件可读的结构化手段。
• WYWIWID —— Dr. Ernie, "What You Write Is What It Did"：用漂移检测与数据管道不变量提供基于证据的可读性。