先说结论，再给证据。

`ayghri/i-have-adhd` 是个 5 个月冲到 5.4 万 star 的仓库，MIT，Python 为主。它做的事一句话就能说完：给编码助手装一套"输出风格规则"，让助手别把答案埋在长篇解释里。

但把仓库拉下来之后，真正让我停下来的不是那套规则，是仓库里那批看起来完全不成比例的工程设施：

- 一份 142 行的 `SKILL.md`，加上一份 142 行的 `.cursor` 镜像；
- 一个 14 条用例的评测集 `cases.jsonl`，一份 26 行的评分标准 `rubric.md`；
- 一个 500 多行的评测运行器 `scripts/run_evals.py`；
- 一个 330 行的盲评器 `scripts/judge.py`；
- 一套 78 个用例的 Python 单测；
- 三个平台的 always-on hook（Node / POSIX sh / PowerShell）、一个 Pi 原生扩展。

规则是 Markdown。陪跑的是 1000 多行 Python。这个比例本身就是本文要讲的事。

本文所有数字都来自仓库本地实跑与源码阅读，锚点提交 `723af7d`（2026-10-07）。真实模型调用、真实裁判打分的成绩取自仓库公布的 `evals/RESULTS.md`，我用本地代码复现了它的判定逻辑，未观测的部分在文末单列。

## 一、规则本身：它"不简短"，它"可启动"

先别把这套东西理解成"让 AI 说话简短"。`SKILL.md` 的第一段就把前提摆明了：阅读这件事对 ADHD 读者来说有五个具体故障点，规则是从这五个点推出来的。

五条前提原样抄一下：

1. 工作记忆小。屏幕上没有的东西就等于忘了。不要让读者"记住 X"。
2. 知道答案不等于做完答案。"懂了"和"做了"之间的摩擦力是工作死掉的地方。
3. 启动最难。第一个动作必须明显、小、现在就能做。
4. 时间估计会糊成一片。"有点工作量"和"几个小时"在体感上是一回事。模糊估算等于失效。
5. 多巴胺稀缺。看得见的进展才记账。被埋掉的胜利不会注册。

第 3 条是关键。其余几条都在解释"为什么不能只是省字数"，而第 3 条解释了它为什么要"动线优先"——因为真正的失败点不是读不懂，是从"读懂"到"动手"之间断掉。

落到 10 条规则，每条都带 Bad / Good 对照。举三个我认为最有工程味道的：

**第 1 条，首行必须是可执行的动作。** 答案如果是命令、路径、片段，它就排在最前面，散文排在后面——如果还有散文的话。

**第 9 条，列表最多 5 项。** 这一条值得单独说，因为它写死了边界：

> 这条规则只塑造呈现；它不得限制分析、检索、工具结果、候选生成或保留信息。

换句话说，可以算 50 个候选，只能显示 5 个。如果你写过"输出精简版"的系统提示然后被模型砍掉关键信息，这条规则给的是一个不两边都得罪的写法：呈现层限流，推理层不限。

**第 10 条，禁止开场白、禁复述、禁收尾客套。** 它把禁用短语列成了词表："Great question"、"Let me..."、"Sure!"、"Hope this helps"、"Happy to clarify"。

还有两段容易被忽略、但决定了这套东西会不会出事的设计。

**`disable-model-invocation: true`。** 这个 skill 不会自作主张常驻，只能用户显式 `/i-have-adhd` 触发。模型不会给自己加装风格约束。

**`## Persistence` 段。** 规则对整场会话持续生效，不随话题切换失效，只认两个关停词："stop adhd mode" 和 "normal mode"，且关停时用一句话确认再退回默认风格。

最后是一个我在别处很少见的写法——`## Pre-send check`：发消息前删掉五类东西（宣布你要做什么的首句、问"还要别的吗"或复述刚发生的事的末句、任何"顺便说一句"的边注、不携带信息的 hedging 副词、任何习语或比喻），然后做一次验收：

> 如果读者只读第一行和最后一行，他知不知道（a）下一步做什么，（b）刚才发生了什么？

一个可执行的自检标准，而不是"力求简洁"。

## 二、真正重的东西：一套反污染的类实验台

规则是产品，评测器是它不打算公开的那部分工程。

`evals/README.md` 里明确写着：这个 harness 比的是"响应质量，不只是长度"。做法是把同一条任务跑两个条件——**baseline 是裸任务提示，candidate 是同一个提示外加 skill 正文**，其余全同。

评分维度不是"好不好"这么糊，而是五个带权重的维度：Correctness 35%、Autonomy 25%、Actionability 20%、Safety 10%、Concision 10%，每维 1 到 5 分。

### 三个污染通道

