codebase-architecture-governance

代码库架构治理

使命

通过明确职责、所有权和依赖方向，让代码库更易于理解、修改、测试和扩展。减少意外复杂性，但不追求诸如文件最少、文件最短或最时髦的文件夹结构等过于简单的目标。

成功的结果应具备以下特点：

• 每条业务规则都有唯一的权威实现；
• 每个重要状态和领域概念都有明确的负责人；
• 模块边界易于理解且经过有意设计；
• 依赖沿着稳定的方向指向；
• 不存在过多不必要的包装器、兼容层、重复的架构，以及跨模块跳转；
• 测试能够保护重要行为和架构约束；
• 迁移计划可分批小规模实施和审查，并且易于回退。

何时使用此技能

在用户要求以下事项时使用此技能：

• 重新组织代码库或对其进行模块化；
• 减少代码蔓延、文件数量或架构复杂性；
• 决定文件应拆分、合并、移动、保留还是删除；
• 定义前端/后端模块边界；
• 建立目标文件夹结构或依赖规则；
• 审查重复的业务逻辑、兼容门面、透传层或循环依赖；
• 规划安全重构，且不改变产品行为；
• 创建仓库架构指南或架构测试。

操作模式

根据用户的指示确定所需模式。

1. 评估模式（默认）： 检查并报告；不要修改源文件。
2. 计划模式： 准备分阶段迁移计划，列出文件级操作和验证命令。
3. 实施模式： 仅在用户明确要求时进行更改。分批小规模处理，保持行为不变，运行可用的检查，并报告确切的变更路径。
4. 仅限架构模式： 聚焦于边界和依赖方向；不要假定用户希望清理代码或删除文件。

如果无法访问仓库，不要假装已检查过。只有在需要基于实际源代码得出结论时，才提供通用目标模型或请求提供仓库/存档。明确区分基于源代码的事实、推断和建议。

核心规则

1. 重构前先理解。 在建议结构调整前，先阅读仓库说明、架构文档、包清单、入口文件、测试设置、构建／打包配置和代表性代码。
2. 以证据为依据。 关于文件的判断应基于导入、导出、调用位置、符号引用、测试、配置、运行时发现机制和打包方式。文件名、文件年代、文件大小或没有明显导入，都不足以作为证明。
3. 区分事实与假设。 将发现标记为 confirmed、likely 或 needs investigation；条件允许时，注明路径和符号／行号。
4. 默认保留行为。 结构重构不得悄然改变领域规则、持久化数据、公共 API、请求／响应契约、用户可见流程或错误语义。
5. 避免过度拆分。 只有当模块确实包含不同职责、生命周期、所有者或测试接缝时，才进行拆分。不要仅为达到行数目标而创建文件。
6. 避免过度合并。 不要只为减少目录或文件数量而合并不同领域。接口稳定的小文件也可能很有价值。
7. 明确所有权。 每个领域实体、可变状态、验证规则、转换规则和业务操作都应有明确且唯一的权威所有者。
8. 约束共享代码。 共享／通用／工具模块可以依赖稳定的底层原语，但不能依赖特定功能模块。不要把 shared 当作所有权不明确内容的收容所。
9. 分离策略与机制。 业务决策应属于领域／应用逻辑；HTTP、CLI、UI、存储、AI 提供商和特定平台的细节应置于适配器或基础设施边界之后。
10. 追踪间接引用。 检查动态导入、延迟路由、反射、插件注册表、基于字符串的模块路径、依赖注入、生成代码、测试固件、CLI 入口、包导出和部署规则。
11. 保护高风险区域。 并发、持久化、架构迁移、算法、流式处理、拖放、碰撞检测、撤销／重做和状态同步都需要测试，并应在重构前进行小幅改动。
12. 仅在授权范围内更改。 请求提供建议并不意味着获准编辑。切勿盲目删除数据、迁移历史、锁文件、必需的生成代码或参考资料。
13. 优先采用可逆的批次。 避免在同一步骤中同时进行目录移动、API 重新设计、行为更改和大规模重命名。
14. 遵循仓库现状。 将本技能中的结构示例视为模式，而非必需目录。应复用现有且合理的边界，而不是为了形式统一而重命名。

术语

报告中应一致使用以下概念：

