improve-codebase-architecture

改进代码库架构

依据 ../coding-standards/SKILL.md 执行一次架构扫描。返回一份按优先级排序的重构候选清单，候选项必须位于扫描边界内。

扫描，而非编写规格。 只推进到有证据支持的归属调整。不要编辑文件、执行重构、更新文档、创建 ADR、估算工作量、设计最终接口或编写技术规格。只有在仓库证据或用户意图支持的情况下，才记录迁移、兼容性、发布或回填方面的现有限制；扫描过程中不要设计这些事项。

1. 确定扫描边界

使用用户提供的范围：仓库、目录、功能、模块、文件集或关注点。边界决定了可以提出哪些候选项。必要时检查边界外的直接调用方、依赖、组合根和测试，以收集证据；记录这一证据范围，但不要为其提出候选项。

如果用户未提供有用的范围：

1. 检查仓库结构和主要入口点。
2. 仅当仓库规模较小或某个区域显然是请求重点时，才推断扫描范围。
3. 否则，提出一个问题，让用户选择范围。

阅读 ../coding-standards/SKILL.md。从边界及其祖先目录开始，一直搜索到仓库根目录，查找 CONTEXT.md、CONTEXT-MAP.md、同类领域语言文件和决策索引。搜索仓库文档和 ADR 集合，查找提及或约束该边界的决策。检查找到的所有约束来源，以及范围内代码、测试和证据范围中的先例。

完成标准： 已明确候选项边界和任何证据范围；已加载编码规范；已搜索指定的上下文和决策位置；已检查所有找到的约束来源；并且已识别相关先例，或记录其缺失。

2. 构建证据图

仅使用文件读取和搜索。不要运行测试、类型检查、代码检查、格式化工具、构建、包脚本或静态分析命令。

在边界范围内，私下构建一份证据图，梳理各架构层面：

• 公共入口和运行时入口；
• 领域模块与应用模块集群；
• 外部边界、持久化边界和进程／运行时边界；
• 副作用和资源生命周期的所有者；
• 测试这些接缝的测试用例。

将每个项目视为一个清单类别。对于每个类别，记录其层面、等效分组，或说明其不存在或不适用并给出理由。仅在层面具有相同的所有权和调用流形态时才将其分组，并记录该组的代表性文件。

对于每种不同的形态，至少追踪一项行为：从入口或直接调用方出发，经过相关边界和副作用（如有），直至调用方可见的结果。检查该接缝处现有的测试，或记录未找到测试。记录相关层面或分组、代表性文件、调用路径、结果、现有测试证据、适用标准和发现。

以证据为准，不凭感觉。 检查架构摩擦：重复出现、跨越边界、泄漏到调用方、模糊所有权，或妨碍通过真实接缝测试行为的设计负担或正确性风险。孤立的代码异味属于局部清理，不是架构候选项。

对于本次扫描，当清单中的层面处理某项原则所约束的问题时，该编码标准原则即适用；先检查仓库再作判断始终适用。内部逐条处理每项编号原则：

• 将其分类为适用或不适用；
• 对每项适用原则，记录检查过的具体代码、调用路径、测试、值或运行时接缝；
• 将每项发现分类为局部清理或架构摩擦。

对于大范围扫描，可以并行探索以收集观察结果，但候选项的最终形成和排序必须由一次综合分析完成。

完成标准： 每个清单类别都已追踪、记录为等效分组，或说明不存在或不适用并给出理由；已记录每次证据范围的延伸探索和有意排除项；已逐条处理每项编号标准；每项适用标准都有经过检查的证据；每项保留的观察都属于具体的架构摩擦。没有证据支持的观察应予以舍弃。

3. 整理、排序并筛选候选项

架构变更会改变某项不变量、策略、转换、编排、副作用、资源生命周期或运行时协调由谁负责。将每项保留的摩擦点转化为一项所有权转移，从当前所有者或调用方转移到拟议所有者。不要设计该所有者最终的接口。