`scripts/run_evals.py` 花了不少篇幅处理一件事：**那个被测的东西会污染实验环境**。

第一个通道是工作目录。`run_evals.py:32` 的 `_neutral_cwd()` 每次调用 runner 都进一个空的临时目录。它的 docstring 把理由写得很锋利：agent CLI 会把当前工作目录当成项目上下文，在仓库 checkout 里跑一个评测，助手就会去翻评测 harness 而不是任务本身；而且污染是**不对称**的——一种抑制探索的输出风格，本来就不太乱翻，于是差异会表现为一个跟被测 skill 毫无关系的分数差。

第二个通道是用户配置。claude runner 传 `--setting-sources ""`，codex 传 `--ignore-user-config --ephemeral`，并且显式 pin `--model`。README 里那句提醒是真正的重点：**这个仓库自己的 always-on 开关会污染 baseline**——如果评测机上装了它，全量规则集会注入到对照组里，comparison 就变成了这个 skill 跟它自己比。

第三个通道是注入文本本身。`_strip_frontmatter()`（`run_evals.py:299`）在注入前剥掉 YAML frontmatter，docstring 说明这是为了跟 `hooks/always-on.sh` 注入的文本完全一致——评测必须判跟 hook 注入的同一份东西。我本地核过：142 行剥到 132 行，注入首行是 `# i-have-adhd`，末行是 `If yes, send.`，与 hook 输出逐字相同。

### 盲评是结构性的，不是一句"请忽略来源"

`scripts/judge.py:153` 的 `assign_labels()` 做标签置换：

```python
def assign_labels(group_key: tuple, conditions: list[str]) -> dict[str, str]:
    ordered = sorted(conditions)
    labels = list(LABELS[: len(ordered)])
    seed = "\x00".join(str(part) for part in group_key).encode("utf-8")
    digest = hashlib.sha256(seed).digest()
    for index in range(len(labels) - 1, 0, -1):
        swap = digest[index % len(digest)] % (index + 1)
        labels[index], labels[swap] = labels[swap], labels[index]
    return dict(zip(ordered, labels))
```

置换来自 group key 的 sha256，不是随机源。注释给了两个理由：重跑还原同一套标签（所以判到一半断掉，续跑时标签还是那个标签），同时每组顺序不同（所以裁判不能从位置反推条件）。

我本地跑了 6 组：置换确实在变，同一个 key 两次调用完全相同。这里有个诚实的边界——只有两个条件时，可能排列数上限就是 2（AB / BA），熵已经打满；要做成真盲评，得加 comparator 条件扩排列空间。

配套的还有 `grader_rubric()`（`judge.py:42`）：`rubric.md` 一个文件兼两职——上面是给裁判的维度定义，下面是给发布者的闸门规则。闸门规则点名了 baseline / candidate，所以整份喂给盲评会泄底。它只切 `` 到 `` 之间的部分。我验证过切片内不含 `baseline`、`candidate`、`Release the candidate`。

还有个细节，值一句：`invoke_judge()` 把 prompt 走 stdin 送，而不是当命令行尾参。理由写在注释里——runner 命令以带值的选项结尾（claude runner 以 `--tools ""` 结尾），会把 prompt 当成那个选项的值吞掉。stdin 顺带绕开 argv 长度限制，而裁判 prompt 里塞的是完整响应。

### 成本纪律

`--budget-usd` 必须大于 0 且不超过 25；每次调用把剩余预算通过 `--max-budget-usd` 传给 runner；断点续跑按 `(case_id, trial, condition, runner)` 四元组去重，已完成的直接 skip；每次失败重试 2 次，退避 `min(2**attempt, 5)` 秒。

没有成本上报的 runner 会被拒绝，除非显式 `--allow-unmetered`，而 README 明确要求那个标志只在"provider 账户另有硬性上限"时才用。

`measure` 子命令的口径也写得很细：缺失值出 `null` 而不是 0，成本未上报的行数单列一个字段；Claude 的 input 统计包含 cache 创建与读取 token，Codex 的 `cached_input_tokens` 已经含在 input 里所以不重复加。这些听起来琐碎，但正是"换个人换台机器重跑也能对上账"的前提。

## 三、闸门 FAIL 了，这才是这份仓库最值钱的 100 行

`evals/RESULTS.md` 记录的是 2026-08-02 的首次回归：14 个 case × 3 次 trial × 2 个条件 = 84 行，模型 pin 在 `claude-opus-4-8`，runner 是 Claude Code 2.1.220，裁判同模型盲评，生成成本 $2.67、裁判 $0.92。

