用途
该技能用于在代码库中发现“架构加深机会”(deepening opportunities),即把浅模块重构为深模块,最终目的是提升可测试性和 AI 可导航性。它由项目的领域模型提供信息:领域语言为好的接缝命名,ADR 记录该技能不应重新争辩的决策。
术语约定
技能要求在每条建议中严格使用下列术语,避免漂移到“component”“service”“API”或“boundary”。完整定义见 LANGUAGE.md。
- Module — 任何具有接口和实现的东西(函数、类、包、切片)。
- Interface — 调用方使用该模块必须知道的全部内容:类型、不变量、错误模式、顺序、配置。不仅是类型签名。
- Implementation — 内部的代码。
- Depth — 接口处的杠杆:小接口背后承载大量行为。深 = 高杠杆。浅 = 接口几乎和实现一样复杂。
- Seam — 接口所在之处;一处无需就地编辑即可改变行为的位置(使用此词,而非“boundary”)。
- Adapter — 在接缝处满足接口的具体事物。
- Leverage — 调用方从深度中获得的收益。
- Locality — 维护者从深度中获得的收益:变更、缺陷、知识集中在一处。
关键原则
- 删除测试:设想删除该模块。如果复杂度消失,它只是直通模块;如果复杂度在 N 个调用方之间重新出现,则它确实有价值。
- 接口即测试面。
- 一个适配器 = 假设的接缝;两个适配器 = 真实的接缝。
使用方式(三步流程)
1. 探索
先阅读项目的领域词汇表以及你正在触及区域的任何 ADR。然后使用 Agent 工具(subagent_type=Explore)遍历代码库。不要遵循僵硬启发式,应有机地探索并记录你感受到摩擦的地方:
- 理解一个概念需要在许多小模块之间来回跳转的地方?
- 模块较浅、接口几乎和实现一样复杂的地方?
- 仅为可测试性而抽取纯函数,但真正的缺陷隐藏在它们被调用的方式中(缺乏 locality)的地方?
- 紧耦合模块跨越接缝泄漏的地方?
- 代码库中未测试、或通过当前接口难以测试的部分?
对任何怀疑是浅模块的对象应用删除测试:删除它会更集中复杂度,还是只是转移复杂度?“是的,会集中”是你想要的信号。
2. 呈现候选
呈现一个编号列表的加深机会。对每个候选说明:
- Files — 涉及哪些文件/模块
- Problem — 当前架构为何造成摩擦
- Solution — 将会发生什么变化的白话描述
- Benefits — 以 locality 和 leverage 解释,并说明测试将如何改进
领域部分使用 CONTEXT.md 的词汇,架构部分使用 LANGUAGE.md 的词汇。如果 CONTEXT.md 定义了 “Order”,就谈“the Order intake module”,而不是“the FooBarHandler”,也不是“the Order service”。
ADR 冲突:如果某候选与现有 ADR 矛盾,仅当摩擦足够真实、值得重新审视该 ADR 时才呈现它,并清楚标记(例如“contradicts ADR-0007 — but worth reopening because…”)。不要列出 ADR 禁止的每一个理论性重构。
此时不要提出接口。询问用户:“Which of these would you like to explore?”
3. 深入讨论循环(grilling loop)
一旦用户选定一个候选,进入深入讨论。与用户一起遍历设计树——约束、依赖、加深后模块的形态、接缝背后是什么、哪些测试能保留。
副作用随决策确定就地发生:
- 以 CONTEXT.md 中不存在的概念命名加深后的模块?将该术语添加到 CONTEXT.md——与 /grill-with-docs 相同的纪律(见 CONTEXT-FORMAT.md)。若文件不存在则惰性创建。
- 对话中澄清了一个模糊术语?就在那里更新 CONTEXT.md。
- 用户以承重理由拒绝该候选?提议一条 ADR,表述为:“Want me to record this as an ADR so future architecture reviews don't re-suggest it?” 仅当该理由确实是未来探索者避免重新提出同一建议所需要的,才提议;跳过瞬时的理由(“现在还不太值得”)和不言自明的理由。见 ADR-FORMAT.md。
- 想为加深后的模块探索替代接口?见 INTERFACE-DESIGN.md。
适用场景
适用于用户希望改进代码库架构、发现可重构的浅模块、提升代码可测试性或 AI 可导航性的情况。也适用于伴随领域术语和 ADR 维护的架构梳理工作。
限制
- 具体参数、配置项、安装方式等暂未提供。
- 该技能依赖 CONTEXT.md、LANGUAGE.md、ADR-FORMAT.md、CONTEXT-FORMAT.md、INTERFACE-DESIGN.md 等项目内文件,缺失时相关行为按文档所述惰性创建或参考。
- 收费方式、价格、平台支持情况暂未提供。