architecture-optimization

架构优化

同时从架构、代码质量和性能三个方面优化可运行的代码库，同时不破坏现有功能。这是一段交互式、可随时恢复的八阶段旅程：每次做出决定前，Agent 都会先征求你的意见，并将结果记录在项目的 docs/ 文件夹中，因此你可以在任何阶段结束后暂停，并在之后继续。它适用于已经投入使用并带来收益，却日渐缓慢、错综复杂的系统；架构阶段让代码更安全、更易于修改，性能阶段让系统速度得到可衡量的提升，最后的阶段则确保这一状态得以维持。

核心原则

先测量再优化，先固定行为再重构——由性能分析器和安全网来决定，而不是凭直觉。 过早优化是诸多问题的根源，并非因为优化不好，而是因为未经测量的优化会针对代码中错误的 97%；没有固定行为就进行重构，不是改进，而是赌博。这项技能会安排各个阶段的顺序、提出决策问题，并将每项选择记录在 docs/ 中。各项组成技能提供具体方法——请调用它们，而不是临场发挥自己的框架。

旅程路线图

阶段	技能	回答的问题	产物
1	working-with-legacy-code	行为是否已固定、性能是否已测量，从而确保每项改动都可验证？	创建 docs/PERFORMANCE.md + docs/TECH-DEBT.md；扩展 docs/TESTING.md — 关卡
2	clean-architecture	依赖关系是否仍然向内指向，还是随着代码增长，边界已经偏移？	扩展 docs/ARCHITECTURE.md
3	software-design-philosophy	模块是否足够深，还是结构本身已经成为复杂性的来源？	扩展 docs/TECH-DEBT.md
4	refactoring-patterns	能否通过有名且保持行为不变的步骤，重塑热点路径？	扩展 docs/TECH-DEBT.md + docs/TESTING.md
5	system-design	实测负载表明瓶颈在哪里，最便宜的修复方案是什么？	扩展 docs/PERFORMANCE.md + docs/ARCHITECTURE.md
6	ddia-systems	数据层是否是瓶颈——查询、索引、隔离、派生数据？	扩展 docs/ARCHITECTURE.md + docs/PERFORMANCE.md
7	release-it	依赖项变慢或不可用时，系统能否继续保持快速稳定？	创建或扩展 docs/RELIABILITY.md
8	pragmatic-programmer	停止优化后，哪些预算和习惯能让系统持续保持快速、整洁？	扩展 docs/PERFORMANCE.md + docs/TECH-DEBT.md + docs/TESTING.md

运行规则

1. 优先恢复进度。 首先阅读 docs/ARCHITECTURE-OPTIMIZATION-PLAN.md 和 Journey Map 中的每一项材料。如果跟踪文件存在，用 3-5 行总结旅程状态，并询问要进入哪个阶段。完成标准：用户已确认入口。存在跟踪文件的旅程应恢复，而不是重新开始。
2. 仅在首次运行时进行初始收集。 如果没有跟踪文件：执行下方的初始收集，然后创建 docs/ARCHITECTURE-OPTIMIZATION-PLAN.md，将每个阶段的状态设为 pending | in-progress | awaiting-evidence | done | deferred: reason | skipped: reason。完成标准：跟踪文件已创建，且用户已确认阶段计划。
3. 进入阶段。 说明该阶段的工作内容、需要做出的决策、产出的材料和大致工作量。提供继续 / 跳过 / 延期选项——标记为 GATE 的阶段可以延期，但不能跳过。用户选择继续后，将阶段标记为 in-progress。完成标准：用户已作出选择。
4. 调用技能及回退方案。 加载并使用该阶段的技能：每个阶段的 Invoke 行都会以 slug 指明技能——使用该技能执行阶段。如果技能不可用，提供：npx skills add wondelai/skills/<slug> --global。如果用户拒绝，则根据 Brief 执行该阶段——采用最低可行方法。说明当前使用的模式。
5. 阶段内决策。 询问「与用户共同决策」下的每个问题，并给出具体选项和推荐方案。将选择记录到跟踪文件的 Key Decisions 中。未经询问就自行做出决策属于缺陷。
6. 阶段退出。 写入前，先呈现材料草稿供用户确认。获得批准后：编写或扩展 docs/ 文件，并更新跟踪文件（状态、Key Decisions、Next Actions）。完成标准：文件已写入，且阶段行的状态为 done。
7. 材料规范。 写入前先阅读；仅在文件不存在时才创建，否则应扩展文件——添加或更新相关章节，并保留其他人的内容。docs/ 中的文件名使用大写。首次创建 docs/ 文件时，参阅 references/artifact-templates.md；根据完整骨架创建文件（包含所有章节标题），再填写当前阶段指定的章节。每条建议都必须落实为复选框或表格行，并注明负责人和优先级。
8. 不得优化未经测量的内容，也不得重构未固定的内容。 为降低已测量基线而进行的每项更改，都必须引用该基线，并在 PERFORMANCE.md 的 Optimization Ledger 中记录前后数据——如果数值没有改善，就回退该更改，不得保留。（韧性与门控工作——超时、熔断器、舱壁、分页、CI 门控——应依据其所属阶段的完成标准评估，而非延迟变化。）结构性更改只能涉及 Safety Net Map 中已固定的代码，必须保留原有行为，并以独立于行为更改和优化更改的提交提交。

