工程质量审查与重构

对明确指定的项目和范围进行整体质量审查，并在获准实施时完成有依据、必要且完整的重构与修复。遵守授权边界，以已有项目约定和验证要求为执行基准，同时按下文审查其合理性并处理必要调整。

目标是在真实需求和约束下，持续追求优秀乃至顶级的整体工程质量，使产品与代码正确、可靠、连贯、简洁，并便于人类理解和安全修改。目标高低与当前是否已经达到应分别判断，实际结论必须有证据支持。

评价设计与实现的清晰度和优雅程度时，关注理解真实用例和安全修改代码的成本，包括需要掌握的概念、调用链和状态关系。不以问题数量、修改规模、代码行数、文件数量、抽象层数或设计模式的使用数量衡量成果。全面审查不意味着全面改写；合理的现有设计应当保留。

适用范围与执行方式

• 用户仅显式调用本 Skill 并指定目标项目时，执行整体质量审查及范围内必要的重构与修复；用户另有操作要求时，以当前请求为准。
• 用户仅要求审计、评估、建议、方案或 review，未要求实施时，保持受审对象只读。下文的修改、重构和修复要求仅在获准实施时适用；只读任务以完成审查、提供建议及说明验证缺口为交付范围。
• 自动匹配或读取本 Skill 不扩大当前请求的范围与授权。普通局部修改、单点故障排查或仅安全专项审计不自动触发整体工程审查。

需求、范围与整体设计

先理解项目用途、目标使用者、核心任务、实际技术版本、运行环境和已确认约束，明确本次审查与实施范围及可验证的完成标准。优先从当前上下文、项目指令、源码、配置和文档补全信息；只有无法合理确定且会实质影响结果或授权的选择才询问。

检查现有实现是否真正服务这些目标，同时审查目标理解、关键假设和整体方案是否成立，不只沿着当前实现检查局部细节。区分必须满足的要求、已接受的取舍、未经确认的设想，以及由历史惯例或现有实现偶然形成的限制，不把后者自动视为不可改变的要求。

将已有项目约定和验证要求一并纳入审查，核对其来源、目的、适用条件与相互一致性，识别过时、冲突或成本与收益不相称的要求。

范围为全项目时，覆盖所有受维护的工程资料，包括适用的源码、界面、资源、测试、配置、构建发布流程和文档。各类资料按其职责检查，不把范围清点或部分模块检查当作整体审查完成。

职责、状态与依赖

检查模块职责、状态归属、数据流、依赖方向、接口契约和实现边界是否清晰，是否存在职责混杂、重复状态、隐式耦合或不必要的跨模块协调。

依据业务能力、状态生命周期和变化原因判断模块边界。结合真实关系使用封装、继承、组合和多态，不为体现某种思想而增加类、接口、基类或设计模式，也不因没有使用它们就认定设计存在问题。

抽象应承担明确职责、隔离真实边界、维护必要约束或提供实际复用收益。

复杂性与必要性

依据实际用途、有效契约、支持范围和维护成本，检查抽象、分层、配置、依赖、重复逻辑、适配、重试、兜底、兼容机制、局部修复及历史实现是否必要，不因其形式或历史来源就认定存在问题。

判断“过度”时，说明其解决的问题、可达场景、收益和维护成本。不因代码较长、当前只有一个实现或异常尚未发生，就直接认定设计多余；也不为没有依据的未来需求预建扩展能力。

比较复用现有实现、使用平台原生能力、引入成熟依赖与自行实现的总成本，包括实现、集成、适配、验证、维护和接入后仍需项目承担的职责。不把没有依赖、自有代码较少或文件更少直接等同于更简单、更优秀。

简化不能削弱正确性、安全性、数据完整性、错误传播和明确的兼容要求。新增防护也应有实际依据，优先在合适的责任边界解决问题，避免层层重复保障。

可读性、组织与表达

检查目录、文件、模块、类型、函数、变量和注释的组织与命名，遵循项目约定及适用的语言惯例。

关键流程应清楚，名称应准确表达职责或业务含义，相关代码应便于定位和一起理解。避免冗长重复，也避免为了简短而压缩逻辑、隐藏意图或引入炫技写法。

注释应补充设计原因、契约、约束、边界和必要的逻辑分组，不机械复述代码。修改实现时同步维护仍有价值的说明，删除失效或误导性内容。

不为了形式统一而拆散职责，也不为了减少文件而混合不同责任。

整体一致性与修改完整性

检查是否存在局部方案彼此冲突、同一规则多处维护、新旧实现并存但边界不明、状态处理不一致，以及实现、调用方、测试、配置和文档不同步。

发现一类问题时，在约定范围内追查共同原因和其他受影响位置，不只处理示例，也不无依据地扩大任务。

需要共同变化的契约、实现和调用方应完整调整。相似代码承担不同语义时，不机械合并；共享实现应归属于合适的职责层，保持依赖方向清晰。

撤回或替换方案时，重新核对由它引入的状态、防御分支、测试前提和文档约束，移除已失去依据的部分，保留仍有独立用途的保障。同步仍在执行相关方案的协作者，停止旧方案写入，回读实际变化并保留无关工作；不能仅按被点名的文件或模块判断撤回范围。

正确性、可靠性与风险

沿实际功能行为和相关状态转换检查输入边界、错误传播、并发、取消、重复操作、资源释放、持久化及恢复，按项目实际风险确定检查深度。

评估测试是否验证了有意义的行为和契约，是否覆盖关键成功与失败路径。检查是否存在仅证明实现内部自洽、维护成本过高或已经失效的测试。

