可维护性评估方法
§1摘要与结论
沿可维护性的子特性组织证据，结合结构度量、变更历史与维护过程指标，对系统「修改得有多有效、多高效」做出可比较判断，并据此定位需优先治理的结构问题。
别名：maintainability assessment、可维护性评估、维护性度量、变更成本 | 英文：Maintainability Assessment | 类型：方法 / process
§2局部关系图
§3原理 · 为什么
可维护性描述的是修改的有效性与效率，它无法被某个孤立的静态数字直接读出，但可以通过多类证据的交叉来近似判断。评估的意义在于把「系统好不好改」从主观印象变为可比较、可追踪的判断，从而在资源有限时把治理投入引向真正昂贵的地方。评估应沿可维护性的子特性组织：模块性、可复用性、可分析性、可修改性与可测试性分别对应修改难度的不同侧面，需要分别收集证据，避免用单一指标概括整体。由于维护是贯穿生命周期的活动，评估还应结合维护过程的现实——变更的实际频率、修改时的波及范围、缺陷与返工的分布——而不是只看代码结构。把结构与历史两类证据合并，才能判断哪些模块是真实的风险点，哪些只是看起来复杂但很少变动。
§4机制 · 如何运作
评估沿三条证据线展开。结构证据：模块边界、依赖方向、耦合与内聚、重复与复杂度等，用于提示潜在的高风险区域；它们是信号而非结论，须结合语境解读。变更证据：版本历史中的改动集中度、单次变更触及的模块数、代码被反复修改的热点，直接反映现实中的可修改性，比静态结构更接近真实成本。过程证据：缺陷与返工的分布、修复所需时间、维护活动的类型构成，反映维护的有效性与效率。三条线交叉后，可按子特性给出相对评分或分级，并把结果映射到需优先治理的模块。评估应可重复：明确度量口径、数据窗口与判定规则，使不同时间点的结果可比较；同时记录评估所依据的版本与假设，避免结论过期后仍被引用。口径一旦变动，须同时重算历史数据，否则趋势对比将失真；评估脚本与判定规则也应与图同版本管理，确保结论可复现。
§5工程 · 怎么落地
实践中把可维护性评估嵌入日常流程而非作为一次性审计：在发布前或迭代节点采集结构、变更与过程三类指标，形成趋势而非单点快照；把明显恶化的趋势作为触发深入分析的信号。评估结果应转化为具体行动——针对热点模块补充测试、改善依赖方向、拆分或合并模块，并把这些改动纳入正常的重构与演进计划，而不是发起孤立的「代码质量专项」。对评估指标本身要保持警惕：可维护性度量多而分散，单一阈值容易误导，且一旦被当作考核目标就可能被博弈，因此应组合使用多个信号并关注其变化方向。评估的产出应是可讨论的假设与优先级清单，供团队结合变更频率与业务重要性决定治理顺序。定期复核度量口径，确认它仍在度量真正重要的问题，避免指标僵化。评估的最终价值在于促成改变，而不在于产出一份更精细的报告：应把发现转化为可执行的治理项并跟踪其效果，下一次评估再验证这些改动是否真的降低了变更成本，形成以证据驱动的闭环，而非周期性的数字汇报。
§6权衡卡
其四，评估有成本：持续采集与解读需要投入，过度频繁或过细的评估会成为负担。
因此评估应以驱动决策为目的，聚焦少数高价值信号，把结果与真实变更成本对照验证，并随系统演化更新口径。
反例是把评估做成一次性打分排名，既未转化为治理行动，也未纳入演进闭环。
- 可维护性评估有内生的局限。
- 其一，结构度量只是间接信号：复杂度高、耦合大的模块未必真的难以修改，而看似整洁的代码也可能因缺乏测试或依赖隐藏而难以安全变更，因此不能以指标高低自动判定问题。
- 其二，指标之间存在张力与冗余：降低耦合可能增加模块数量，降低重复可能增加间接层，单一目标的最优化可能损害整体，需要结合语境取舍。
- 其三，度量本身可能被博弈：当指标被当作考核目标，团队会优化数字而非改善可维护性，使评估失去意义。
- 承认度量的近似性，才能把它用在合适的判断上：评估适合用来发现趋势、排序治理优先级与检验改进效果，不适合用来给个人或团队排名，也不适合替代对具体代码与变更语境的深入阅读。
- 度量服务于判断，而不能代替判断。
权衡原文仅按显式标记词归栏引用（收益 / 代价 / 反例），其余句子按原序列为「原文要点」；内容逐字引用未改写。
§7案例带
网申填写扩展逆向架构
对 Chrome MV3 网申自动填写扩展的逆向架构分析：梳理 popup、content、background、options 四模块职责，解剖 12 个站点适配器、双通道消息协议与隐私脱敏机制，并评估其零依赖零构建选型。
网申 v3 多模块解耦
一套面向高可扩展性的网申信息速查扩展架构：以 schema.js 为唯一数据驱动源，把数据模型、存储、纯函数与渲染组织为严格单向依赖的共享层，供 popup 与页面浮层双容器复用，并先立跨模块接口契约。
网申 v2 深度重构
一次由「改一处漏多处」症状触发的深度重构：定位到接口定义散落 12 个文件、存在 7 种接口形态的根因后，以单一契约源、dispatch 消息表与能力注册中心重建三层契约系统，恢复可审计与可校验性。
preset 通道耦合分析
对 harness「委派工具层→续用管理器→preset 服务→MCP 服务器」这条通道做耦合分析：识别契约、服务定位、数据契约、组合语义、路径与装配一致性六类耦合点，定位「静默丢弃特化」与「装配漂移」两处实质缝隙。
Open Code Review 图谱
对阿里开源 AI 代码审查 CLI 做源码级解析并构建「知识 + 实践资产 + AI 索引」三合一知识图谱的工程案例。
控制理论⊗Agent 设计
将控制理论五维（负反馈 / 状态估计 / PID / 鲁棒 / 分层）系统映射到 Agent 工程环节，并以真实产品案例验证的跨学科方法论案例。
技术知识中枢交付法
从模糊需求到上线，把 AI Agent 驱动的端到端交付固化为四阶段加双共识加迭代的可迁移方法论的实战提炼案例。
§8信源与核验
核验结论：可维护性由多个子特性构成，须综合结构、变更历史与维护过程三类证据交叉判断；单一静态指标只是间接信号，且可能被当作目标而失真 [OFF-005]
§9原始关系清单
展开：本节点的全部原始关系边（6 条，含边 ID 与方向）
| 关系 | 方向 | 对端节点 | 说明 |
|---|---|---|---|
| 依赖关联 | → MTH-M-04 | 质量模型应用方法 E-355 | 可维护性评估依赖质量模型的维度框架 |
| 依据推导 | → ESS-M-01 | 可维护性本质 E-349 | 可维护性评估以可维护性本质为判据 |
| 实现 | ← TEC-H-02 | SQALE 技术债评估方法 E-805 | SQALE 为可维护性提供量化评估方法 |
| 实现 | ← TEC-H-03 | 技术债量化度量指标 E-808 | 债务比率与评级把可维护性折算为可计算指标 |
| 实现 | ← TEC-M-01 | 质量模型工具化 E-906 | 质量模型为可维护性评估提供子特性维度 |
| 实现 | ← TEC-M-02 | 可维护性量化 E-907 | SQALE 量化技术债与可维护性实现可维护性评估方法 |