信息收集

创建跟踪器前，请先询问以下问题：

1. 系统的功能是什么，“太慢”会造成什么代价——用户流失、SLA 违约，还是基础设施账单增加？（这有助于确定应关注的指标，以及这段工作流值得投入多少精力。）
2. 目前有哪些证据——APM 跟踪记录、慢查询日志、p95 延迟、云账单，还是只有投诉？（这些信息将用于建立第 1 阶段的基线；只有投诉时，必须先完成检测埋点。）
3. 哪些流程或端点的问题最严重，哪些模块负责实现它们？（用于选出各阶段要处理的热点路径。）
4. 是否有自动化测试，且测试能否全部通过？（这决定第 1 阶段安全网的范围——尚未固定测试的热点路径，要先固定下来，再进行任何改动。）
5. 使用的技术栈是什么——语言、框架、ORM、数据库、缓存——以及部署位置？（这是第 5 至 6 阶段的前置条件。）
6. 实际负载数据是多少——平均和峰值 QPS、数据量、增长率？（这是第 5 阶段的前置条件——按数据而非担忧来进行容量规划。）
7. 现在希望完成整个工作流的哪些部分？（第 1 至 4 阶段让改动更安全、更简洁；第 5 至 6 阶段提升速度；第 7 至 8 阶段保持这一状态。）

跳过启发式流程：如果结构良好且问题纯粹出在性能上，可将第 2 至 3 阶段压缩为仅审计；无论结果如何，都要记录审计发现，并将阶段状态设为 done，附上“仅审计，未做改动”的说明。只有在先前工作流的 RELIABILITY.md 集成点审计经核实仍然有效时，才能跳过第 7 阶段（请检查文件，不要想当然）。绝不可跳过第 1 阶段——没有基线的优化只是猜测，没有安全网的重构则是一场赌博。

然后根据模板创建 docs/ARCHITECTURE-OPTIMIZATION-PLAN.md，并确认计划。完成标准：跟踪器已创建、所有阶段均已设置状态，且用户已确认计划。

阶段

各阶段须按列出的顺序执行——每个阶段都假定上一个阶段的产物已经存在。先调整结构，再提升速度，是有意为之：第 2 至 4 阶段让热点路径更安全、改动成本更低，从而使第 5 至 6 阶段的优化只需小幅差异，而不必大动手术。根据操作规则，可以进入、跳过或推迟任何阶段，但第 1 阶段是所有阶段的前置条件——它提供两道彼此独立的安全网：固定行为后即可推进第 2 至 4 阶段，记录基线后即可推进第 5 至 6 阶段，因此结构调整不必等到收集完可能耗时数周的性能分析结果。如果第 1 阶段的分析显示数据库占主导，可能需要调换第 5 和第 6 阶段的顺序：在添加缓存之前修复 N+1 查询或缺失的索引，正是这项技能所遵循的“优先处理成本最低项”原则。通过各阶段的 Brief 执行阶段（未安装对应技能时），请先阅读 references/methods.md——其中包含每个阶段的完整方法、检查清单、公式和启发式规则；Brief 仅为摘要。

