Vibe Coding 垂直模块边界：按用户能力切分可替换实现

原型早期常出现 components/、services/、hooks/、utils/ 四个大目录。Agent 新增“取消订单”时，会在每个目录各加一个文件，再从页面直接调用数据库 SDK。结构看似整齐，业务边界却不存在：任何修改都要跨层搜索，测试只能启动整套应用，未来更换传输或存储时也找不到唯一接缝。

垂直切片把同一用户能力的规则、用例、端口、适配器和界面放在可识别边界内。它不是规定所有项目都采用同一目录，而是要求依赖方向和公开入口可由工具检查。仓库依赖图驱动的改动规划负责计算影响闭包，本篇先让图中出现可靠的模块节点。

从用户能力而不是技术名词命名

先列系统承诺的能力，如 checkout、team-invitation、article-review，再为每个能力定义 owner、输入事件、输出结果、业务不变量和持久化需求。database、api、common 不是能力，无法说明一次需求属于哪里。真正跨域的身份、审计或通知，也应以明确服务合同出现，而不是放进无限增长的 shared/utils。

一个 TypeScript 切片可以采用如下形态，具体目录名服从现有仓库：

features/article-review/
  domain/          # 状态与不变量，不导入 Web 或数据库 SDK
  application/     # 用例与所需端口
  adapters/        # HTTP、数据库、队列实现
  ui/              # 页面和交互适配
  public.ts        # 唯一跨模块入口
  tests/

依赖方向由外向内：UI 与 adapter 可以依赖 application，application 依赖 domain 和抽象端口，domain 不依赖框架。不是每个小功能都要拆成独立 package；在单仓目录内也能先执行相同规则。规模扩大、构建隔离确有收益时，再利用 TypeScript Project References 将边界提升为编译单元。

公开端口控制跨模块调用

切片只从 public.ts 或 package exports 暴露必要命令、查询和事件类型。其他模块不能深层导入 adapters/database.ts，也不能直接写对方的数据表。Node 的 package entry points 可以限制可加载子路径，但单靠约定不够；lint、构建图或 Nx module-boundary 规则要让违规导入在 CI 失败。

端口表达业务需要，不复制供应商 API。例如用例依赖 ArticleReviewStore.load(id) 与 save(review, expectedVersion)，而不是暴露完整 ORM client。这样内存 adapter、测试替身和真实数据库实现共享同一语义，并能表达并发版本。端口不应变成囊括所有表的 Repository，否则只是把耦合藏在一个大接口里。

跨切片同步调用只返回对方承诺的公开结果；异步事件要有稳定名称、版本、幂等键和失败处理。公共 schema 的变化先走 expand-migrate-contract，再删除旧字段。Agent API 契约兼容门可以验证消费者组合；不能让 Agent 同时修改生产者、消费者和测试，随后用共同错误获得绿色。

把 Agent 的任务限制在一个影响闭包

给 Agent 的任务包包含目标切片、允许读取的相邻公开端口、验收样例和禁止路径。先让它输出依赖计划，再写代码。若实现需要跨边界访问内部文件，必须说明缺失的公开能力，由 owner 决定扩展端口还是调整设计；不要自动放宽路径权限。

编程 Agent 的仓库地图应标出每个切片入口、运行入口、生成源和测试命令。完成后将实际 diff 与计划比较，出现新跨切片边、循环或 shared 新增业务规则即停止评审。对自动大规模移动文件的情况，沿用AST Codemod 重构不变量，证明 symbol 绑定、语义和第二次运行零差分。

模块测试分三层。domain 测不变量与状态转换，不启动网络；application 用手写 fake 证明端口交互和失败语义；adapter 对真实基础设施或协议运行契约测试。端到端测试只覆盖关键用户路径，不能成为唯一证明。这样一次规则修改可以在窄范围快速反馈，而 adapter 更换仍有共享契约守住行为。

从现有横向目录渐进迁移

不要让 Agent 一次搬完整个仓库。先选一个频繁变更且边界相对清楚的能力，建立公开入口；旧代码通过兼容 adapter 调用它。随后把调用方迁到入口，监测深层导入归零，再删除旧路径。每阶段都能独立构建和回滚，循环依赖则先用接口或事件打断。

迁移门可以检查：目标切片以外的计划外修改为零；禁止依赖为零；公开导出有契约测试；domain 不导入框架；跨模块类型只从公开入口获得；未解释的动态加载为零。最终证据纳入编程 Agent 的改动验证门。

垂直切片的目标不是追求目录审美，而是让一次用户能力的修改拥有明确 owner、有限影响范围和可替换外部实现。Vibe Coding 可以继续快速生成代码，但每段代码必须落到一个能说清依赖与验收方式的边界里。