QUALITY.md 上 Show HN：给 AI Agent 立规矩的开源标准来了

昨天 Hacker News 上冒出来一个 Show HN 帖子，作者甩出了一个叫 QUALITY.md 的东西——一份规范、一个 Agent Skill、一套 CLI，三合一。项目地址是 getquality.md，看起来朴素得像个静态页。但底下评论区吵得挺热闹，几个熟脸都在留言，包括之前做 Agent Skills 目录站的那批人。

简单说，这是一次针对 AI 编码 Agent 的质量约束标准化尝试。Cursor 有 .cursorrules，Claude Code 有 CLAUDE.md，Aider 有自己的配置，Copilot 有自己的一套。每家格式不一样，团队规矩每次接一个新工具就得重写一遍。QUALITY.md 的思路是：干脆定一份和模型无关、和工具无关的开放格式，让'什么叫高质量代码'这件事变成一个可以版本控制、可以复用、可以校验的文件。

听起来像不像 EditorConfig？作者在评论区自己也认了这个类比。但比 EditorConfig 野心大得多——那个只管缩进和换行，QUALITY.md 想管的是命名、结构、测试覆盖、注释密度、API 设计原则，甚至团队的技术债偏好。

一份文件、一个 Skill、一套 CLI

QUALITY.md 的设计分成三层，这是它区别于同类项目的关键。

第一层是规范本身。一个 QUALITY.md 文件，Markdown 格式，带 YAML frontmatter。frontmatter 里放元数据（版本、语言、适用范围），正文用结构化的段落描述具体规则。这里有意思的地方是，作者没有强推 JSON Schema 或者 TOML 那套死板的字段定义，而是刻意保留了自然语言的表达空间——因为质量这件事本来就不是全都能量化的。

举个例子，一份典型的 QUALITY.md 里可能会写：