阶段 1 — 固定行为并测量（working-with-legacy-code）— 闸门

**目的：**让之后的每次改动都有双重依据——用测试固定行为，用数据固定性能。任何阶段都不得触碰尚未固定行为的代码，也不得优化未经测量的路径。

**简介（备用方案）：**双重保障。行为方面：没有测试的代码就是遗留代码——先覆盖再修改，绝不改完就祈祷。找出热路径上的变更点，在影响最小的接缝处打破内联依赖（使用带生产默认值的 Parameterize Constructor；对一个隐藏较深的调用使用 Extract and Override），并编写特征测试来记录实际行为——先断言一个错误值，查看失败信息，再固定真实值。性能方面：动手之前先进行性能分析——瓶颈很少出现在直觉所指的地方。在现实数据量下，记录每个热流程的 p50/p95/p99 延迟、吞吐量和资源使用情况（开发数据库的计时结果并不可靠），并按资源运用 Gregg 的 USE 方法：针对 CPU、内存、磁盘、网络和连接池，检查利用率（Utilization）、饱和度（Saturation）和错误（Errors）。设定每项指标必须达到的预算，让“完成”有数字依据，而非凭感觉判断。

**调用：**对 intake 中的热路径模块使用 working-with-legacy-code 技能。请它找出接缝，并提供一组尽可能精简的特征测试，以固定每个待优化流程的当前行为；随后为这些流程采集性能分析器或 APM 基线。

与用户共同决策：(1) 确认纳入范围的热路径——以测得的性能问题为依据，而非猜测。(2) 确定每项指标的预算（例如，结账 p95 < 500ms）和记录工具（性能分析器、APM、负载测试），以便前后数据保持可比。(3) 记录特征测试过程中发现的错误：固定当前行为并记入台账，绝不悄悄修复——调用方可能依赖这些特殊行为。

**产物：**扩展 docs/TESTING.md 中的 ## Safety Net Map 和 ## Characterization Backlog；创建 docs/PERFORMANCE.md，包含 ## Baselines & Budgets、## Load Reality、## Profile Findings 和 ## Optimization Ledger；创建或扩展 docs/TECH-DEBT.md 中的 ## Debt Ledger 和 ## Sprout / Wrap Register，记录按现状固定的错误和缺少测试的宿主。更新跟踪器。

**完成条件：**范围内的每个流程都已固定行为（测试套件通过）——这将解锁阶段 2-4；并且已有记录在案的基线及预算——这将解锁阶段 5-6。分别记录这两项；如果性能分析仍在进行，就将状态设为 awaiting-evidence，并添加一行 Next Actions，而不是阻塞结构阶段。

阶段 2 — 重新划定偏移的边界（clean-architecture）

目的： 恢复代码库逐渐偏离的依赖规则——关注点混杂正是变更令人担忧、且无法独立优化缓慢部分的原因。

简述（备用）： 源依赖指向内层：框架 → 接口适配器 → 用例 → 实体；内层不得命名任何外层内容。在不断扩展的代码库中，偏移具体表现为：业务 逻辑导入 ORM、控制器计算领域规则、各处都调用供应商 SDK。绘制 实际依赖图并列出违规项；将关键路径业务规则提取到无框架依赖的用例中，并置于自有接口之后（依赖倒置）——这也能支持阶段 5–6，因为边界可以在以后插入缓存或队列，而无需大动手术。只在真正易变之处（数据库、外部服务、交付）划定完整边界；其他地方则合并形式化的层次——重要的是方向，而不是文件夹数量。

调用： 使用 clean-architecture 技能，并提供初始信息收集阶段得到的模块映射和技术栈。要求提供依赖图、所有业务逻辑直接依赖框架、ORM 或供应商的违规项，以及关键路径用例的提取计划——并指出哪些边界值得付出成本。

与用户共同决定： 本轮边界要推进到什么程度——优先处理关键路径，绝不一次性大规模重构分层；先将哪个供应商封装在自有接口之后；哪些违规项立即修复，哪些记入台账。

