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。

规模预警

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

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

童子军原则

遇到已有架构问题时：

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

设计模式约束

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

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

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

红旗：停止继续堆积

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

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

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

输出要求

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

不要做

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