在整个扫描范围内统一对所有候选项排序，而非按标准类别排序。按架构杠杆效应排序：相对于引入的接口、间接层或机制，所消除的具体负担或风险的广度与影响。考虑受影响的调用方、行为、运行时所有权和测试。杠杆效应相当时，优先选择证据更充分的候选项，其次选择更小且完整的所有权转移。

合并解决相同根本摩擦或需要相同所有权转移的候选项；将次要的标准改进视为更强候选项带来的收益。剔除审美性改进、缺乏证据、与可靠的本地惯例相矛盾、对灵活性的推测、孤立的清理工作，或伪装成架构工作的实现任务。最多保留五个候选项；如果没有候选项达到证据门槛，则保留零个。

一致使用推荐强度：

• Strong — 具体证据支持该摩擦点、所有权转移和杠杆效应；
• Worth exploring — 有证据支持该摩擦点，但所有权转移或杠杆效应取决于一项尚未核实的准确说法。

不要用 Worth exploring 推迟可以进行的检查。先通过许可的读取和搜索核实所有可验证的说法；仅当所需证据无法通过源码检查获得时，才保留证据缺口。

完成标准： 每个保留的候选项都指出具体摩擦点、从当前所有者到拟议所有者的所有权转移、杠杆效应依据、现有测试证据、验证切入点和推荐强度；每项不确定说法都是无法通过源码核实的准确证据缺口；保留的候选项不超过五个。

4. 呈现结果

每次都以简洁的扫描摘要开头，说明候选项边界、任何证据范围延伸、涵盖的清单类别、适用的上下文或决策依据，以及重要排除项。

如果没有候选项保留，应说明未发现有证据支持的架构候选项，并解释为何筛除了观察到的信号。不要凭空编造首要建议，也不要要求用户启动技术规格工作流。

否则，按排名顺序返回简洁的候选项卡片。引用足够有代表性的证据来证明摩擦点，无需列出每处出现位置：

### <Candidate title> — <Strong | Worth exploring>

- **Standards:** <applicable coding-standard principle names>
- **Files/modules:** `path:line`, `path:line`
- **Current friction:** <caller burden, risk, duplicated policy, poor seam, or test friction>
- **Evidence:** <concrete call path, repetition, leaked representation, invalid state path, or test contortion>
- **Ownership move:** <current owner or callers> -> <proposed owner>
- **Expected leverage:** <burden or risk removed relative to new machinery>
- **Existing test evidence:** <test path:line or none found>
- **Verification seam:** <public interface or real adapter through which the move would be tested>
- **Evidence gap:** <required only for Worth exploring; the exact source-unverifiable claim>
- **Context/ADR note:** <optional; only for a durable term, conflict, or decision>

当调用流、数据流、所有权或运行时拓扑用图示比文字更清楚时，使用简洁的当前/拟议 ASCII 图示。

仅在需要说明稳定的领域用语时，才建议对 CONTEXT.md 做出准确的澄清。只有具体摩擦足以证明重新审视 ADR 的合理性时，才提及 ADR 冲突。

以以下内容结尾：

Top recommendation: <candidate title> — <why it has the greatest architectural leverage>

Which candidate would you like to prepare for the tech-spec workflow?

完成标准： 扫描摘要明确了排序范围；每张卡片都符合候选项约定；每项说法都能追溯到引用证据或准确的证据缺口；零候选项分支不包含任何建议。

选择之后：准备交接

呈现结果后停止。只有用户选定候选项后，才执行此分支。

为 ../tech-spec/ 准备一份简洁说明，包含：

• 候选项标题及相关文件/模块；
• 问题、当前摩擦点和收集到的证据；
• 从当前所有者到拟议所有者的所有权转移；
• 适用的编码标准原则；
• 已知约束和不变量；
• 疑似切入点、边界、适配器和调用路径；
• 待解决问题；
• 上下文或 ADR 建议（如有）。

说明之后，告知用户使用该说明调用 @tech-spec；不要在此技能中调用或编写规格。

完成标准： 说明中的每项说法都能追溯到扫描证据，或标记为待解决问题；所有收集到的约束、不变量和受影响路径均已纳入；并明确告知用户由其主动发起交接。