产出物： 扩展 docs/ARCHITECTURE.md 中的 ## Layer Map & Dependency Rule（违规项 | 位置 | 修复 | 状态）和 ## Decision Log。更新跟踪表。

完成条件： 已绘制依赖图，每项违规都列入跟踪表，关键路径业务规则可在不依赖框架的情况下通过测试，且测试套件全部通过。

阶段 3 — 深化模块（software-design-philosophy）

目的： 降低复杂度税——不断扩展的代码库会累积浅层类和泄漏的决策，这些问题会先拖慢团队，再拖慢代码。

简述（备用）： 模块深度 = 功能 ÷ 接口复杂度。合并总是协同运行且共享状态的浅层透传类；将每项设计决策隐藏在唯一一处——信息泄漏（同一决策反映在多个模块中）是最明显的危险信号；用按知识组织的模块替代按执行顺序组织的时间分解模块。跨层传递相同抽象的透传层，表明其边界不值得付出成本。这是从战术转向战略：现在投入 10–20%，让后续每个阶段涉及更少的文件。合并模块也能减少关键路径上的调用链形式化层次——但这样做是为了可读性，而不是纳秒级性能。

调用： 使用 software-design-philosophy 技能，并提供阶段 2 中映射的模块。询问哪些类较浅、哪些决策泄漏到多个模块中，并要求制定整合计划，将其合并为接口更小、深度更深的模块。

与用户共同决定： 哪些整合现在进行，哪些记入台账——避免过度合并真正无关的关注点；团队今后采用哪些设计规范。

产出物： 扩展 docs/TECH-DEBT.md 中的 ## Smell Inventory（添加浅层模块和信息泄漏条目，并说明已执行的整合）以及 ## Adopted Conventions。更新跟踪表。

完成条件： 每个浅层模块簇都已整合，或已记入台账并附上修复方案；每项已识别的泄漏决策都已整合，或已列入 Smell Inventory；且测试套件全部通过。

阶段 4 — 重构热点路径（refactoring-patterns）

目的： 使用有名称且保持行为不变的转换，重塑即将优化的代码——先清理，再提速，因为只有能安全修改的代码，才能安全优化。

简要说明（备用）： 每种代码异味都对应一种有名称的重构：对注释长度的代码块使用提取方法（Extract Method）；用卫语句替换嵌套条件（Replace Nested Conditional with Guard Clauses）；用多态替换条件（Replace Conditional with Polymorphism）；引入参数对象（Introduce Parameter Object）；用查询替换临时变量（Replace Temp with Query）。工作流：测试通过 → 执行一项转换 → 测试通过 → 提交；测试失败就回退，而不是调试。过程中融入整洁代码规范：使用能体现意图的名称；函数只在一个抽象层级上做一件事；不返回 null；错误中包含操作和状态上下文。准备性重构（Preparatory Refactoring）是通往阶段 5-6 的桥梁：每次优化前，先让变更变得容易（重构结构），再执行容易的变更（优化）——分开提交。

调用： 对热点路径模块和阶段 1 的测试使用 refactoring-patterns 技能。要求它指出每种代码异味、引用相应的转换，并在每次测试之间逐一应用。

与用户共同决定： 范围——本轮处理哪些代码异味、哪些记入台账；哪项即将进行的优化需要先在其插入点进行准备性重构；是否将重构后的模块加入 TESTING.md 中的 CI 门禁列表。

产出物： 扩展 docs/TECH-DEBT.md 中的 ## Smell Inventory（代码异味 | 位置 | 重构 | 状态）；将任何新加入门禁列表的模块补充到 docs/TESTING.md 的 ## CI Gates。更新跟踪表。

完成条件： 目标代码异味均标明重构名称，状态为 done / ticketed；测试通过；结构性提交不包含行为变更。

阶段 5 — 攻克实测瓶颈（system-design）

目的： 根据性能分析所示的耗时分布，按成本从低到高投入优化，并以实际数据确定优化规模。