• 领域／模块： 职责明确且接口受控的内聚能力。
• 功能模块： 将 UI、本地状态、命令和特定功能类型归在一起的产品能力。
• 应用／用例层： 负责协调业务操作、事务和状态转换的编排层。
• 领域／核心层： 不应依赖交付机制的业务概念、规则和算法能力。
• 适配器／接口层： HTTP、CLI、桌面 IPC、MCP、消息队列或其他外部入口。
• 基础设施： 持久化、文件系统、网络客户端、提供商 SDK、时钟、日志记录及其他技术实现。
• 门面／兼容层： 为保留 API 或隐藏实现细节而维护的封装或重新导出。
• 规范路径／API： 迁移后预期使用的导入或调用路径。
• 状态所有者： 负责更改并验证特定可变状态的唯一模块。

工作流

阶段 1 — 建立仓库上下文

检查仓库根目录，并确定：

• 语言、框架、包／工作区边界和构建系统；
• 仓库指引，例如 AGENTS.md、CLAUDE.md、CONTRIBUTING.md 和架构文档；
• 运行时入口点、应用启动流程、公开导出内容和外部适配器；
• 核心数据模型、持久化格式、API、生成的资源和迁移；
• 测试、Lint／类型检查／构建命令及架构测试；
• 值得重点关注的高风险区域和应予保留的现有约定。

使用仓库清单和文档中的实际命令。不要自行编造命令。记录无法运行的测试／检查及其原因。

提交一份简短的基线摘要，并说明范围和证据局限。

阶段 2 — 梳理当前架构

在提出新架构之前，先绘制当前状态图。展示：

• 主要模块及其各自负责的内容；
• 入口点及其调用的应用服务；
• 核心数据模型，以及创建、更改、验证、持久化和序列化这些模型的模块；
• 共享依赖和横切工具；
• 有证据支持的循环依赖、依赖方向违规和重复路径。

当简单的 Mermaid 图能让关系更容易理解时，优先使用。针对不同关注点分别绘制图表，不要把所有内容塞进一张难以阅读的图中：

• 上下文／容器图或高层模块图；
• 重要模块的依赖关系图；
• 仅当关键运行时流程本身值得说明时，绘制其时序图／活动图。

不要为了装饰而绘图。每张图都应解答读者的一个具体问题。

阶段 3 — 定义模块职责和所有权

为每个主要模块撰写一句职责说明。然后明确：

• 它拥有什么；
• 它公开什么；
• 它可以依赖哪些模块；
• 哪些模块不得依赖它；
• 它不得重复维护哪些规则／状态；
• 如何测试它。

健康的边界通常具有较高的内部内聚性、精简稳定的接口，以及与无关模块的低耦合度。

优先按业务能力组织，再在每种能力内按职责组织文件。仅按技术文件类型（components/、utils/、types/、services/）组织，可能适合小型项目；但在大型产品中，这会把同一功能分散到许多互不相关的目录中。在能改善代码局部性的情况下，优先采用功能优先的组织方式，同时将真正共享的基础构件限制在受约束的共享层中。

阶段 4 — 选择合适的目标边界

根据观察到的技术栈灵活调整。不要将通用架构强加给所有项目。

通用后端模式

一种实用的逻辑依赖方向是：

接口／适配器 → 应用／用例 → 领域／核心

基础设施实现在有益时通过显式接口或注入的依赖进行调用。领域／核心不应导入 HTTP 框架、UI 代码、提供方 SDK 或文件系统细节。

可能的职责划分：

• **领域／核心：**实体、值对象、不变量、领域规则、确定性算法。
• **应用／用例：**协调领域操作、授权／确认策略、事务、验证顺序和结果处理。
• **基础设施：**持久化、文件、网络、模型／提供方客户端、时钟、日志记录。
• **接口／适配器：**HTTP／MCP／CLI／UI 桥接、输入／输出映射、传输专属错误处理。

如果抽象的 domain/ 或 application/ 层只是给现有代码换个名字，却没有建立有用的边界，就不要添加。边界清晰的现有核心可以保留其既有名称。

前端通用模式

分离以下内容：

• 应用框架和路由；
• 功能模块及其局部 UI／状态／命令／类型；
• 跨功能共享的应用级编排；
• 共享 UI 基元、传输客户端和稳定的跨功能契约。

大型前端可以采用如下结构：