---
name: backend-service-quality
version: 0.3
languages: [go, python]
scope: services/**
---

## Error Handling
- 所有对外接口必须返回结构化错误，禁止裸抛 panic
- 内部函数可以用 error wrapping，但错误链不超过 3 层
- 日志里不要打印完整堆栈到 INFO 级别

## Testing
- 新增 handler 必须有集成测试覆盖 happy path 和至少一个错误分支
- 单测覆盖率不硬性要求，但 diff 覆盖率不低于 70%

看起来平平无奇，但关键在于：这份文件既是给人看的，也是给 Agent 看的。人读起来就是团队 wiki 的一部分，Agent 读起来就是一份行为约束。

第二层是 Agent Skill。QUALITY.md 天然按 Anthropic 去年推的 Agent Skills 开放格式打包，也就是一个包含 SKILL.md 的目录，附带 scripts/ 和 references/。Skill 的 description 字段会告诉 Agent：'当你要写代码、审查代码、生成 PR 描述、或者被要求评估代码风格时，激活这个 Skill'。

这一步其实是整个设计里最聪明的地方。作者没有另起炉灶发明一套加载机制，而是直接搭上 Agent Skills 已有的 Discovery → Activation → Execution 生态。Claude Code、Cline、以及一堆基于 Skills 规范的 Agent 框架都能直接消费，不需要额外适配。

第三层是 CLI。装上以后可以：

• quality init 交互式生成项目的 QUALITY.md
• quality lint <file> 用 QUALITY.md 里的规则检查一个文件或一个 diff
• quality explain <rule> 让 CLI 反过来解释某条规则的意图和历史
• quality sync 把 QUALITY.md 转成 CLAUDE.md、.cursorrules、Copilot instructions 等多家格式

最后这个 sync 命令是杀手锏。作者显然清楚一件事：你不可能指望所有 IDE 和 Agent 都马上来支持你的新格式，那就反过来当翻译层，让 QUALITY.md 成为规则的'单一真相源'。写一次，各处能用。

为什么现在冒出来这么个东西

把时间轴拉回来看，AI 编码 Agent 从去年到今年经历了两轮明显的洗牌。第一轮是模型能力上限抬高，Claude 4 系列、GPT-5 系列、Gemini 3 陆续落地之后，'能不能写对'不再是主要矛盾。第二轮是 Agent 化——从补全到自主执行，Claude Code、Codex CLI、Cursor Agent 这些工具让 AI 开始真的在代码库里长时间跑任务。

矛盾就在第二轮里暴露出来了。模型不缺能力，缺的是上下文里的约束。一个 Agent 跑十分钟可能改了二十个文件，如果它不知道你团队的规矩，产出往往是'看起来对但没法合并'。于是过去大半年，各种约束文件层出不穷：

• Anthropic 的 CLAUDE.md（去年成为事实标准之一）
• Cursor 的 .cursorrules 和 rules 目录
• Aider 的 conventions.md
• GitHub Copilot 的 copilot-instructions.md
• 各种 MCP 服务器暴露的规则接口

每个都想当标准，结果就是没标准。团队里维护一份规则文件已经够累了，同步到四五个工具下更是灾难。QUALITY.md 的价值主张说白了就一句话：你别管我们下面接哪个 Agent，规矩都写在这里。

这也是它取名叫 QUALITY.md 而不是 AGENT.md 或者 RULES.md 的原因。作者在评论区解释过：这不是给 Agent 的配置文件，是给项目的质量宣言，Agent 只是恰好也会读。语义上把主语调整了一下，长期看更容易被非 AI 场景采纳——比如 code review 时人也可以拿来对照。

和 Agent Skills、MCP 是什么关系

看到这里可能有人要问：这不就是 Agent Skills 套了个壳？

答案是——是，但也不是。QUALITY.md 在物理形态上确实是一个符合 Agent Skills 规范的 Skill，能被任何支持 Skills 的 Agent 加载。但它比标准的 Skill 多做了两件事：

1. 约定了内容结构。普通 Skill 的 SKILL.md 里想写什么都行，QUALITY.md 规范约束了必须包含哪些质量维度（错误处理、测试、命名、文档等），保证不同项目之间可以对比、可以聚合。
2. 提供了双向转换。普通 Skill 是单向消费的，QUALITY.md 通过 CLI 反过来能生成其他工具的配置文件，形成互操作。

和 MCP 的关系就更清楚了。MCP 解决的是 Agent 怎么连接外部工具和数据源的问题——数据库、Slack、Jira、代码检索。QUALITY.md 解决的是 Agent 怎么理解本项目内在规矩的问题。前者给 Agent 装手脚，后者给 Agent 立规矩，一个在外，一个在内。

挑刺时间

夸完了讲问题。这个项目现在的状态还很早，v0.3，主页干净得像个 landing page，README 里几个例子都是小项目。真要在中大型代码库落地，几个问题绕不开。

规则冲突怎么处理？ 一个 monorepo 里，前端团队和后端团队的质量偏好几乎肯定不同。规范里提到了 scope 字段可以按目录划分，但当规则互相矛盾时（比如根目录一份 QUALITY.md 说'禁止使用 any'，某个子目录说'允许 any 但需要注释'），Agent 怎么决策？作者说走'就近原则'加'显式覆盖'，但这种事情工程上永远比设计上难。

规则的执行力度是软是硬？ QUALITY.md 里的规则是给 Agent 参考，还是硬约束？如果是硬约束，就得配套 linter；如果是软约束，Agent 每次都可能'刚好这次觉得违反一下也 OK'。CLI 的 lint 命令目前主要靠正则和 AST 简单匹配，加上一部分调用 LLM 做语义判断——这套混合执行的可靠性有待验证。

生态启动问题。这是所有'我们来做标准'项目的通病。你说 QUALITY.md 是单一真相源，但如果 Cursor 不主动支持、Copilot 不主动支持、只能靠 CLI 单向 sync，那实际使用体验就是永远差一层。作者需要在早期把最主要的几个 Agent 拉进来官方支持，否则很容易变成又一个没人用的规范。

和 CLAUDE.md 的关系微妙。Anthropic 自家的 CLAUDE.md 已经在开发者群体里形成了一定习惯，很多项目根目录早就躺着一份。QUALITY.md 想成为上位标准，就得说服这些已经写好 CLAUDE.md 的团队再迁移一次。作者的策略是让 CLI 支持从 CLAUDE.md 反向导入生成 QUALITY.md，算是给了迁移路径，但用户会不会买账还得看。

值得关注的点

抛开这些具体问题，我觉得 QUALITY.md 反映了一个更大的趋势：AI 编码工具的竞争正在从模型能力和 IDE 集成，向更上层的'团队工程规范'转移。

过去两年，工具厂商拼的是接哪家模型、有没有 tab 补全、能不能跑 Agent。到今年，前面这几件事基本追平了。真正让一家公司用起来舒服的差异，来自它对团队既有工程实践的适配能力——你写 Go 的规矩、你 review 代码的偏好、你怎么起变量名，Agent 得记得住。

谁抓住了这一层的抽象，谁就有机会成为下一个 GitHub。QUALITY.md 是个人项目、v0.3、评论区还有人质疑名字取得对不对，但它切的角度是对的。至少比再造一个 IDE、再包一层 UI 有意思得多。

后面几个观察点：一是 Anthropic 或 GitHub 会不会把这套东西直接吸纳成官方 Agent Skills 的子规范；二是国内的 AI 编码工具——CodeGeeX、Trae、通义灵码这些——会不会跟进；三是开源社区会不会自发出现 QUALITY.md 的模板库，就像 gitignore.io 那样，让不同技术栈的团队开箱即用。

如果你手上正好在维护一份 CLAUDE.md 或者 .cursorrules，可以先花十分钟去 getquality.md 看看，跑一下 quality init，看它生成的结果和你手写的差距在哪。这种早期项目的价值往往就在这——不一定要用，但看一眼能帮你梳理一下自己对'质量'的定义。

参考来源

• Agent Skills 开放标准来了：AI Agent 终于有了'可复用技能包' - 博客园 — Agent Skills 规范的中文解读，QUALITY.md 底层复用的就是这套开放格式
• 「AI Agent Skill」的本质是什么 - 知乎专栏 — 从架构视角解释 Skill 如何被 Agent 发现和激活，理解 QUALITY.md 加载机制的背景阅读