简要说明（备用）： 阿姆达尔定律限制了所有优化收益：整体提速幅度受优化部分实际耗时占比限制——在占请求耗时 5% 的部分上提速 10 倍，只能节省 4.5%。目标应由性能分析而非代码审查来选定。粗略估算负载（QPS = 日活用户数 × 每日操作次数 ÷ 86,400，峰值为平均值的 2-5 倍），并确认与预算之间的差距。然后按顺序解决问题：先优化算法（O(n²) 循环或频繁的逐项 I/O，影响往往大于任何基础设施调整），再提高垂直扩展余量；对于读密集型路径，采用旁路缓存并设置 TTL 和明确的失效规则（测量命中率——冷缓存只会带来纯粹的开销）；再通过消息队列将耗时工作移出请求路径（利特尔定律：在途请求数 = 到达率 × 延迟，因此降低延迟也能提升容量）；然后添加只读副本——只有证据充分时才分片。每次变更后都重新测量；保留能改善指标的变更，回退没有改善的变更。

调用： 使用阶段 1 的性能分析结果和接入时收集的负载数据运行 system-design 技能。询问哪个组件最先成为瓶颈、针对实测差距成本最低且按优先级排序的改进方案，以及目前明确不需要哪些机制。

与用户共同决定： 哪些改进现在发布，哪些延期并记录触发阈值；若有，首先将哪种工作负载移至队列后；每条缓存路径的失效规则——什么事件会使哪个键失效。

产出物： 扩展 docs/PERFORMANCE.md 中的 ## Profile Findings 和 ## Optimization Ledger（变更 | 优化前 | 优化后 | 结论 | 日期）；扩展 docs/ARCHITECTURE.md 中的 ## Decision Log（记录每项采纳或延期及其触发条件）和 ## System Context，后者应引用 PERFORMANCE.md 中的 ## Load Reality，而不是重复负载数据。更新跟踪表。

完成条件： 根据性能分析指出瓶颈；每项改进均已实施并在台账中记录优化前后数据，或延期并注明触发条件；已采纳的改进均优于其基线。

阶段 6 — 修复数据层（ddia-systems）

目的： 数据库通常是首要怀疑对象——大多数测得的性能问题出在查询上，大多数正确性债务则源于隔离级别假设。根据证据修复这两类问题。

简述（备用）： 阅读查询计划，而不是 ORM 代码。常见问题包括：N+1 查询（每行一次——批量查询或使用联接；ORM 会悄无声息地生成这类查询）、实际访问路径上缺少索引（对慢查询运行 EXPLAIN；为谓词列和排序列建立索引，但每个索引都会增加写入开销）、结果集无界（为所有列表分页）、宽行上使用 SELECT *，以及深层偏移分页（改用键集分页）。存储引擎需要在读写之间权衡（LSM 的写入吞吐量与 B-tree 的读取延迟）——购置硬件前，应先根据访问模式选择合适的数据模型。并发正确性方面：大多数数据库默认采用读已提交或快照隔离，而非可串行化隔离——先读后写的路径会产生写偏斜；应显式加锁（SELECT ... FOR UPDATE），或在不变量有要求时使用可串行化事务。第二种读取模式（搜索、分析、信息流）可以证明使用 CDC 同步派生数据的合理性——绝不要双写；阶段 5 中的副本则要求有意处理读己之写。

调用： 使用 ddia-systems 技能，并提供阶段 1 的配置、阶段 5 的发现结果，以及接入阶段确定的数据库。如果尚无查询级数据来源，先启用一个（pg_stat_statements、auto_explain、慢查询日志）——这是阶段 1 延后的埋点工作，不能因此靠猜测行事。请进行查询计划审计（N+1 查询、缺失索引、无界读取），查明实际默认隔离级别及其在相关路径上造成的异常，并评估各工作负载适用的数据模型和存储引擎。

与用户共同决策： 决定要添加哪些索引，并权衡写入成本；决定哪些路径采用加锁或可串行化事务，哪些路径容忍异常；决定是否有任何工作负载足以证明使用 CDC 同步第二个数据存储的合理性。

交付物： 扩展 docs/ARCHITECTURE.md 中的 ## Data & Storage Decisions 和 ## Decision Log；扩展 docs/PERFORMANCE.md 中的 ## Profile Findings 和 ## Optimization Ledger，并记录查询优化前后的情况。更新跟踪表。

