agentleFS
ArchAIHarnessArchAIHarness/agent-workflows/skills/quality/code-quality/SKILL.md

code-quality

Skill1 starsChanged 5 months agoMITView on GitHub

Use when the user asks for qa, 代码质量, 质量评估, 代码评估, 质量报告, 代码审查, code review, project quality, code quality, or quality report for a software project.

  • Reads credentials

80 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use logging-patterns, spring-boot and 10 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • DIL8654Skill

    logging-patterns

    Keep logs structured, correlated, low-noise, and safe for production support. Use when adding operational logging, reviewing observability, or improving diagnostics in .NET services.

    Also in 3 projects that use this

  • ffsshhttiikkSkill

    spring-boot

    Spring Boot framework and Java enterprise patterns

    Also in 3 projects that use this

  • mstuder-slalomSkill

    jpa-patterns

    JPA/Hibernate patterns for entity design, relationships, query optimization, transactions, auditing, indexing, pagination, and pooling in Spring Boot.

    Also in 3 projects that use this

  • glommerSkill

    pr-workflow

    General guidelines for Commits, formatting, CI, dependencies, security

    Also in 4 projects that use this

  • ffsshhttiikkSkill

    design-patterns

    Practical application and coding skills for Design Patterns

    Also in 4 projects that use this

  • abdullah1854Skill

    implementation-plan

    Also in 3 projects that use this

The file

Files
SKILL.md

核心原则

评估的标准是被评估项目自己的设计文档(README.md / AGENTS.md),不是通用规范。 代码符合项目自己的设计要求 = 合格,违反 = 不合格。

禁止事项

  • ❌ 询问用户
  • ❌ 中断等待确认
  • ❌ 提供选项让用户选
  • ❌ 跳过任何阶段
  • ❌ 跳过代码阅读(必须逐行分析核心文件)
  • ❌ 跳过文档阅读(README/AGENTS.md/配置必须读)
  • ❌ 跳过数字验证
  • ❌ 跳过评分计算器验证
  • ❌ 随便编造问题(必须有代码证据)
  • ❌ 发现问题后自行降级(对照 rules + 被评估项目设计文档定级)
  • ❌ 日志级别影响敏感信息泄露定级未区分
  • ❌ 仅看清单,不看设计意图

必须事项

  • ✅ 完整执行所有阶段
  • ✅ 保存报告到被评估项目根目录
  • ✅ 每个问题必须标注具体文件和行号
  • ✅ 检查结果必须使用颜色标识(P0🔴/P1🟠/P2🟡/P3🔵)
  • ✅ 问题描述必须基于实际代码
  • ✅ 发现 P0 问题必须在流程走查阶段定位
  • ✅ 问题定级必须交叉引用 rules + 被评估项目的设计要求

第一阶段:扫描 + 读懂项目设计

步骤 1.1:扫描所有文件

扫描项目所有代码文件和配置,不区分是否隐藏。

跳过规则:

  • ✅ 必须扫描:源码目录、配置文件
  • ❌ 跳过:依赖目录(node_modules/target/vendor)、构建产物(dist/build)、IDE配置、.git、.gitignore 中排除的目录/文件

步骤 1.2:读取项目设计文档(必须读,这是评估标准)

必须读取以下文档,提取评估标准:

文档提取什么
README.md(被评估项目自己的)项目简介、技术栈、架构设计、设计要求
AGENTS.md(被评估项目自己的,或 CLAUDE.md/GEMINI.md)分层规则、鉴权规则、技术约束、禁止事项、优先级定义
配置文件(.yaml/.json/.env)路由规则、认证策略、日志级别、运营配置

步骤 1.3:识别项目概况

属性值
项目名称{项目名称}
开发语言{语言}
技术框架{框架}
架构模式{模式}
代码规模{文件数} 个文件,约 {行数} 行
检查日期{YYYY-MM-DD}

步骤 1.4:提取设计要求(来自 README.md)

从被评估项目自己的 README.md 提取的设计要求将用于第三阶段:

被评估项目 README.md 设计要求(来自实际文档):
1. [分层规则] {提取内容}
2. [鉴权规则] {提取内容}
3. [技术约束] {提取内容,如禁止某类代码}
4. [禁止事项] {提取内容}
5. [优先级定义] {P0/P1 的具体含义}

第二阶段:代码审查(按设计 + 清单双视角)

审查视角 1:按被评估项目 README.md 设计要求检查(核心)

逐条对照 README.md 中的设计要求,检查代码实现是否满足:

被评估项目 README.md 设计要求代码实现是否满足违反定级
{规则1}{实现情况}是/否P0/P1/P2/P3

重点检查:

  1. 分层违规:被评估项目自己的 README.md / AGENTS.md 定义的分层规则是否被遵守
  2. 禁止事项:被评估项目自己的 README.md / AGENTS.md 明确禁止的代码模式是否出现
  3. 技术约束:如"禁止阻塞代码"、"禁止同步调用"是否被违反
  4. 鉴权规则:被评估项目自己的 README.md 描述的认证策略是否被正确实现

审查视角 2:通用缺陷模式检查(补充)

使用 rules_{语言}.md 进行清单式检查,重点关注跨语言通用缺陷:

缺陷类型检查方法定级
认证失败路径信任客户端输入找到认证失败的分支,看是否仍使用客户端可控的参数放行P0
认证成功路径信任客户端标识找到认证成功的分支,看用的是服务端生成标识还是客户端传入标识P0
注入漏洞看参数是否直接拼接到 SQL/命令/查询中P0
竞态条件看"先查后改"操作是否有并发保护P1
敏感数据泄露看日志/响应中是否打印/返回敏感信息P1/P2 按日志级别
资源泄漏看流/连接/线程池是否正确关闭P1
错误处理不当看异常是否被静默吞掉P1
配置硬编码看阈值/规则是否支持外部配置P2

日志级别与敏感信息定级

日志级别生产是否输出定级
error/warn/info✅ 是P1
debug❌ 否(默认)P2
trace❌ 否P3

检查输出格式

  • ✅ 通过 - 无问题
  • 🔴 P0: 问题 - 文件:行号 - 危险,有代码证据
  • 🟠 P1: 问题 - 文件:行号 - 告警
  • 🟡 P2: 问题 - 文件:行号 - 建议
  • 🔵 P3: 问题 - 文件:行号 - 轻微

第三阶段:业务流程走查(发现 P0 的关键)

第二阶段发现"代码有没有做某事",第三阶段验证"做的事对不对"。P0 级问题只有通过走查业务流程才能发现。

步骤 3.1:API 入口走查

对每个 API 端点沿请求链路走一遍:

端点: {METHOD} {PATH}
├── 认证: 认证失败/异常后是否放行?认证成功路径用服务端标识还是客户端标识?
├── 鉴权: 无认证路径是否可达受保护资源?权限校验是否完整?
├── 入参: 必填参数是否有校验?
├── 调用链: 请求 → 中间件/拦截器 → 业务逻辑 → 数据层
├── 异常: 每层异常是否正确处理?
└── 响应: 是否泄露敏感信息?

步骤 3.2:按设计要求逐条验证

将 README.md 设计要求与代码行为对照:

README.md 设计要求代码实际行为是否违反定级
{设计要求内容}{实际代码行为}是/否P0/P1/P2/P3

步骤 3.3:状态流转走查

对有状态的对象:

  • 画出状态机
  • 验证每个流转的前置条件
  • 查找非法跳转、终态可操作、状态竞态窗口

步骤 3.4:并发安全走查

对每个"先查后改"操作:

  • 检查查询和更新之间是否有并发保护(乐观锁/悲观锁/唯一约束)
  • 检查一次性资源是否有防重机制

步骤 3.5:敏感数据走查

  • 密钥是否明文存储在 DB/配置文件
  • Token/密码是否在响应中返回
  • 日志是否按级别区分敏感信息

定级规则(严格按规则执行)

  1. README.md(被评估项目自己的)设计要求标注 P0 的,违反即为 P0
  2. AGENTS.md(被评估项目自己的)标注 P0 的规范,违反即为 P0
  3. rules 标注 P0 的检查项,违反即为 P0
  4. 都没标 P0 但问题严重,按 P1
  5. 禁止降级:发现 P0 不能写成 P1

第四阶段:问题合并 + 评分 + 验证 + 报告

步骤 4.1:问题合并去重

  • 同一位置同一问题:保留定级高的
  • 同一位置不同角度:保留两个
  • 第三阶段定级更高:以第三阶段为准

步骤 4.2:扣分规则

定级扣分
P0-10
P1-5
P2-3
P3-1

步骤 4.3:维度扣分上限

各维度扣分上限 = 该维度权重分值。

步骤 4.4:评级标准

条件评级
有任意 P0🔴 不合格
无 P0,评分 ≥90🟢 优秀
无 P0,评分 80-89🟡 合格
无 P0,评分 70-79🟠 待整改
无 P0,评分 <70🔴 不合格

步骤 4.5:结论判定(严格三选一)

条件结论禁止
有任意 P0暂停上线禁止写其他
无 P0 有 P1限期整改后上线禁止写其他
无 P0 无 P1可上线禁止写其他

步骤 4.6:数字交叉验证

第一轮:问题数量对比 统计第3部分每个表格实际行数,与第2部分"合计"行对比。

第二轮:评分验证 用计算器验证评分:

node scripts/score_calculator.js '<问题JSON>'

第三轮:结论验证

  • 有 P0 → 暂停上线
  • 无 P0 有 P1 → 限期整改后上线
  • 无 P0 无 P1 → 可上线

验证通过才能保存报告。

步骤 4.7:生成报告

按 report.md 模板生成,包含 6 部分:

  1. 项目概况
  2. 评估结果汇总
  3. 问题详情(P0/P1/P2/P3 分级)
  4. 修复建议(按优先级分类)
  5. 结论(三选一)
  6. 检查规则

步骤 4.8:保存报告

保存路径:{被评估项目根目录}/质量报告_{项目名}_{日期}.md

禁止保存到 workspace 根目录。


参考文件

  • 规则文件: rules/rules_{语言}.md
  • 评分标准: rules/rules.md
  • 报告模板: report.md
  • 评分工具: scripts/score_calculator.js

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.