自定义
可选个人偏好: ${AGENT_SKILLS_CONFIG:-~/.config/agent-skills}/CodeQuality/PREFERENCES.md。
如果该文件存在,则读取并应用它;否则使用技能默认值。仅限个人偏好:任何与仓库或产品相关的事实都应归属于该仓库(在其 .claude/workflow-profile.sh 或工具配置中),绝不在此处。
CodeQuality 是做什么的?
一个循环,两个视角。循环始终是:检测 → 选择 一 项 → 在有测试保护的情况下修复 → 验证 → 重复。工具视角 修复扫描器标记的内容,按优先级排序,以现有测试作为护栏。原则视角 修复使代码难以更改的内容(上帝类、重复代码、不可测试核心),一次应用一个 SOLID / 整洁代码原则,并且绝不在展示之前应用设计变更。两个视角都读取相同的工具清单,写入相同的报告目录,并以相同的质量改进报告结束。
两个视角
| 工具视角 | 原则视角 | |
|---|---|---|
| 驱动 | 扫描器输出(summary.md) | 映射到 Principles.md 的设计坏味(smell-inventory.md、roadmap.md) |
| 工作单元 | 一个发现:一个文件:行的一个规则 | 一个有界热点上的一个原则:一次提取、一次类拆分、一次依赖反转 |
| 顺序 | P0 安全 → P1 正确性 → P2 可维护性 | 杠杆阶梯(见下文),按仓库调整 |
| 自主性 | 修复,然后显示差异 | 提议 → 确认 → 应用;未经批准不编辑任何内容 |
| 安全网 | 现有测试保持绿色 | 当目标未经测试时,首先编写表征测试 |
| 指标 | 更少的发现,工具重新运行无问题 | 重复百分比、圈复杂度、函数长度、扇入/扇出、“现在可单元测试” |
| 何时选择 | 静态检查/类型/安全债务、CI 红色、“让扫描器满意” | 抵制变更的代码;重构冲刺的结构层 |
循环
扫描 → 选择 → 安全网 → [提议 → 确认] → 修复 → 验证 → 报告 → 重复
└─ 原则模式下强制,工具模式下跳过 ─┘
工作流路由
| 触发词 | 工作流 | 产出 |
|---|---|---|
| “安装质量工具”、“设置代码质量” | Workflows/Install.md | 清单工具已安装并验证 |
| “扫描”、“基线”、“分析代码质量”、“坏味报告”、“我们应该先修复什么”、“重构路线图” | Workflows/Scan.md | summary.md (A)、smell-inventory.md (B)、roadmap.md (C) |
| “改进代码质量”、“修复 lint”、“质量循环”、“修复 [发现]” | Workflows/Loop.md 工具模式 | 修复、session-log.md、报告 |
| “重构”、“应用 SOLID”、“清理这个”、“开始循环” | Workflows/Loop.md 原则模式 | 修复、session-log.md、报告 |
| “清理这个仓库”(无修饰词) | 扫描 A + B + C,然后进入 Loop 原则模式 | 以上所有 |
| “重构冲刺”、“重构周期” | IssueFlow Remediation 拥有分支、PR 和合并;Scan 定义周期范围,Loop 执行它 | 每个周期一个 PR |
当未指定模式时,Loop 自行选择:仓库不存在 roadmap.md 时选择 工具,存在时选择 原则。用户可以强制指定。
清单
Tools/tools.tsv 是本技能中唯一的工具列表。制表符分隔,每种工具和语言一行:language category priority tool install run notes,其中 language 为 js | python | yaml,category 为 lint | format | types | security | deadcode | duplication | complexity | deps | coverage,priority 为 P0 | P1 | P2。两个脚本都读取它;工作流绝不内联列出工具。要添加或删除工具,编辑一行即可。
| 脚本 | 从清单读取 | 功能 |
|---|---|---|
Tools/install-quality-tools.sh [--dry-run] [lang ...] | 所选语言的 install 单元格 | 检测语言(package.json → js;pyproject.toml、requirements.txt 或 *.py → python;*.yaml/*.yml → yaml);将 js 工具作为 devDependencies 使用仓库的包管理器安装(lockfile → npm/pnpm/bun),python 和 yaml 工具使用 uv pip install 或 pip;npm:/pip: 前缀覆盖通道,- 表示不安装 |
Tools/run-quality-baseline.sh [--dry-run] [lang ...] | run 单元格 | 将每个工具运行到 reports/codequality/<YYYY-MM-DD>-<HHMMSS>/ 目录中,替换 $OUT(报告目录)、$SRC(QUALITY_SRC_DIRS,默认为 src(如果存在)否则为 .)、$PM 和 $NPX;未安装的工具标记为 MISSING,崩溃的工具标记为 FAILED,两者都不会停止运行;写入 summary.md,包含每个工具的状态、解析的问题计数以及 P0/P1/P2 总计;打印报告路径 |
run 为 - 的行(覆盖率工具)会被安装但不被基线运行:覆盖率在 Loop 中测量,范围限定于目标。每个工具都是免费的且本地运行;npm audit、pip-audit 和 checkov 仅访问网络以获取其漏洞数据库。
杠杆阶梯(原则视角默认顺序)
- 命名 — 你无法阅读的代码,你也无法安全地更改。成本低,解锁一切。
- DRY / 重复 — 以最低风险移除最多代码;暴露隐藏的抽象。
- 小函数 — 长方法 → 提取;每个函数保持一个抽象层次。
- SRP (单一职责原则) — 拆分因多个原因而变化的类和模块。
- OCP / DIP (开闭原则 / 依赖反转原则) — 反转依赖关系,添加接缝;影响大,风险更高,需要先有安全网。
- ISP / LSP (接口隔离原则 / 里氏替换原则) — 胖接口和破坏的可替换性;需要步骤 5 中的接缝。
扫描部分 C 根据实际清单调整此顺序(杠杆 = 影响 ÷ 风险;请参阅 Principles.md 第 3 部分)。
不可协商的规则
- 每次迭代只处理一项。 一个发现,或一个有界目标上的一个原则。小型、可审查的差异。
- 保持行为不变。 结构改变,行为不变。如果行为必须改变,停止并标记它:那是一个特性,而不是修复。
- 从绿到绿。 测试前后都通过。更改后变红意味着回退,绝不向前修复。
- 首先编写表征测试,当要触及的代码行未经测试时。没有安全网,不进行重构。
- 在应用任何设计变更(原则模式)之前先提议。 工具模式可直接修复,然后显示差异。
- P0 → P1 → P2 用于工具发现,跨语言,绝不按语言排序。
- 绝不削弱测试或 lint 规则 以使其通过。过时的测试移动到新的正确行为;规则在代码中得到满足。
- 童子军原则,但有边界。 保持接触的文件更整洁,但不要将范围扩大到当前项目之外。
- 证据,而非意见。 指出规则或原则,如果存在则提供指标。
输出产物
全部位于 reports/codequality/ 目录下(被 git 忽略):
| 文件 | 由谁写入 |
|---|---|
<YYYY-MM-DD>-<HHMMSS>/summary.md + 原始工具输出 | run-quality-baseline.sh(扫描 A) |
<YYYY-MM-DD>/smell-inventory.md | 扫描 B |
<YYYY-MM-DD>/roadmap.md | 扫描 C |
<YYYY-MM-DD>/session-log.md | Loop,每次迭代一个条目 |
<YYYY-MM-DD>/quality-report.md | Loop,在会话结束时(见下文) |
质量改进报告(强制)
每次 Loop 会话结束时生成此报告,无论哪种模式。它是与代码变更一起交付的产物,并且当工作通过 IssueFlow 输出时,是 PR 或追踪器评论的主体。
| 部分 | 内容 |
|---|---|
| 摘要表 | 新增 / 删除 / 净增行数;每个优先级的问题数(之前 → 之后);移除的死代码热点数;测试数量(之前 → 之后,全部绿色) |
| 删除的代码 | 文件、内容、行数、风险 |
| 新增或修改的代码 | 文件、内容、行数、目的 |
| 修复的缺陷 | 严重性、描述、根本原因(仅当出现问题时才包含) |
| 复杂性变化 | 之前 → 之后的最大和平均圈复杂度,每个热点附带 ASCII 条形图 |
| 延迟处理 | 已看到但超出范围的项目及其原因 |