完成标准： 通过测量前后结果修复慢查询；所有范围内流程的列表端点均已分页（其余问题记入债务清单）；记录隔离级别，并对有风险的路径加锁；所有派生数据均有明确的同步机制。

阶段 7 — 故障时也要保持快速（release-it）

目的： 一个慢依赖就能拖垮整个系统，这样的系统算不上快速——故障时的延迟也是性能属性。

简述（备用）： 集成点是头号杀手，而缓慢响应比没有响应更糟：一个挂起的依赖会耗尽线程和连接池，日志里却毫无记录。不可妥协的要求：每个出站调用都要设置连接和读取超时（超时就是延迟预算）；为关键依赖配置熔断器（快速失败胜过等待）；设置隔舱，避免某个慢依赖耗尽共享连接池；采用指数退避和抖动重试（朴素重试会在依赖濒临故障时让负载恰好增加三倍）；定期清理日志、临时数据和不断增长的缓存。按端点接入 RED 指标（速率、错误、持续时间），并根据症状告警（p95 超出预算）——将阶段 1 的预算转化为生产环境的护栏，而不是一次性的快照。

调用： 使用 release-it 技能，结合接入阶段收集的出站依赖和阶段 1 的预算。要求提供根据流程延迟预算推导出的超时值、熔断器和隔舱的设置位置，以及 RED 指标和症状告警设计。

与用户确定： 各依赖的超时和熔断阈值，并使其与流程预算挂钩；哪些依赖需要专用连接池；非关键依赖不可用时，各核心流程如何降级。

产物： 创建或扩展 docs/RELIABILITY.md，加入 ## Integration-Point Audit（依赖项 | 超时 | 熔断器 | 隔舱 | 重试策略 | 状态）、## Query & Resource Findings 和 ## Health Checks & Metrics。更新跟踪表。

完成标准： 范围内流程的每个出站调用都设置了不超出流程预算的超时（范围外的调用记入 Debt Ledger）；关键依赖均配置了熔断器和隔舱；无界结果集和受阻线程均记录在 ## Query & Resource Findings 中；生产环境通过 RED 指标和症状告警来保障阶段 1 的预算。

阶段 8 — 固化预算与习惯（pragmatic-programmer）

目的： 让改进永久生效——如果没有关卡拦截，回归就会随着一次次看似无害的提交悄然发生。

简述（备用）： 将阶段 1 的每项预算转化为 CI 关卡：在热点路径上运行性能测试或查询次数断言，一旦 p95 超出预算，就像测试失败一样使构建失败。DRY 关注的是知识：同一规则在两处计算就会逐渐偏离——同一查询从两个层发起，既容易滋生错误，也会带来性能成本。破窗理论：发现第一个未经审查的慢查询或被跳过的索引，就要立即修复或登记工单，绝不能任由问题悄然累积。可逆性：将供应商和基础设施置于自有接口之后，这样下次优化——替换缓存、变更队列——仍只需一周，而非重写。设定每次迭代的债务预算，并记录约定；由台账而非记忆来记录延期事项。

调用： 对涉及的模块使用 pragmatic-programmer 技能。要求找出重复知识（包括重复查询和规则）、未跟踪的 TODO 和破窗问题，并设计性能预算的 CI 关卡。

与用户确定： 哪些预算应成为阻塞式 CI 关卡，哪些应作为仪表盘告警；每次迭代的债务预算；破窗处理策略——哪些问题立即修复，哪些登记工单。

产物： 扩展 docs/PERFORMANCE.md 中的 ## Baselines & Budgets（标明每项预算对应的关卡）；扩展 docs/TECH-DEBT.md 中的 ## Debt Budget & Broken-Windows Policy 和 ## Adopted Conventions；扩展 docs/TESTING.md 中的 ## CI Gates。更新跟踪表。

完成标准： 每项热点路径预算都成为 CI 关卡或有明确负责人的告警；重复知识已修复或记入台账；约定均已记录。

可选阶段