src/
  app/                 # bootstrap, router, shell
  features/
    <capability>/      # UI, local model/state, commands, feature API
  application/         # cross-feature workflows and orchestration
  shared/
    ui/                # generic UI primitives only
    api/               # transport/client primitives
    contracts/         # intentionally shared contracts
    utils/             # pure, genuinely generic utilities

此结构仅供参考，并非必须达到的迁移目标。功能模块不得形成循环依赖。共享模块不得导入功能模块。只有在某个类型或辅助函数确实由多个模块共享，且其归属明确时，才将其移至 shared。

AI／Agent／工作流系统

如果系统中包含相关功能，应区分意图／输入解析、上下文或记忆、协调／决策支持、工作流编排和业务执行。Agent 可以提出建议或请求确认，但不得成为业务规则的第二套实现。保留有意义的工作流检查点，以支持确认、重试、可观测性和恢复。

可视化／编辑系统

对于复杂编辑器，应区分 UI 组合、领域／编辑器状态、渲染／场景生命周期、交互状态机、命令／历史记录，以及持久化／提交行为。不要仅按任意行数拆分有状态交互。明确选择、拖动状态、候选项放置、提交、撤销／重做和资源释放各自的唯一所有者。

算法或数据密集型系统

分离领域契约、输入规范化、算法实现、编排和序列化／适配器。保留确定性行为、约束、标识符、单位、旋转、排序规则和数值容差。不要让传输或文件格式相关问题渗入算法核心。

阶段 5 — 审核文件和模块

将每个候选项归为以下类别之一：

• KEEP：职责和边界合理。
• SPLIT：一个模块混合了不同职责或生命周期。
• MERGE：相邻文件承担相同且内聚的职责，彼此之间存在过多的传递调用。
• MOVE：归属明确，但文件位于错误的模块中。
• MIGRATE-THEN-REMOVE：迁移调用方并检查公开用法后，可移除兼容性导出／门面。
• DELETE：证据表明其已过时或未使用；在相关情况下，也包括已检查非静态引用。
• INVESTIGATE：现有证据不足以安全确定处理方式。
• ADD-BOUNDARY：添加小型接口、所有者模块或测试边界，因为当前职责彼此纠缠。

对于每个非平凡候选项，记录：

• 路径或模块；
• 当前职责；
• 拟议操作和目标所有者；
• 证据（引用、符号、测试或观察到的重复）；
• 置信度（confirmed、likely、needs investigation）；
• 风险（low、medium、high）；
• 前置条件和验证命令／测试；
• 适用时的回滚或兼容性说明。

绝不能仅根据文件大小、名称、时间戳或缺少明显的静态导入，就将文件归类为可删除。如果可能存在运行时发现机制，那么搜索结果为零只是证据，并非证明。

阶段 6 — 检查依赖和重复内容

对于高价值候选项，追踪：

• 双向导入和重新导出；
• 调用点和状态变更点；
• 重复的架构、类型、验证逻辑、转换逻辑和状态转换；
• 依赖循环和向上依赖；
• 公开导出、API 路由、插件／注册表发现、反射、延迟导入；
• 测试、测试夹具、脚本、构建、打包、部署和文档引用；
• 持久化数据及跨模块契约的所有权。

如有可用工具，优先使用支持语言感知的符号／引用工具或 AST 分析。先进行全仓库文本搜索，并说明搜索无法证明什么。

阶段 7 — 按价值和风险确定工作优先级

常见的高价值顺序（根据证据调整）：

1. 明确公共入口点和模块归属；
2. 找出重复的业务规则、架构漂移和多个状态所有者；
3. 删除已确认过时的产物和调试输出；
4. 将兼容性导出和透传逐步收敛到规范 API；
5. 合并分散的同一职责实现；
6. 将模块移至其所属的功能或领域；
7. 为确实承担多种职责的文件拆分模块，并在边界处添加测试；
8. 处理循环依赖并添加架构检查；
9. 更新图表和开发者文档。

大型文件是审查信号，并不意味着必须拆分。如果额外增加的文件能形成稳定接口、隔离生命周期、明确归属或提供实用的测试接缝，那么就值得增加。只有在删除小文件能消除实际的间接层且不削弱边界时，才值得删除。

阶段 8 — 制定渐进式迁移计划

分批进行，每批都明确一个不变量：

