+ 发布产品

maintainability-agent Skill 技能

## 技能简介 maintainability-agent 是一个离线、可重复的代码可维护性审计工具

AI编程开发
查看 Skill ↗
认领产品

技能简介

maintainability-agent 是一个离线、可重复的代码可维护性审计工具，输出直接可粘贴给 AI 编程 Agent 的"边界工单（bounded work order）"——每条发现附带精准位置、为什么重要、用什么命令验证，外加一条硬约束"只修这些、其它不要重构"。工具支持 15 种语言（Python、Java、Kotlin、C、C++、C#、Go、Rust、PHP、Ruby、Swift、Shell、COBOL free-form/fixed-form、JS/TS/HTML），每个语言的 scanner 都按该语言自己的"什么是分支"实现并与独立实现交叉校验。所有评分基于 201 个成熟开源仓库校准（B 级是中位线），不是阈值拍脑袋。它能同时跑在 CI（CLI）和 IDE 内（本地 MCP server），并提供 Claude Code slash command 一键调用。

核心能力

  • 15 种语言精确解析：每个语言用独立 scanner，按该语言自己的分支定义扫描；Shell/COBOL 用各自 grammar 直接校验
  • 基于 201 仓库的校准基线：所有评级是相对成熟开源的中位线（B = 中位），任何人都能按公布 query 复现
  • AI 工单直生成：每条 finding 一段可直接粘贴给 Claude Code / Cursor / 其他 Agent 的 prompt，限定"只修这些 + 不允许无边重构"
  • 可插拔分析器池：优先调用成熟工具（ruff、pylint、radon、lizard、complexipy、eslint、pmd、checkstyle、spotbugs 等），缺失时降级内置 detector 并在报告里诚实标注
  • 本地 MCP 服务器：pip install "maintainability-agent[mcp]" 后可在 IDE 内直接调审计能力
  • Claude Code slash command：内置 skill 安装到 ~/.claude/skills/，按 /maintainability-agent 触发
  • 安全子模块：自动跑 secure-code-agent（需另外装），覆盖 secrets / SCA / SAST
  • 可重复报告：maintainability-agent.json 配置驱动，无交互，CI 友好
  • 示例 demo：examples/demo 是一个故意带问题的订单系统，5 分钟跑完看完整输出

安装配置

  1. 核心 CLI：pip install maintainability-agent
  2. 带 MCP 服务器：pip install "maintainability-agent[mcp]"（给 IDE / chat host 用）
  3. Claude Code slash command：cp -r skills/maintainability-agent ~/.claude/skills/
  4. 强烈推荐的分析器池（pip）：pip install cohesion complexipy flake8 fortitude-lint interrogate lizard multimetric mypy pydocstyle pylint radon ruff vulture
  5. JS/TS 分析器（npm 全局）：npm install -g jscpd eslint
  6. JVM 语言（brew）：brew install pmd checkstyle spotbugs
  7. 安全子模块：pip install 'secure-code-agent>=0.12.10' + brew install gitleaks osv-scanner semgrep checkov（+ pip install bandit）
  8. 配置文件：从 https://raw.githubusercontent.com/marshallguillory86/maintainability-agent/main/maintainability-audit.example.json 下载一份，根据项目调整

使用步骤

  1. 下载配置 + 跑审计：curl -O https://raw.githubusercontent.com/marshallguillory86/maintainability-agent/main/maintainability-audit.example.json && maintainability-audit --config maintainability-audit.example.json --output report.md --prompt-output prompt.md
  2. 看报告：report.md 是证据汇总（评分、按文件 / 按 finding 类别分布、ISO/IEC 25010 0-5 评级）
  3. 取工单：prompt.md 是给 Agent 的"边界工单"——按优先级列出该修的 finding，每条带位置、why、验证命令，结尾统一强调"不许无边重构"
  4. 粘给 Agent：把 prompt.md 完整粘进 Claude Code / Cursor / Continue 即可；Agent 会严格按边界修复
  5. 首次无配置：maintainability-audit 不带 --config 会进入交互模式，问分析器池 / 扫描深度 / 许可证策略 / 是否跑测试套
  6. demo 试跑：examples/demo 仓库里有现成的 4 项 finding + 3 个 finding 类别 + 4 段 prompt + expected-prompt.md 标准输出
  7. 集成 CI：在 CI 里加 pip install maintainability-agent + maintainability-audit --config config.json --output report.md --prompt-output prompt.md，产物做 artifact 上传
  8. 用 MCP：在 IDE / Claude Desktop 里配 maintainability-agent MCP server，直接对话式审计代码

适用场景

  • AI 写代码太快、code review 来不及：Agent 一晚上产出上千行，需要个工具告诉 Agent"先精确修这 N 个地方"
  • CI 守门员：每次合并前审计，PR 注释直接贴 finding 摘要 + 给 Agent 的修复 prompt
  • 长期项目维护度量化：用同一个 0-5 评级跟踪 PR 是否让代码库更健康
  • 多语言 monorepo：Java + Kotlin + Python + JS/TS 一起扫，统一报告
  • Open source 项目治理：让贡献者提交前先跑一遍，避免"AI slop" 涌入
  • 遗留代码评估：接手老仓库，先跑一遍拿到改造优先级

适用人群

  • 重度使用 Claude Code / Cursor / Continue 写代码、想给 AI 立"边界规则"的资深工程师
  • 维护开源项目、需要可重复审计基线的 maintainer
  • Tech lead 想给团队定 CI 守门员、又不想重复造轮子
  • 平台工程 / DevEx 团队给所有语言仓库统一装一套审计

工作原理

maintainability-agent 把"审计 + 工单生成"拆成两层。审计层：每个语言有独立 scanner，按该语言自己的 AST / grammar 定义"什么是分支 / 重复块 / 长函数 / 复杂度"；优先调用成熟第三方分析器（ruff / pylint / eslint / pmd 等），降级到内置 detector 时报告里显式标注"Estimate source: built-in detectors"。所有评分基于 201 个成熟开源仓库校准——选仓库用 published query（非主观挑选），每个仓库 pin 到具体 commit，所以校准可被独立复现。工单生成层：审计完成后扫描每条 finding，根据"严重度 × 修复成本 × 上下文位置"生成一段独立 prompt，prompt 模板强制包含"只修这些 + 不许无边重构"的边界声明，外加验证命令。配置驱动（maintainability-agent.json）意味着 CI 与本机输出完全一致，安全子模块 secure-code-agent 在每次审计时自动跑（提供 secrets / SCA / SAST 维度）。可选 MCP 服务器把以上能力暴露为标准 MCP 工具，让 IDE / chat host 直接对话式审计。

官方链接

maintainability-agent 网站预览

团队信息

AI产品库 官方
由 AI 猎手自动发现

评论与建议

0 条评论