ai-codebase-deep-modules

深层模块与快速反馈

将有意义的复杂性隐藏在契约之后，让调用方能够完成实际工作。 目标是在保留行为的同时降低认知和变更成本，而不是增加文件夹、 规定导出数量，或为每个函数都添加抽象。 Agent 的生产力提升只是一项待验证的假设，并非由目录结构证明的收益。

检查真实的变更路径

从任务出发，沿着相关入口追踪领域策略、 状态／数据所有权、副作用、调用方和测试。阅读实际依赖， 不要只看 README 中的架构说明。明确调用方必须了解哪些信息， 以及哪些需要协同修改的改动会反复出现。大文件也可能内聚；小型包装器也可能 泄露复杂协议。不要将代码行数等同于模块深度。

说明需要保留的行为、要消除的具体耦合或重复，以及最小的拟议边界。对于代码审查，给出可执行的发现。对于 实现请求，完成连贯的补丁和测试；不要停留在强制编写九个部分的架构计划上。只有在 需要作出重大设计决策时，才使用现有的计划资源。

围绕所有权设计契约

定义操作、输入／输出类型、错误、状态转换、资源所有权、 生命周期、权限以及并发／取消语义。将不变量放在拥有它们的模块中。区分外部边界处的 验证与已经验证过的内部值，避免到处重复防御性检查。

公开领域操作，而不是一堆内部实现或通用管理器。 公共入口可以是一种有用的约定，但若要适配类型、平台适配器、延迟加载或服务端／客户端边界， 采用多个有意设计的接口可能更合适。避免使用巨型根导出文件，以免改变导入副作用，或将仅供服务端使用的代码打包进客户端。 保留语言／框架实际的加载约定。

明确依赖方向。通过另一领域的公共契约形成直接的无环依赖，可能比新增事件总线更简单。只有在依赖／所有权问题确实需要反转时才采用依赖反转，只有在确实需要时间上的解耦时才使用事件。事件会带来投递、排序、幂等性和可观测性方面的责任；它们不会消除耦合。共享代码应真正为多个模块所用，而不是成为所有有争议类型的归宿。

强制执行并测试边界

编写 lint 规则前，请先阅读边界强制机制。 规则必须区分模块使用自身内部实现与外部使用方越界访问。通过每种受支持的导入写法／解析器， 测试允许和禁止的导入。文件名、all 和 grep 都只是约定／信号，并非通用的隐私或安全机制。

在公共边界创建行为测试，其中包括有意义的失败、空数据／边界数据、状态／重启，以及适用时的取消和并发场景。保留能够诊断重要算法的专项内部测试。 对实现自身调用顺序的模拟并不能证明其契约；测试桩返回未实现也不等于实现了领域行为。

先运行最快且相关的测试／lint／类型检查，再运行重构涉及的实际构建／集成路径。衡量反馈成本和正确性，而不是设定固定数量的模拟或文件。更完整的检查清单请参阅测试与反馈，并根据项目使用的工具和风险进行调整。

将重构作为一项连贯的变更

将现有的模块示例用作草图，而不是原样安装的脚手架。一起更新接口、实现、使用方、依赖规则和测试。不要创建兼容性别名、无用包装器、臆测的导出项，也不要在没有使用方契约要求时再实现一套方案。破坏性的数据／架构转换仍需明确的上线／恢复计划；移除源码兼容性并不意味着可以丢失数据。

旧的 scaffold_deep_module.py 已移除。它会将未经检查的名称插入路径／源码中，跳过已存在的文件，却报告这些文件已创建，并生成占位 API／测试，而不是有用的领域契约。请通过常规的审查补丁流程创建实际需要的文件。无需为了生成四个空文件而提供替代 CLI。

提供证据

说明边界、它隐藏了什么、允许哪些依赖，以及为何能减轻具体的变更负担。报告实际运行过的测试和未解决的集成风险。不要因为一个导入示例失败就声称架构得到了强制执行，也不要在没有对比任务测量的情况下声称 Agent 速度有所提升。明确说明项目特定的假设，避免进行一刀切的整洁架构重写。

引用路径相对于此已安装的技能，而不是目标项目的文件夹。作者基线审查日期：2026-09-13：https://agentskills.io/specification。