Concitech AI · 深度长文
2026/10/04 07:05
AI重构大模块：删掉这个模块会怎样？
Matt Pocock的codebase-design是一份代码设计词典。七个术语和四条原则帮助开发者识别空壳抽象，审查接口、测试位置与模块职责。仓库另有代码库巡检技能。
AI写代码的速度提高，代码库里的抽象数量增加。一个文件叫PaymentService，另一个叫PaymentManager。两者各有接口，方法负责参数转发。删除哪一层？开发者与AI缺少共同的判断依据。
Matt Pocock的原推文提出一个任务：寻找浅模块，做“删除测试”，列出删除候选。Viking的转述强调一份名为/codebase-design的词典：它定义module、interface、depth、seam、adapter、leverage与locality，帮助AI讨论大模块重构。
对应的GitHub仓库是mattpocock/skills。仓库原文给codebase-design的定位是设计参考。它缺少扫描或改写代码的执行流程。寻找重构候选属于另一项技能improve-codebase-architecture的职责。两个名字接近，工作不同。
七个词，解决“接口”这个词的误会
仓库的codebase-design原文给module下了宽口径定义：函数、类、包、跨层级代码均可构成模块。模块由interface与implementation组成。interface超出TypeScript的interface关键字和函数签名。调用者需要知道的约束、调用顺序、错误模式、配置与性能特征，构成接口的内容。
depth是接口的“杠杆率”：调用者学会一小块接口，获得多少行为。大接口配薄实现，产生浅模块；小接口承载大量行为，构成深模块。leverage是调用者得到的收益。locality是维护者得到的收益：改动、错误和验证工作集中一处。
seam指行为替换的位置，adapter是符合该位置接口的具体实现。仓库选择seam，避开含义多重的“boundary”；它选择module，避开含义含混的“service”。这些词的价值来自讨论对象的精确性。
统一词汇带来具体收益。团队提出“这个service需要拆分”，讨论对象含糊；团队提出“这个模块的接口暴露了三个内部依赖”，问题获得具体形状。
删除测试：空壳抽象还是有效封装
设想一个订单计价场景。PriceService公开三个方法：取折扣、取税额、做货币换算。每个方法调用另一个同名方法，参数和异常留给上层处理。三个调用方需要知道折扣、税额与汇率的执行顺序。这个模块的接口复制了内部依赖。
删除PriceService，转发层消失，调用方的知识负担维持原状。这是浅模块的信号。
另一个设计公开quote(order)。模块内部处理折扣顺序、税额计算、汇率与舍入规则，返回金额明细。结算页、发票任务与测试面对同一个接口。删除这个模块，这些规则散落到多个调用方。它通过了删除测试。
删除测试的判断点是复杂度的去向：模块消失，复杂度消失，还是复杂度扩散到调用方？
四条原则，各自检查一个盲点
第一，深度属于接口。代码行数与模块深度是不同指标。深模块的实现由多个小函数组成。调用者面对的是外部接口。
第二，删除测试检查模块的存在价值。转发层消失，工作量下降；有效封装消失，调用方复制规则。
第三，接口是测试入口。测试断言内部状态或私有步骤，重构便会牵动大量测试。仓库建议测试面向模块接口与可观察结果。
第四，一个adapter对应假设中的seam；两个有正当理由的adapter支撑真实seam。生产环境的远程实现和测试中的内存实现构成一组。缺乏变化需求的额外接口增加转发层。
这四条原则是设计检查表，缺少自动裁决能力。真实系统有兼容性、部署与团队协作约束。仓库的补充文件把依赖分为纯内存、可用本地替身、团队自有远程系统和第三方系统。不同依赖需要不同测试方案。
项目定位与使用方式
codebase-design提供词汇与审查问题，缺少“扫描全库—提交补丁”的执行流程。improve-codebase-architecture的说明给它的定位是代码库巡检：生成候选报告，用户挑选问题，重构属于后续工作。原推文的“找浅模块”任务适合这个巡检流程，codebase-design负责定义判断标准。
仓库README提供安装入口：npx skills@latest add mattpocock/skills。安装器允许选择技能。了解方法的读者可读项目主页和codebase-design原文。阅读资料保持项目原状。
AI重构的难题是模块职责。调用方需要知道多少？“删除测试”给这个问题一把尺。那层代码的消失产生两种结果：复杂度消失，或者复杂度扩散。结果揭示模块的存在价值。