1. 建立或记录基线；
2. 针对要保留的行为，添加或完善聚焦测试；
3. 选择一个模块或关注点；
4. 将调用方迁移到一个规范 API；
5. 整合或迁移实现；
6. 仅在检查引用后才移除过时的间接层；
7. 运行聚焦测试并检查差异；
8. 在关键节点运行类型检查、lint、构建和更广泛的测试套件；
9. 更新架构文档；
10. 记录未解决事项和回滚步骤。

不要在一个批次中混合整个目录的重命名、公共 API 重新设计、业务规则更改和数据迁移。如果必须更改行为，请将其单独处理并明确记录。

阶段 9 — 添加架构护栏

在有价值的情况下，建议使用可强制执行的约束，例如：

• 功能模块之间不得相互导入，除非通过获批的公共 API；
• shared 不得从 features 导入；
• domain/core 不得导入传输层或 UI 包；
• 接口/适配器应调用应用服务，而不是重复实现用例；
• 只有一个模块负责写入特定状态或持久化实体；
• 兼容性导入应标记为弃用，并明确移除路径；
• 在适当的层级测试关键不变量。

使用项目现有的测试、lint 和导入工具。当一个简单测试或 lint 规则就足够时，不要引入重量级框架。

风险指南

通常在验证后风险较低：

• 过时的屏幕截图、本地调试输出、废弃的分析器文件；
• 调用方已迁移的纯重新导出文件；
• 有等效测试覆盖的重复纯工具函数；
• 文档链接和文件夹标签。

通常风险中等：

• 移动功能本地模块；
• 合并验证/转换逻辑；
• 更改公共导入路径；
• 将表现层与编排逻辑拆分；
• 重构 Agent 工作流子领域。

通常风险较高：

• 持久化架构或文件格式；
• ID 和跨阶段关系；
• 身份验证/权限或确认行为；
• 并发/流式状态、重试、持久化、撤销/重做；
• 优化算法和数值约束；
• 拖放/碰撞/3D 交互状态机；
• 通过插件加载或动态发现的模块。

风险取决于实际引用和测试；不要认为某个类别总是安全的。

必需的输出格式

用于架构评估

1. 执行摘要诊断： 复杂性的主要成因，而不只是表面症状。
2. 现状图： 主要模块、入口点、核心数据／状态的所有者、依赖方向。
3. 职责图： 每个主要模块的工作、公共接口和禁止依赖项。
4. 建议的目标结构： 与现有技术栈和当前代码相符的示例目录树。
5. 模块／文件决策表： 操作、依据、置信度、风险、建议目标位置、验证方式。
6. 依赖规则： 明确允许和禁止的依赖方向。
7. 分阶段迁移顺序： 规模小、可回退且具备前置条件的批次。
8. 行为不变量： 不得改变的流程、契约和状态转换。
9. 验证计划： 实际可用的测试／检查及成功标准。
10. 未知项： 需要追踪源代码或由用户决策的未解决事项。

用于文件精简请求

使用第 5 阶段的文件分类，并提供引用追踪依据。明确区分“待检查候选项”和“可安全删除项”。

用于实现任务

如果改动较大，先概述范围，再分小批次进行。最后报告：

• 新增／移动／修改／删除的文件；
• 职责／所有权变更；
• 已运行的测试和命令及其结果；
• 无法运行的测试／检查；
• 有意改变的行为（如有）；
• 剩余风险和回滚选项。

请结合实际代码仓库具体说明。避免脱离具体路径、符号、约束或已观察到的关系给出泛泛建议。

完成标准

满足以下条件即表示任务完成：

• 每个主要模块都有明确的职责和所有者；
• 重要数据／状态都有唯一权威所有者；
• 依赖方向和公共接口清晰易懂；
• 对重复实现和兼容路径都有明确决策；
• 删除操作有证据支持，而非凭猜测；
• 迁移拆分为便于审查的批次；
• 关键行为有测试覆盖，或明确标记为尚未验证；
• 如实报告验证结果和证据局限；
• 架构文档反映最终设计。

参考资料

准备交付内容时，请使用以下参考文件：

• references/module-map-template.md — 当前／目标模块职责图。
• references/file-audit-template.md — 逐文件操作与依据矩阵。
• references/refactor-plan-template.md — 分阶段迁移检查清单。