架构设计引导 Skill — 基于已验证方法论（决策框架、双向翻译、对变化下注、乘法架构、契约vs抽象），以硬门禁 + 两层级验证 + 进化回路机制约束 AI，产出带 ID 的可追溯工件与可直接交予 AI 编码的设计契约。
arch-design 是一个 AI 可加载的 Skill。它不是让 AI 替你画架构图，而是让 AI 引导你完成架构设计，并产出带 ID、可交叉引用、可机械核验的工件。
统一命题：判断不可机械化，但"判断的可审计性"可以机械化。门禁不裁决"判断对不对"，只裁决"判断有没有做、做没做足"。
工件结构化（带ID） → 硬门禁执法（Tier A机械 + Tier B判断） → 进化回路修法 → 设计契约桥接代码
- 硬门禁：G0-G9 设计域门禁 + G10-G14 生成评审门禁 + R-Gate 复盘门禁。每条含「机械判据/证据要求/通过条件/失败回退/豁免条款」，AI 必须粘贴证据原文才能过关，违反即强制回退。
- 两层级验证：Tier A 机械层检查工件的结构与关系（AI 跑查询贴证据）；Tier B 判断层检查决策实质（AI 留痕 + 用户主动挑战）。
- 进化回路：每次会话以复盘门禁结束，经验写入
_arch_evolution.md（仅收用户签收条目、反事实句式、反回声规则），下次加载为已知失败模式清单。 - 设计契约：产出独立契约文件（目录落点/接口签名/语义不变量/抽象映射/生成边界），约束 AI 编码不越权、不新增契约外抽象。
- 变化簇质量三检查：用"内聚/分离/泄漏"（在场景×单元共变矩阵上）替换原语数量硬约束；数量降级为绊线。
- 回验 L0-L3 分级：ADR 记录可证伪预言，业务变化真实到来时按 L0 预期内/L1 校准/L2 局部重构/L3 整体重构分级处置；"赌错了很便宜"。
- 黑板留痕：
_blackboard.md记录待深化点、开放问题、被否决项及理由（草稿可擦、理由不可擦）。 - 跨系统取经：五步流程（选源/收敛表/证伪/裁剪/落地）+ 血统过滤（趋同才算证据，同源是框架产物）。
- 框架调和：DDD/MVC/三层/Hexagonal 调和矩阵 + R1-R5 规则（参考章节，待实际验证）。
| 原则 | 说明 |
|---|---|
| 架构 = 决策框架 | 架构不是模块图、接口文档，而是决策及其 why；图是决策的影子 |
| 架构 = 双向翻译器 | 业务概念与技术模块之间建立双向可追溯映射 |
| 模块稳定性 = 对变化下注 | 边界能扛住需求变更；下注依据是业务驱动力，非代码相似度 |
| 减法 × 乘法 | 找 3-5 个领域原语（x），用组合覆盖所有场景；一对一实现是合法决策（当无 x 时） |
| 过度抽象 = 在变化簇没有分叉的地方画边界 | 画边界前必须做分叉分析 |
问题空间勘定 → 领域原语提取 → 变化推演 → 场景伪代码 → 四层交付物 + 设计契约
(S表/T表) (P表/触发源) (C表) (PC) (D/F/A/PC + 门禁)
每个阶段统一四段式：输入 / 活动 / 产出（带 ID 工件）/ 出口门禁。
npx skills add pionxe/arch-design-skill -g-g 全局安装到 ~/.agents/skills/，所有兼容 agent（Claude Code、Codex、ZCode 等）均可自动加载。
git clone https://github.com/pionxe/arch-design-skill.git ~/.agents/skills/arch-design
ln -s ../../.agents/skills/arch-design ~/.claude/skills/arch-design/arch-design
AI 会引导你经历五个阶段，每阶段出口有硬门禁：
- 勘定问题空间 — 场景表 S + 词汇表 T（纯业务语言）→ G1/G2
- 识别领域原语 — 原语表 P + 触发源表（老板测试+变化触发源）→ G3/G4
- 推演变化与边界 — 变化推演表 C（边界裁决）→ G5
- 设计场景伪代码 — 伪代码 PC（名词解析）→ G6
- 产出交付物 — 目录 D + 契约 F + ADR + 伪代码 → G7/G8/G9
真实使用后可让 skill 做代码生成评审（G10-G14），并跑复盘门禁（R-Gate）驱动 skill 进化。
| 层级 | 产出 | 说明 |
|---|---|---|
| 1 | 目录树 D | 两级结构：业务域 → scenario/shared/infra（shared 拆 primitives/utils） |
| 2 | 接口契约 | 业务语言签名，标注契约/抽象角色（N×1 vs 1×N） |
| 3 | ADR | 背景/决策/原因/代价/替代方案/不可逆性等级 |
| 4 | 场景伪代码 PC | ≤50 行/场景，名词可解析到词汇表/原语 |
| 5 | 设计契约 F | 独立文件，约束 AI 编码的生成边界 |
arch-design-skill/
├── README.md # 本文件
├── SKILL.md # Skill 本体（AI 加载）
├── LICENSE # MIT
├── CHANGELOG.md # 版本记录
└── examples/
└── example-session.md # 示例对话流程
- 新项目启动时的架构设计
- 新增业务模块前的边界推演
- 重构前的模块职责梳理
- AI 辅助编码前产出设计契约，约束生成
- 团队架构对齐（产出 ADR 可传承）
MIT © pionxe