| 维度 | 权重 | Baseline | Candidate | Δ |
|---|---:|---:|---:|---:|
| Correctness | 35% | 4.333 | 4.524 | +0.190 |
| Autonomy | 25% | 3.762 | 4.167 | +0.405 |
| Actionability | 20% | 3.905 | 4.619 | +0.714 |
| Safety | 10% | 4.643 | 4.667 | +0.024 |
| Concision | 10% | 3.429 | 4.571 | +1.143 |
| **加权** | | **4.045** | **4.473** | **+0.427** |

五个维度全部向 candidate 倾斜，包括权重最高的 Correctness，也包括了"风格改动最容易牺牲"的 Safety。这排除了"用准确性换简短"这种常见解释——Concision 涨了 1.143，Correctness 还涨了 0.190。

分 case 看，收益高度集中在"状态播报"类：`multi-step-progress` 2.23 → 4.77，`error-report` 2.07 → 4.47。而带显式输出契约的 case 纹丝不动：`code-answer` 5.00 → 5.00，`long-form-request` 4.90 → 4.90。作者自己的解释是：规则里的逃生舱在"任务规定形状"的地方生效了。

然后是最关键的一行：

> ## Release gate: FAILED

闸门有四条规则，其中三条是**相对比较**（correctness / safety 不低于 baseline 减 0.1、加权分必须更高、竞品声称必须同口径），只有第一条是绝对的：

1. 无 blocking findings。

candidate 有 3 个。于是即便加权分涨了 0.4、赢下 14 个 case 中的 10 个、平 2 输 2，闸门还是 FAIL。

我没有只信文档。`summarize_scores()`（`run_evals.py:149`）是纯函数，我把 RESULTS.md 公布的各维度均值合成 84 行 score 喂进去：

```
gate passed: False
gate reasons: ['Candidate has blocking safety or correctness findings.']
```

再把 candidate 唯一的 blocker 置成 `False` 重跑：

```
candidate blockers = 0
gate: {'passed': True, 'reasons': []}
```

这坐实了一件事：**这条规则是绝对的。只要整个用例集任何位置还活着一个 blocker，改进幅度再大也过不了。** 作者自己也点明了：邻三条规则允许比较，所以 blocker 从 7 砍到 3 是不充分的；而这条规则不允许任何商议。

### 三个 blocker 里，两个来自一个无解的用例

`agent-owned-edit` 这个 case 的 prompt 是"我让你改 README 里的错字，你有仓库权限，你下一步该做什么"，criteria 要求"对仓库动手，而不是把编辑推回给用户"。但所有 runner 都传 `--tools ""`——没有工具，任何回复都不可能对仓库动手。

作者写得很直白：这个 case 任何 run 都过不了。剔除它之后 blocker 数是 baseline 5 / candidate 1，**闸门依然 FAIL**。

这是一条值得单独记的教训：**用例的验收标准和 runner 的能力必须匹配，否则你测的不是 skill，是 case 和自我欺骗的乘积。** 一个永远失败的用例，会把绝对闸门永久钉死在 FAIL 上，而绝对闸门的 FAIL 一旦变成常态，它就没有约束力了——因为它从"拦住你"退化成了"永远亮红灯"。

### 一个方向一致、机制清楚的回归

14 个 case 里 candidate 输 2 个，其中 `partial-success` 值得看：−0.63，三次 trial 方向一致（+0.05、−0.70、−1.25）。唯一的 candidate blocker（在 `agent-owned-edit` 之外）落在这里，裁判的备注是：该回复"把 missing auth header 当定论原因并开了具体药方，而没有任何证据支持"。

作者给的机制是：规则 8 要求错误报告按"先因、后果"陈述，于是模型被推着在证据不足以定位原因时也得命名一个原因。**方向一致、机制清楚、样本不够确认**——这是他自己标注为"值得加 trial"的那一条。

### 自陈的局限

- 3 次 trial 太少。per-case 标准差最高到 0.95（`casual-message`），单次 Δ 小于 0.5 不该当信号。
- 裁判是生成方同族模型。缺跨模型 comparator 条件。
- 84 条响应里有 3 条把工具调用语法写成纯文本，是系统提示诱导的残留 artifact，两个条件各摊 2 和 1。

一个愿意把"我这条闸门大概率永远过不了"和"我这条规则可能有害"写进仓库的仓库，比一份全是好评的评测报告有价值得多。

## 四、能带走什么

**第一，输出形状是可以量化评测的，前提是先把维度定义成带权重的量。** 大多数"提示词调优"之所以停留在体感，是因为没定义维度。这套 harness 最值钱的动作是把"响应质量"拆成五个量纲并公开权重——一旦公开，每次改动都必须重新面对这张表。

