一个城市自行车维修合作社维护 Python 服务，用来登记零件、安排修车工位和生成周报。团队的 CI 已经有一些检查，但新成员不知道红灯表示真实错误、历史欠账还是工具版本变化。一次发布前，大家又发现回退说明只写了「恢复旧版本」，没有证明旧服务能读新数据。下面在练习仓库与合成工单上，把静态规则、技术债和发布证据分别建立基线，再用有负责人、期限与恢复路径的门禁连接起来。
先固定仓库基线与责任
选择一个已知能启动的提交，保存 Python 版本、依赖锁定文件、工具版本、检查配置和现有 CI 运行记录。写清服务与模块边界：工位安排调用领域规则，领域规则通过存储接口读写，报表只消费公开结果。给规则、运行环境和发布决定分别指定维护者，避免一份汇总分数成为无人能解释的门禁。仓库级治理需要完整配置和历史信息，不能只看一次 PR 的新增行。
把规则表分成阻断、告警和暂未启用三种状态。每项记录规则标识、检查范围、为什么需要、失败示例、修复方向和负责人。潜在未定义变量与格式差异可以采用不同处置，但都要能回到具体工具与配置。为生成文件、迁移目录和第三方副本说明排除理由，核对实际发现的文件是否符合预期。排除范围太宽，会让原本想保护的业务路径从检查中消失。
基线首次运行时先保留原始输出和退出状态，再分类有效问题、误报、重复项及无法执行项。历史违规不是新的改动，但仍要有可追踪清单。可以为已有债务设置限定范围的阶段计划，同时阻止新增同类问题。具体如何识别已有项要遵循工具能力和仓库约定，记录位置与版本，不把全部失败统一设成忽略。工具没运行、配置没加载和发现违规是不同状态。
静态检查从可解释的小规则集开始
对 Python 仓库，可参考维护中的 Ruff 官方配置与规则文档建立明确规则集。先确认版本与实际生效配置，检查继承、命令行覆盖和文件范围。第一次只做检查，不自动修复；为一项未使用导入和一项未定义名称准备合成样本，观察规则编号与位置是否符合预期。再运行正确对照，验证规则能分辨问题。升级工具前保留同一套样本，不让新规则在没有评估时突然改变阻断标准。
为复杂度预算记录采用的是哪一种度量、工具版本和函数范围。不要把不同工具的数值直接放在同一个阈值下比较。选一个工位分配函数，列出嵌套、分支与异常处理为什么难改，再用项目已有度量做基线。新增逻辑超预算时，维护者可以先讨论拆分责任、补测试或改输入结构，不能仅为降低数字把条件藏进无名辅助函数。验收应同时看可理解性与行为保持。
重复检查也要回到业务含义。两处看似相同的工单筛选，可能分别处理已预约和已完工状态，直接合并会抹掉不同规则。先标注重复范围和调用方，确定确实应共用的逻辑，再决定是否修复。依赖与架构边界可参考 Import Linter 的受支持契约，将允许方向写成明确规则；用一个有意跨层的练习导入验证它会失败，再用符合边界的路径验证通过。工具能检测到的静态关系不等于所有运行时依赖。
把运行结果转换为 CI 证据时，保留检查命令、工具版本、配置版本、目标提交、退出状态和可读日志。若日志只显示最后一步成功，确认前面的命令失败不会被覆盖。对缓存与跳过条件分别做试验，防止某些改动根本没触发需要的检查。先在告警阶段观察稳定性，确认重复运行结果一致、误报有处理办法，再把有限规则提升为阻断。每次变更门禁都应能解释增加了哪项保护。
技术债以具体维护代价排序
技术债清单从仓库事实开始。记录哪些文件经常一起修改、哪类工单故障反复出现、哪些模块很难独立测试。对一个混合了排班、库存与报表的函数，给出调用图、依赖方向和一项真实的变更障碍，例如每次新增工位类型都要修改三个模块。历史提交只能说明共同变化，不能单独证明架构错误；结合代码与维护者解释再判断根因。
每项债务写清位置、当前风险、验证方式、估计投入范围和前置依赖。区分已经造成故障的问题与未来可能增加成本的设计。优先级可以结合影响、变更频率和修复可行性，但把判断依据保留下来，而不是只交一个总分。需要先补测试才能安全拆模块时，将测试作为前置任务。把一次大重写拆成能交付的边界，例如先建立存储接口，再逐个迁移调用方，最后删除旧路径。
给首个债务修复设置完成条件。工位规则可在不启动报表服务的情况下测试，旧接口消费者仍得到同样结果，新增边界检查能阻止反向依赖。运行前后同一夹具，记录行为和错误分支。复杂度或重复数下降只是辅助信息；若修改增加了隐藏共享状态，维护风险可能反而上升。请未参与改造的同事解释调用路径并做一个小变更，观察是否真比以前容易理解。
团队每个周期检查债务状态和实际投入。估计偏差大时记录原因，及时调整范围。已不再适用的条目可以关闭并说明依据，临时压后的条目保留重新评估时点。规则、技术债与发布阻断的责任要分清：重要的长期改进不一定阻止每次小发布，而已经证明会损坏数据的风险也不能因为被列成债务就无限延期。由相应负责人根据明确后果决定处置。
发布门禁要对应同一候选与可恢复状态
发布证据卡记录候选提交、构建产物、目标环境、配置版本、数据库变化和负责人。每条检查指向该候选实际执行的结果，注明观察时间与适用范围。演练样本和真实目标的回执分开，固定日期的例子过期后不能继续当成当前证据。门禁可以产生暂缓结论，列出缺失的工位预约回归、迁移验证或恢复演练，而不是用空字段默认通过。
回退计划需要可执行的前提。在隔离环境模拟新服务写入一条合成工单，再用旧服务读取，观察字段与状态是否兼容。若迁移不可逆，明确恢复备份或向前修复的方案与代价，不能只写恢复镜像。记录备份范围、恢复点、所需权限、操作人和完成后检查。部署失败、运行期故障和数据迁移失败可能需要不同处理路径，分别演练最相关的一条。
上线后观察项要与风险对应。比如新排班计算可能造成重复工位预约，就检查合成用例、任务失败率和被拒绝的冲突记录，并写清观察窗口、阈值与处理人。阈值来自服务要求和基线，不能照抄别的仓库。遇到异常时明确何种条件暂停扩量、回退或继续调查。数据不能取得时应标为不可判断，不能把没有日志等同于没有故障。
整理证据和交接时，可考虑 Skillπ Release Readiness。已核对公开条目是付费产品，包含 Python 3.9 或更高版本的本地检查器、示例和双语交接模板，适合本阶段整理已提供的证据并生成 ready/hold 结果。完整包按其购买与使用条款取得，公开演示不等于完整交付。本教程未购买或运行它，也不把它当成回执真实性、部署或支付验证工具。团队已有等效清单时，可以继续按相同证据要求完成。
误报、例外与恢复都写进流程
一项规则误报阻断练习发布时，保存原始发现、规则版本、触发样本与反例。先确认是不是配置或输入超出了工具适用范围。需要临时例外时，将例外限制到具体规则和路径，写负责人、理由、补救措施与失效时间。例外不应顺手关闭整个检查，也不能把一次发布的决定变成永久仓库政策。到期未修复时重新评估并留下决定，不能静默延长。
门禁配置本身也需要回退。保存上一次有效版本，用有问题与正常两个样本比较新旧结果。如果新规则产生大量噪声，可以先撤回该项阻断并保持报告，再修正规则重放基线。恢复配置后确认其他保护仍运行，日志中能看到实际状态。真正业务风险仍存在时，需要相应业务缓解，不能仅把检查改绿。例外关闭后清理局部抑制并复跑，确保风险已处理且规则重新生效。
选择技能时先写能力边界
静态规则需要语言、工具与配置契约，债务诊断需要仓库结构与变更证据，发布就绪需要当前候选、回执和恢复路径。三类任务可以顺序组合，但每个发现应有唯一来源和责任人。发现候选时先检查是否已有 SkillPI Skill Finder，没有时阅读官方仓库说明后按宿主方式启用。让它按具体缺口收集来源、版本、依赖和产物，再逐一打开实际包核对。
首轮试用固定同一仓库、工具和规则版本，记录有效问题、误报、重复、运行时间、修复成本和例外数量。文档建议与实际执行结果分别列出；技能只生成计划时，不能算已跑门禁。来源无法查看或用途不匹配的候选不写关联，新增条目后再用同样夹具比较。Ruff 和 Import Linter 是这里参考的开源检查工具，不被冒充为已安装的 SkillPI 技能。只将多次试验后可解释、有维护人的规则加入正式流水线。
一次治理演练的交付
先在基线提交运行静态规则并分类，再选择一项排班职责泄漏的债务建立小步修复计划。用合成工单验证行为与边界，生成同一候选的发布证据卡，在隔离环境演练旧版读新记录。故意移除一条关键回执，检查结果应暂缓且指出补齐方法；补齐后再按规则判断。最后制造一个局部误报，走例外、修复和回收流程。交付包含规则表、债务清单、候选证据、恢复记录与例外历史，另一位维护者应能复跑关键检查。
常见问题
红灯很多，是否应该一次修完？
先分类新增问题、历史债务和环境失败。针对风险逐步建立阻断与告警，保留历史清单和期限。大规模自动修复前用小样核对行为，避免把清理与业务变更混成无法解释的差异。
通用质量分数能决定发布吗？
分数需要说明规则、范围和权重，也可能掩盖单个严重问题。发布应对照团队要求、当前证据与恢复能力，由负责人作决定。没有规则来源的总分只是一条未证实的摘要。
多个工具报告同一问题怎么办？
给发现建立共同身份，保留各工具证据并指定主规则与负责人。统计重复项，避免同一风险多次计数。若工具结论冲突，用固定样本和契约确认，保留无法判定部分。
例外到期但修复还没完成怎么办？
重新评估风险、补救是否有效和剩余工作，明确继续暂缓还是批准新的有限例外。保留新的理由、责任人与截止时间，不能自动继承原决定。
如何知道治理确实有帮助？
持续看有效问题、误报、复核时间、返工和例外回收，而不是只看检查数量。用同一基线评估工具变化，再结合实际发布事件调整范围和阈值。