harness-audit

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 种介质）

1. CLAUDE.md / AGENTS.md — 软约束，项目知识
2. settings.json（.claude/settings.json）— harness 强制行为
3. Linter / 静态分析 — 形式化的硬约束（ESLint、ruff 等）
4. CI 流水线 — 合并前的终极防线（GitHub Actions 等）
5. Git hooks — 过程拦截（husky、lefthook 等）

认知层

6. 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 中），用四个问题检验它是否在正确的介质上：

1. 可以被形式化吗？（能否翻译成 function check(code): boolean）

   • 不能 → 应该放在 CLAUDE.md（认知层问题则放 Skill）
   • 能 → 继续问题二

2. 违反代价有多高？

   • 极高（数据丢失、安全漏洞、不可逆）→ CI 或 hook
   • 中等（返工、PR 打回）→ linter error
   • 低（风格、美观）→ linter warn

3. 反馈速度需要多快？

   • 立刻（会传染的错误）→ linter
   • 可以等（低频操作）→ 仅 CI

4. 被触发的频率多高？

   • 高频（>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 之前，先判断项目是否属于"一次性脚本"。