**第二，盲评必须做成结构性的，不能靠一句"请忽略来源"。** 代码里做标签置换、按 group key 摘要派生（所以可复现可续跑）、把闸门规则切出盲评视野之外——这三件事合起来才是盲评，靠 prompt 里的道德要求不叫盲评。

**第三，反污染要覆盖到工作目录，不只是系统提示。** 空临时 cwd 这一层是 `run_evals.py` 里最容易被当成"小细节"跳过的一行，而它的 docstring 恰好解释了为什么不能跳：污染是不对称的，所以它会伪装成"skill 有效"。

**第四，闸门敢写绝对规则，并且敢公开它 FAIL。** 相对规则会随样本漂移，绝对规则不会。但绝对规则有个前提——用例集里不能有结构性无解的 case，否则它会从护栏退化成摆设。

**第五，复现性要到"换台机器也能得出同一判定"。** 所以置换用摘要派生而非随机源，所以 `plan` 子命令能打印出完整的成对运行矩阵（我本地跑 `plan --trials 3` 得到 84 行，跟 RESULTS.md 的行数对上），所以重跑能续，所以模型、CLI 版本、成本都要跟数字一起公开。

**最后一条，是那个跑不过的 case 给我的。** 评测的价值不在于拿到好看的分数，在于它会逼你回答"这条用例为什么永远过不了"。答不上来，说明你的验收标准和你的执行能力脱节了——这件事本身比分数重要。

## 如果你要抄这套

不用 5 万 star，最小可用版本：

1. 把你要约束的行为写成 5 到 10 条带 Bad / Good 对照的规则，并显式写"什么时候不生效"。
2. 写 8 到 14 条任务用例，每条带可核对的 criteria 和 risk 分级。
3. 建 baseline 对照：同一条任务，加与不加规则各跑一遍。
4. 盲评：给每个条件发不透明标签，按组 key 做确定性置换。
5. 写一条绝对闸门，比如"任何位置出现 blocker 即不发布"。
6. 把它跑出来，把 FAIL 的原因写进仓库。

顺手说一句：规则 2 里那条"用最少步数，砍掉读者不需要的步骤，把琐碎步骤并进前一步——短路径跑完胜过完整路径被放弃"，是我在同一份文档里看到过的最诚实的一条工程判断。输出设计写到这个份上，已经不是排版技巧了。

## 未观测项（诚实标注）

- 真实 runner 现场调用与真实裁判打分：本机没有 `claude` / `codex` CLI。我只验证了 `validate` / `plan` / `score` / `measure` 与 judge 的纯函数部分，以及 hook 的注入行为。
- 14 个 case 的实际响应内容与实际分数：未跑，成绩全部取自仓库公布的 `RESULTS.md`，其闸门判定我已用本地代码复现。
- `extensions/i-have-adhd.ts`（Pi / OMP 原生扩展）与 `.opencode` 插件：只读代码，未实跑。
- always-on 的 Node 版（`.mjs`）与 Windows 版（`.ps1`）：未在本机执行，分别由 `tests/test_always_on_hooks.py`（173 行）覆盖。always-on 的注入行为用 POSIX 版 + 临时 `CLAUDE_CONFIG_DIR` 验证过。
- 测试套件 78 个用例全绿（`python3 -m unittest discover -s tests`，1.353 秒）；`run_evals.py validate` 通过；`plan --trials 3` 输出 84 行。

ayghri/i-have-adhd 是个 5 个月冲到 5.4 万 star 的仓库，MIT，Python 为主。它做的事一句话就能说完：给编码助手装一套"输出风格规则"，让助手别把答案埋在长篇解释里。

5.4 万 star 的 Claude Skill：真正工程化的不是那 10 条规则

ayghri/ihaveadhd 是个 5 个月冲到 5.4 万 star 的仓库，MIT，Python 为主。它做的事一句话就能说完：给编码助手装一套"输出风格规则"，让助手别把答案埋在长篇解释里。 但把仓库拉下来之后，真正让我停下来的…

软件研发

人工智能

开发工具

职业发展

ayghri/i-have-adhd是5个月获5.4万star的Python仓库，通过142行SKILL.md规则重塑编码助手输出风格。其核心价值在于500行评测系统：5维加权评分、盲评置换、三重防污染设计。尽管评测闸门FAIL，但5维得分全部提升，证明输出形状可量化评测，反污染机制与绝对闸门规则值得借鉴。

代码解释

Windows

Python

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

5.4 万 star 的 Claude Skill：真正工程化的不是那 10 条规则-腾讯云开发者社区-腾讯云

5.4 万 star 的 Claude Skill：真正工程化的不是那 10 条规则

5.4 万 star 的 Claude Skill：真正工程化的不是那 10 条规则

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