技能	在以下情况下添加	产物
clean-code	除热点路径外，可读性也很差——整个代码库都需要检查命名、函数和错误处理	扩展 docs/TECH-DEBT.md ## Smell Inventory、## Adopted Conventions
domain-driven-design	边界总是与业务语言冲突——模块划分与领域划分不一致	扩展 docs/ARCHITECTURE.md ## Bounded Contexts & Context Map、## Domain Glossary (Ubiquitous Language)
high-perf-browser	测得的缓慢发生在浏览器端——页面加载、LCP、阻塞资源——而非后端	扩展 docs/METRICS.md ## Baselines & Targets、docs/WEBSITE.md ## Audit Findings
team-topologies	有多个团队负责该系统，因此模块边界必须与团队边界保持一致（康威定律）	扩展 docs/OPERATIONS.md ## Team Structure

可选阶段遵循相同的操作规则——像核心阶段一样加载并使用列出的每项技能；在“添加条件”首次成立时插入。它们没有内联 Brief：独立运行时，clean-code 用于检查命名、函数大小和错误处理，domain-driven-design 用于梳理通用语言和有界上下文，high-perf-browser 用于审计 Core Web Vitals（LCP、INP、CLS），team-topologies 用于评估认知负荷和团队边界——或者安装指定技能以使用其完整框架。

常见错误

错误	修正方法
凭直觉而非分析器指示来优化	先进行性能分析（阶段 1）；阿姆达尔定律决定了任何收益都受该代码实际耗时占比的限制。
不做安全保障就为提速而重写	先用特征测试固定行为（working-with-legacy-code）；错误答案即使很快，仍然是错的。
保留没有改善指标的优化	每项变更都要在 Optimization Ledger 中记录前后数据；回滚未超越基线的变更——没有收益的复杂性纯属技术债务。
尚未修复算法就先上基础设施	O(n²) 循环或 N+1 查询的影响胜过任何缓存；先修代码，再配置基础设施规模（system-design）。
缓存却没有失效规则	过期数据造成的错误比节省的延迟代价更大；每条缓存路径都要说明哪个事件会使哪个键失效。
相信 ORM 会生成优质 SQL	对慢查询运行 EXPLAIN（ddia-systems）；N+1 查询和缺失索引会藏在看似无害的代码后面。
对外部调用不设超时，却称系统很快	故障情况下的延迟也是性能属性（release-it）；一个卡住的依赖就会抵消所有优化。

完成这段旅程

根据问题选择合适的投入：如果是某个端点响应缓慢，可能只需完成阶段 1、5 和 6——基线、瓶颈和查询；几天时间就能立即见效。如果是整个代码库每次更改都缓慢且风险很高，就应先完成结构相关阶段，因为只有边界清晰，优化才能小步推进。无论选择哪条路径，账本都会记录结果：保留的更改都优于各自的基线，其余更改均已回滚。

退出检查清单——每一项都对应一份交付物：

• docs/ARCHITECTURE-OPTIMIZATION-PLAN.md 中的每个阶段都已标记为 done、deferred: reason 或 skipped: reason。
• 每条热点流程都有基线、预算，以及在预算范围内的当前测量结果（PERFORMANCE.md 中的 Baselines & Budgets）。
• 每项保留的优化都展示了测量前后的结果；没有任何保留的优化未达到基线要求（PERFORMANCE.md 中的 Optimization Ledger）。
• 热点路径上的 Dependency Rule 违规已关闭，或已作为条目跟踪（ARCHITECTURE.md 中的 Layer Map）。
• 慢查询已通过执行计划修复，列表已分页，隔离级别已记录，风险路径已加锁（ARCHITECTURE.md 中的 Data & Storage Decisions）。
• 每个出站调用都有超时设置，且预算由 RED 指标和告警保护，或由 CI 门禁保护（RELIABILITY.md、TESTING.md 中的 CI Gates）。

关闭跟踪清单：将剩余的 Next Actions 移入 PERFORMANCE.md 账本和 TECH-DEBT.md，确保不遗漏任何事项。然后选择后续方向：如果问题在于害怕更改，而非速度，请继续使用 remove-technical-debt 技能；如果全新的原型未经测试、需要完整的生产级改造，请使用 improve-code-quality；如果下一个系统从一开始就应采用这种结构，请使用 design-code-architecture。