# Arch Guard

> Use when 编写、修改或重构代码，尤其是新增功能、跨模块变更、引入外部依赖、 文件或模块持续膨胀、职责混合、公共接口扩张，或涉及 package、crate、子系统与服务边界时。

- Skill: `mocikadev/arch-guard` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx skillmds@latest add mocikadev/arch-guard`
- Raw SKILL.md: https://api.skillmd.com/api/skills/mocikadev/arch-guard/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: mocikadev (https://skillmd.com/u/mocikadev)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/mocikadev/arch-guard

---


# arch-guard

在代码变更前后守护职责边界、模块划分和依赖方向。核心原则：选择与当前问题匹配的**最小充分架构**；既不把新职责继续堆入现有单元，也不为假想需求预建复杂抽象。

## 强制执行闭环

涉及代码变更时，依次执行，不得因任务“小”“赶时间”或用户只点名一个文件而跳过分级：

1. **初筛**：先完整读取 `references/change-levels.md`，按影响范围和架构风险判定 L0–L3。
2. **调查**：L0 只核对项目规则与目标位置是否确实不改变结构；L1–L3 再读取构建清单、目录、目标代码、相邻模块和测试，识别工作区结构与现有惯例。
3. **划界**：说明新增职责属于哪里，检查函数、类型、文件、模块、package/crate、子系统或服务中哪个层级能形成最小有效边界。
4. **决策**：优先沿用现有模式；比较内聚、耦合、依赖方向、状态所有权、测试边界和迁移成本后再决定是否拆分或抽象。
5. **实现**：存在需要独立演进或测试的稳定业务规则时，隔离 UI、协议、存储和网络等易变细节；简单固定实现不强造接口或适配层。保持公共 API 最小，不悄悄偏离已确认方案。
6. **验收**：运行测试与静态检查，并复核职责、边界、依赖、扩展性、可测试性和设计一致性。

## 边界判断

拆分依据是职责、变化原因、依赖和生命周期，不是行数本身：

- 每个单元应能用一句话说明“负责什么、不负责什么”。描述频繁出现“以及”“同时”“顺便”时，检查职责混合。
- 业务规则、用例编排、UI/接口、持久化、网络、状态和协议映射属于不同变化方向；可以协作，不得无边界混合。
- 先选择能真正隔离变化的最低层级；不得把“拆分”理解为只把大文件切成小文件。
- L2 新职责先判断能否自然进入现有内聚边界；形成独立变化原因时，优先建立一个可命名模块。只有内部再出现独立状态、依赖、生命周期或测试边界时，才继续拆分。
- 新边界必须明确公共能力、输入输出、错误语义、状态所有权、允许的依赖和独立测试方式。
- 当项目确有需要独立演进或测试的核心规则时，不让具体 UI、数据库、文件系统或第三方 SDK 类型穿透该边界；简单固定流程可以直接组合具体实现。

设计或调整边界时读取 `references/boundary-design.md`。涉及具体语言的 package、crate、workspace、project 或服务层级时，再读取 `references/stack-mapping.md`。

## 规模预警

以下为默认软预警，可被项目规则覆盖：

| 信号 | 必须执行的检查 |
|---|---|
| 文件约 300 行 | 是否存在多个变化原因 |
| 函数约 50 行 | 是否混合多个处理阶段 |
| 本次使目标文件增长约 20% | 是否出现可独立职责 |
| 单元出现 3 个以上明显职责 | 是否应提升边界层级 |
| 公共接口持续扩大 | 边界是否错误或泄漏实现 |

超过预警线不等于强制拆分，但必须说明保留理由。生成代码、声明表和测试数据等可合理豁免。文件很短也可能职责混乱。

## 童子军原则

遇到已有架构问题时：

- 不继续恶化本次直接触及的结构。
- 整理实现需求所必需的局部边界。
- 不借小需求擅自发动全项目重构。
- 系统性问题单独记录证据、影响和建议；大规模治理作为独立任务确认。

## 设计模式约束

先识别真实变化和耦合，再选择模式。采用模式时必须回答：

1. 它解决哪个具体问题？
2. 为什么函数、组合、枚举或现有结构不足？
3. 新增了什么复杂度？
4. 如何测试、替换或删除？

无法回答时，不使用该模式。

## 红旗：停止继续堆积

出现任一信号，暂停追加代码并重新划界：

- “为了少改文件，先都写在这里。”
- “先复制一份，以后再抽象。”
- 新逻辑需要跨层取状态、扩大公共接口或增加全局状态。
- 用 `utils`、`helpers`、`common` 掩盖无法命名的职责。
- 用事件总线、服务定位器或依赖注入容器掩盖错误依赖。
- 只移动代码，却不收紧接口、依赖和状态所有权。
- 一次 L2 变更新增多个结构单元，却无法逐一说明独立边界收益。
- 未读取构建清单和现有实现，就列出或引入一组“可能需要”的依赖。
- 因赶时间而省略 L2/L3 的架构说明或确认门禁。

时间压力只影响方案规模，不取消边界治理。

## 输出要求

- L0/L1：简短执行；发现异常则升级。
- L2：编码前给出架构摘要，默认可继续；存在明显不同的合理方案时先请用户选择。
- L3：提出 2–3 个方案与取舍，获得用户确认后才能实施。
- 完成前读取 `references/architecture-review.md`；无架构变化时压缩报告，有结构决策时说明边界、依赖、验证证据和遗留问题。

## 不要做

- 不只按行数机械拆分。
- 不默认创建多 crate、workspace、微服务或完整分层。
- 不创建没有明确职责的薄层和转发接口。
- 不为了“可扩展”实现尚无真实用例的扩展点。
- 不忽略项目既有架构、专项 Skill 和项目级规则；它们优先于本技能的通用建议。