| name | harness-audit |
| description | 审计项目的 AI agent harness 配置，评估完备性和合理性，检测反模式，给出优先级排序的改进建议。当用户想要审查 harness 配置、询问 harness 质量，或说"harness audit"、"检查harness"、"harness评分"、"harness检查"时使用。 |
Harness 审计
审计项目的 harness —— 那些引导和约束 AI agent（Claude Code、Cursor、Copilot 等）在本仓库中工作的外部结构。
理论基础：本技能的方法论源自知乎高赞回答 参考文章-五种介质方法论.md，原作者 情酱。核心框架包括：五种介质（CLAUDE.md / settings.json / linter / CI / Git hooks）的力学特性、四问题判定流、约束层与认知层的边界、以及错误信息即 prompt 原则。建议在理解审计标准之前先阅读该文章。
审计范围
约束层（5 种介质）
- CLAUDE.md / AGENTS.md — 软约束，项目知识
- settings.json（
.claude/settings.json）— harness 强制行为
- Linter / 静态分析 — 形式化的硬约束（ESLint、ruff 等）
- CI 流水线 — 合并前的终极防线（GitHub Actions 等）
- Git hooks — 过程拦截（husky、lefthook 等）
认知层
- Skills（
.claude/skills/）— 按需注入的知识
审计流程
阶段一：发现 — 有哪些？
扫描项目根目录和关键目录，寻找以下文件。对每一项标注：存在 / 缺失 / 部分。
CLAUDE.md / AGENTS.md：
CLAUDE.md、AGENTS.md、.claude/CLAUDE.md、.github/CLAUDE.md
settings.json：
.claude/settings.json、.claude/settings.local.json
Linter：
| 技术栈 | 需检查的文件 |
|---|
| TypeScript/JS | .eslintrc.*、eslint.config.*、.prettierrc* |
| Python | pyproject.toml（ruff/mypy）、.flake8、.pylintrc |
| Go | .golangci.yml |
| Rust | Cargo.toml（clippy）、rustfmt.toml |
| 通用 | .editorconfig |
CI：
.github/workflows/、.gitlab-ci.yml、Jenkinsfile、buildspec.yml
Git hooks：
.husky/、.git/hooks/、lefthook.yml、.pre-commit-config.yaml
Skills：
.claude/skills/、.cursor/skills/、.github/skills/
阶段二：质量评估 — 好不好？
对找到的每种介质，按以下维度评估质量。
CLAUDE.md 质量（0-5）
| 分数 | 标准 |
|---|
| 0 | 缺失 |
| 1 | 存在但内容空泛/占位 |
| 2 | 包含技术栈 + 目录结构 |
| 3 | 包含带示例的具体编码规范 |
| 4 | 包含具体的"做/不做"规则 + 引用了项目文件 |
| 5 | 精简（<80 行），只有具体规则，细节推到 docs/skills |
红旗标志：
- 超过 150 行（把所有东西塞进一个文件）
- 包含模糊规则，如"代码要简洁"、"write clean code"
- 约束层和认知层内容混在一起
- 缺少"不要/禁止"等明确否定词
settings.json 质量（0-5）
| 分数 | 标准 |
|---|
| 0 | 缺失 |
| 1-2 | 仅设置了模型 |
| 3 | 配置了 permissions allow/deny |
| 4 | 配置了 hooks（PostToolUse 触发 lint 等） |
| 5 | permissions + hooks + 模型锁定 + 敏感文件保护 |
红旗标志：
- 完全没有
deny 规则
- 缺少
.env 保护
- 没有
rm -rf / 危险命令拦截
Linter 质量（0-5）
| 分数 | 标准 |
|---|
| 0 | 未配置 |
| 1-2 | 仅使用默认预设（如 extends next/core-web-vitals） |
| 3 | 包含项目专属规则（no-restricted-syntax、自定义模式） |
| 4 | 错误信息面向 Agent 设计（说明了为什么 + 用什么替代 + 去哪里看） |
| 5 | 规则与架构边界对齐 + 错误信息即 prompt |
红旗标志：
- 所有规则都是 "warn" 级别（无实质约束力）
- 所有规则都是 "error" 级别（过于刚性，诱发绕过习惯）
- 错误信息简洁/面向人类（如 "Unexpected any"，无引导信息）
- 没有架构边界规则（如组件内直接 fetch、直接 import prisma）
CI 质量（0-5）
| 分数 | 标准 |
|---|
| 0 | 无 CI |
| 1-2 | 仅基本的 build + test |
| 3 | 包含 lint + typecheck + test + build |
| 4 | 包含特殊场景守卫（migration review、安全扫描、覆盖率阈值） |
| 5 | 与本地检查平衡（CI 是最后一道防线，不是唯一防线） |
红旗标志：
- 所有质量检查只在 CI 里，本地没有（反馈延迟问题）
- 没有覆盖率/安全检查门禁
- CI 耗时超过 10 分钟且阻塞所有进度
Git Hooks 质量（0-5）
| 分数 | 标准 |
|---|
| 0 | 无 hooks |
| 1-2 | 仅基本 pre-commit，只做格式化 |
| 3 | pre-commit 运行 linter |
| 4 | 包含 commit-msg 检查（约定式提交）+ lint-staged |
| 5 | Hook 链：format → lint → typecheck，延迟最小 |
红旗标志：
- Hook 存在但频繁用
--no-verify 绕过
- Hook 太慢（>5 秒）
- 没有 commitlint 或等价工具
Skills 质量（0-5）
| 分数 | 标准 |
|---|
| 0 | 无 skills 目录 |
| 1-2 | 有 1-2 个 skill 但内容空泛 |
| 3 | Skills 有具体的 description，能匹配到相关任务 |
| 4 | Skills 覆盖了常见项目工作流（工具函数使用、数据库模式等） |
| 5 | Skills 覆盖了 CLAUDE.md 无法单独处理的认知层缺口 |
红旗标志：
- Skills 目录存在但 skill 的 description 为空或无关
- 认知层内容放在 CLAUDE.md 而非 skills
- Skills 重复了 CLAUDE.md 已有的内容
阶段三：介质适配检查
对每条找到的活跃规则（在 CLAUDE.md、linter 配置、CI、hooks 中），用四个问题检验它是否在正确的介质上：
-
可以被形式化吗？（能否翻译成 function check(code): boolean）
- 不能 → 应该放在 CLAUDE.md（认知层问题则放 Skill）
- 能 → 继续问题二
-
违反代价有多高？
- 极高（数据丢失、安全漏洞、不可逆）→ CI 或 hook
- 中等（返工、PR 打回）→ linter error
- 低（风格、美观）→ linter warn
-
反馈速度需要多快？
- 立刻（会传染的错误）→ linter
- 可以等（低频操作）→ 仅 CI
-
被触发的频率多高？
- 高频（>5 次/周）→ 值得写自定义 linter 规则
- 低频（<每月）→ 即使可形式化也放 CLAUDE.md 就够了
标记每条未通过此检验的规则（例如：一条可形式化的高代价规则留在 CLAUDE.md 里，或一条不可形式化的模糊规则写进了 linter）。
阶段四：反模式检测
检查以下常见反模式：
| # | 反模式 | 检测方法 |
|---|
| 1 | CLAUDE.md 垃圾场 | CLAUDE.md >150 行，什么都在里面 |
| 2 | CI-only 质量 | Linter/hooks 缺失但 CI 里有很多检查 |
| 3 | 模糊的 CLAUDE.md 规则 | "保持整洁"、"简洁"等规则，没有具体内容 |
| 4 | Harness 过硬 | 所有 linter 规则都是 error，频繁使用 --no-verify |
| 5 | Harness 过软 | 所有 linter 规则都是 warn，无实质约束 |
| 6 | 人类错误信息 | Linter 信息简短，没有"为什么/替代方案/示例" |
| 7 | 约束-认知混淆 | 认知层内容放在 CLAUDE.md，约束规则放在 skills |
| 8 | settings.json 被忽视 | 该由 settings.json 做的事（权限、模型锁定）写在了 CLAUDE.md |
| 9 | 敏感文件未保护 | 没有 deny .env、credentials、migrations |
| 10 | 无反馈速度梯度 | 所有检查在同一层级，缺少 linter→hook→CI 梯度 |
阶段五：评分
完备性评分（0-10）：
= CLAUDE.md 得分 (0-2) + settings.json 得分 (0-2) + linter 得分 (0-2)
+ CI 得分 (0-2) + git hooks 得分 (0-1) + skills 得分 (0-1)
各项：0=缺失，1=部分，2=存在且质量良好。
合理性评分（0-10）：
= 介质适配得分 (0-4) [规则是否在正确的介质上]
+ 反模式倒扣 (0-3) [0个反模式=3, 1-2个=2, 3-4个=1, 5+个=0]
+ 反馈梯度 (0-2) [linter→hook→CI 时机是否恰当]
+ 错误信息质量 (0-1) [是否面向 Agent 编写错误信息]
综合等级：
| 分数范围 | 等级 | 描述 |
|---|
| 16-20 | A | 成熟的 harness，各层均衡 |
| 12-15 | B | 能干活，但有缺口 |
| 8-11 | C | 基础配置，改进空间很大 |
| 4-7 | D | 最简 harness，Agent 基本在裸奔 |
| 0-3 | F | 无 harness，全靠模型直觉 |
阶段六：改进建议
生成按优先级排序的可操作改进列表。每条建议包含：
- 优先级：P0（立即）/ P1（本周内）/ P2（本月内）/ P3（有空再做）
- 操作：具体要创建/编辑哪个文件，添加什么内容
- 原因：修复了哪个反模式或提升了哪项分数
- 成本：低（<10 分钟）/ 中（<1 小时）/ 高（>1 小时）
优先级规则：
- P0：安全缺口（无 settings.json deny、敏感文件未保护）
- P1：缺少应该有但没有的介质（完全没有 linter、没有 CI）
- P2：质量改进（更好的错误信息、规则迁移到正确介质）
- P3：锦上添花（更多 skills、A/B 测试机制）
输出格式
以结构化报告呈现：
# Harness 审计报告 — [项目名称]
## 概览
- **综合等级**：A/B/C/D/F（xx/20）
- **完备性**：x/10
- **合理性**：x/10
- **关键发现**：[一句话总结]
## 组件清单
| 介质 | 状态 | 评分 | 关键问题 |
|------|------|------|----------|
| CLAUDE.md | 存在 | 3/5 | ... |
| settings.json | 缺失 | 0/5 | ... |
| Linter | 存在 | 4/5 | ... |
| CI | 部分 | 2/5 | ... |
| Git hooks | 存在 | 3/5 | ... |
| Skills | 部分 | 2/5 | ... |
## 发现的反馈式
1. **[模式名称]** — [文件:行号] — [影响]
## 介质适配违规
[列出放在了错误介质上的规则，及建议迁往何处]
## 改进建议
| # | 优先级 | 操作 | 成本 | 预期收益 |
|---|--------|------|------|----------|
| 1 | P0 | ... | 低 | ... |
| 2 | P1 | ... | 中 | ... |
| ... | ... | ... | ... | ... |
## 快速见效（<30 分钟总计）
[2-3 项低投入高回报的事]
注意事项
- 如果某种介质不适用于该项目技术栈（如不用 TypeScript 所以没有 ESLint），标注说明并跳过该组件的评分。
- 对于 monorepo，如果每个 package/app 有独立的 harness 配置，需要分别审计。
- 处于原型阶段的项目（核心抽象未定型），默认建议轻量 harness——不要过度工程化。
- 在建议重仓投入 harness 之前，先判断项目是否属于"一次性脚本"。