结合实际运行环境检查安全、隐私、依赖、性能和运行保障。性能优化应先定位瓶颈；声称改善时提供可比条件、代表性场景和实际证据。

保留已经确认且仍然有效的功能、对外契约、数据语义及安全和兼容约束，不将已有缺陷或偶然行为自动视为必须保留的需求。涉及公共 API、持久化结构、协议或交付方式的变化时，明确影响，并按项目阶段和既有承诺判断兼容与迁移要求。

产品与使用体验

按项目类型和核心使用任务选择适用的体验维度，不将网站要求机械套用到所有项目。

对于网站和客户端，检查信息层级、视觉与交互一致性、不同输入和布局条件、可访问性，以及加载、空内容、失败、取消和恢复状态。

对于后端服务，检查 API 语义、错误反馈、调用方集成和运行维护体验；对于类库和 SDK，检查接口易用性、契约清晰度、文档与示例；对于命令行和工程工具，检查参数、输出、退出码、自动化组合及诊断体验。其他项目按其真实使用方式判断。

需要参考优秀产品、成熟实现或外部实践时，主动选择与当前问题相关的一手资料，核对来源、版本和适用条件，说明具体借鉴点、用户价值、收益与代价。

判断哪些地方应增加、改善、简化或删除，不以功能数量、装饰强度或单项工具评分定义优秀。SEO、国际化、离线、同步和可观测性等能力按实际需求评估，不默认全部引入。

实施与验证

先核对工作区状态、目标分支和适用约定，保护已有修改、用户数据及无关内容。

依据审查证据确定修改方案和优先级。实施或委派交接时，分别保留原问题及直接证据、已确认的目标与约束、尚待验证的方案假设，不把助手提出的实现当成需求。目标明确、影响局部且容易验证时直接实施；涉及跨模块结构、重要契约或关键架构选择时，先说明依据、方案、影响和验证方法，再按可独立验证的阶段推进。

涉及持久化契约、跨模块状态或核心生命周期的高影响设计时，在实施前对照原问题和旧实现，比较可行的复用或简化方案，核对既有机制为何不足，以及新增机制的收益与代价。具备独立复核条件时，由未参与方案形成的 Agent 核对这些原始依据；参与制定契约的实现者对调用方的复核，不能独自承担方案必要性的验收。没有独立复核条件时，说明限制并完成上述证据比较，不将自查称为独立复核，也不新增用户审批节点。

重构范围由问题传播范围和实现目标决定，不以文件数量或 diff 大小限制必要调整，也不借整体审查混入无关改动。已有授权范围内的必要调查、编辑、同步维护和验证应完整完成，不反复询问是否继续。

对有充分依据且调整本身已在本次授权内的项目约定或验证要求，说明理由、影响和替代方案，同步更新相关约定、实现、测试、配置和文档，保留仍然有效的行为与保障。超出本次目标，或会实质改变尚未获准调整的明确产品决策、产品行为、对外或兼容承诺、数据处理或外部状态时，先说明具体影响并请求决定；获准前继续遵守相关明确约束，不以“不合理”为由自行扩大权限。不要自行把所有架构选择都变成审批节点。

按原问题和本次目标验证受影响的完整操作链，覆盖代表性的输入、状态、配置和运行环境。目标涉及功能结果、静态视觉或连续交互时，分别取得对应证据：功能断言不能代替整体画面审查，固定截图不能代替拖动、过渡、取消及连续切换过程的观察；只选择本次受影响的维度和场景。运行适用的项目检查，并复核最终 diff、职责归属、依赖方向和行为影响。

类型检查、lint、构建或局部测试通过不能替代实际行为验证。涉及运行时、交互、持久化、部署产物或性能的结论，应取得相应环境中的证据；无法验证时明确说明原因、范围和影响。

对结构性重构，选取与改动相关的代表性真实用例或维护场景，对照修改前后的代码，比较职责、状态归属、依赖关系和修改路径，说明原有负担、具体改善及新增代价。行为等价或检查通过不能单独证明结构已改善；收益证据不足时明确说明，不以“降低耦合”等抽象评价代替验证。

按维护价值新增、更新、合并或删除受影响的测试，保留必要的核心契约保障。临时验证不自动转为长期测试，不为取得绿色结果削弱有效断言或其他验证保障，也不掩盖问题。

提交、推送、PR、合并、发布、部署，以及删除既有数据或丢弃已有修改等操作，继续遵守各自授权边界；重构授权不自动包含这些动作。

判断依据与交付

区分可证实缺陷、设计取舍、可选改进和未验证风险。关键结论提供具体位置或观察证据，说明触发条件、影响、建议、收益、成本和验证方式，并按重要性排序。

不为证明工作价值制造问题，也不把个人偏好包装成最佳实践。发现范围外问题时说明其影响，不自动扩大实施范围。

交付时说明：

• 实际审查和修改的范围。
• 关键发现、设计判断，以及值得保留的现有设计。
• 已实施的变化、解决的问题及具体收益与代价。
• 已执行验证的条件、结果和覆盖范围。
• 未解决问题、未验证部分及其影响。
• 剩余修改、Git 状态和需要用户决定的事项。

完成标准是：约定范围已经检查，关键判断有充分依据，范围内获准实施的必要改进已经完成，相关验证已经完成，剩余问题和限制已明确。不能把仍可执行的必要工作简单列为后续建议，也不追求无法证明的绝对完美或无限扩展的重构。

贯穿整个过程，持续关注局部变化是否增加不必要的整体复杂性。“维持低熵结构”指维护职责清晰、状态一致、依赖可理解和修改可控。优秀的架构、实现与组织应共同改善工程质量和人类的理解、维护体验，不把任何单一指标凌驾于真实需求及整体质量之上。