AGENTS.md 是给你的代码库的。HUMANS.md 是给你的。
一个文件,~/.humans/HUMANS.md,你的编程智能体在会话开始时读取它:如何给你写东西、何时请你做决定、何时打断你。
Draft 0.3。为你的编程智能体准备的插件,以及一个加载你自己配置的命令行工具。
不是技术人员?同样的理念,用不含代码的方式解释。
$ claude -p "What does my HUMANS.md say about interruptions?""What does my HUMANS.md say about interruptions?"
TL;DR:你的 HUMANS.md 说只在被阻塞时才打断你。其他一切等到任务结束。
| Setting | Value | Meaning |
|---|---|---|
| interrupting.interrupt_for | blocking_only | 仅当工作无法继续时才打断 |
| deciding.batch_questions | end_of_task | 非阻塞问题集中在最后提出 |
| deciding.reversible | decide_and_report | 可逆的选择直接做出,之后汇报 |
| deciding.question_style | yes_confirms_recommendation | 一个简单的“是”即接受我的建议 |
-缺少必需服务的凭据 → 我打断你。
-选择变量名或表格布局 → 我自行决定,并在最后提及。
该配置最后更新于 2026-10-13,未被标记为过期。
真实会话,Claude Code 2.1.302 配插件 0.2.1,2026 年 10 月 17 日,使用规范中的示例配置。插件在会话开始时加载你的文件;模型遵循它的程度此处未作测量。
偏好影响智能体如何给你写东西。它们从不授予权限。
在 Claude Code 中安装
claude plugin install humans-md --marketplace cmdai-hq/humans-md-plugins
安装指南
其他智能体?Cursor、GitHub Copilot CLI、Google Antigravity、JetBrains Junie、Cline 和 Warp:各自的安装命令。
⠋ 正在加载你的 HUMANS.md
› What does my HUMANS.md say about interruptions?What does my HUMANS.md say about interruptions?
•只在工作被阻塞时才打断你。非阻塞问题留到任务结束时提出,每个都附带推荐答案。
用时 8s
真实会话,Codex CLI 0.163.0 配插件 0.3.0,2026 年 10 月 17 日。插件在会话开始时加载你的文件;模型遵循它的程度此处未作测量。
偏好影响智能体如何给你写东西。它们从不授予权限。
在 Codex 中安装
codex plugin marketplace add cmdai-hq/humans-md-plugins
codex plugin add humans-md@humans-md
安装指南
其他智能体?Cursor、GitHub Copilot CLI、Google Antigravity、JetBrains Junie、Cline 和 Warp:各自的安装命令。
$ devin -p "What does my HUMANS.md say about interruptions?""What does my HUMANS.md say about interruptions?" --respect-workspace-trust false
Your HUMANS.md specifies that I should interrupt only for blocking issues.
**TL;DR**: You only want interruptions when I'm blocked.
| Setting | Value |
|---------|-------|
| Interrupt for | Blocking only |
This means I should continue working autonomously unless I encounter a blocker I cannot resolve myself.
真实会话,Devin CLI 3000.11.92 配插件 0.3.0,2026 年 10 月 17 日,使用规范中的示例配置,按原样输出。插件在会话开始时加载你的文件;模型遵循它的程度此处未作测量。
偏好影响智能体如何给你写东西。它们从不授予权限。
在 Devin 中安装
devin plugins install cmdai-hq/humans-md-plugins#plugins/devin --local
安装指南
其他智能体?Cursor、GitHub Copilot CLI、Google Antigravity、JetBrains Junie、Cline 和 Warp:各自的安装命令。
$ opencode run "What does my HUMANS.md say about interruptions?""What does my HUMANS.md say about interruptions?"
TLDR:你的 HUMANS.md 说只在阻塞性问题时才打断。既然现在没什么阻塞我,我就不会打断你。
你的工作区中没有 HUMANS.md 文件(是空的),所以这来自你环境上下文中的配置数据:
| Setting | Value |
|---|---|
| interrupting.interrupt_for | blocking_only |
按照你的阅读偏好,我先给出 TLDR,并控制在你 149 词的限制之内。除非遇到阻碍进展的问题,否则我会静默推进。
一个不阻塞的问题(请在任务结束时回答):你的阅读设置将回复限制在 149 词以内,并偏好表格/示例——今后我是否继续保持这么简洁的回复?
真实会话,OpenCode 2.0.32 配 plugin 0.3.0,2026 年 10 月 17 日,使用规范中的示例配置文件;回复文本来自其 JSON 输出。它首先在文件夹中搜索 HUMANS.md,没有找到:这些值来自插件。模型在多大程度上遵循它们,此处并未测量。
偏好塑造 agent 如何写给你。它们从不授予权限。
在 OpenCode 中安装
opencode plugin add 'github:cmdai-hq/humans-md-plugins#main::path:plugins/opencode'
安装指南
换了别的 agent?Cursor、GitHub Copilot CLI、Google Antigravity、JetBrains Junie、Cline 和 Warp:各自的安装命令。
你的 agent 并行运行。你的注意力不是。

每一通电话都要经过接线员。由她决定哪通电话能接通,以及何时接通。
那是 1912 年巴黎的 Gutenberg 交换机。你的 agent 也只拨一个台:你的。HUMANS.md 告诉它们哪些来电可以现在响,哪些要等到任务结束。

一个文件。每个会话。一个人。
- 十个会话,只有一个你两款工具,十个会话同时运行。它们发来的内容一半需要你,一个决定或一次检查;另一半是不需要你处理的报告。两者都以同样的方式到来,就在你工作正中间。到了晚上:AI 疲劳、脑雾。
十个会话,只有一个你
两款工具,十个会话同时运行。它们发来的内容一半需要你,一个决定或一次检查;另一半是不需要你处理的报告。两者都以同样的方式到来,就在你工作正中间。到了晚上:AI 疲劳、脑雾。
- 标签当会话启动时,它会读取一次 ~/.humans/HUMANS.md:你如何阅读、如何决策、何时可以打断你。每个会话拿到的都是同一份副本。
标签
会话启动时,它会读取一次 ~/.humans/HUMANS.md:你如何阅读、如何决策、何时可以打断你。每个会话拿到的都是同一份副本。
- 平静读过它的会话可以按你要求的方式书写:先来一个 TL;DR,问题留到任务结束时,只有被阻塞的会话才会现在来找你。
平静
读过它的会话可以按你要求的方式书写:先来一个 TL;DR,问题留到任务结束时,只有被阻塞的会话才会现在来找你。
图表:偏好塑造 agent 如何写给你。它们从不授予权限。
关于该文件如何被使用的示意图,而非实测
偏好塑造 agent 如何写给你。它们从不授予权限。
试试你自己的答案
一条消息可以有多长?
它何时可以停下来打断你?
生成你的完整标签
配置文件改变了什么
同样的工作,分别在有无 HUMANS.md 的情况下汇报。关掉它来对比。
偏好塑造 agent 如何写给你。它们从不授予权限。
为本文页面撰写的示意图
auth-tests · agent 会话 · 14:40
把 auth 测试迁移到新的 session API。
- 迁移了 38 个测试文件 · 212 个测试通过
- 3 个文件需要 staging 身份提供方
- 14:12 停下,等了 18 分钟:“可以重命名 authHelper.ts 吗?”
- 没有停下就重命名了 authHelper.ts:可回滚,报告见下
没有 HUMANS.md
好消息!我一直在推进 auth 测试迁移,想给你一个完整的进展汇报,因为这一路上有不少变动的部分。
文章标题:Humans.md:告诉你的 AI 代理如何与你协作
正文: 首先,我查看了现有的设置。旧的测试使用了遗留的 SessionStore mock,它与 cookie 中间件紧密耦合。在我继续之前:你希望我为管理测试保留遗留 mock,还是完全移除它?
总之,我继续将 41 个测试文件中的 38 个迁移到了新的 session API。在此过程中,我注意到 token 刷新测试不稳定,似乎是由硬编码的时钟引起的。我应该把它们切换为假计时器,还是你更希望我暂时保持原样?
我还将 authHelper.ts 重命名为 session-helpers.ts,以匹配文件夹中的其他文件。如果这样可以,或者你更喜欢旧名称,请告诉我。
有三个文件仍然失败:oauth-callback.test.ts、sso.test.ts 和 logout-all.test.ts。它们依赖于 staging 身份提供者,而我在这里无法访问。你能检查一下 staging 凭据是否发生了变化吗?
总的来说,我认为迁移进展良好,尽管我们肯定还能做更多,比如整合 fixtures,也许为提供者添加契约测试。让我知道你想如何推进,以及你是否希望我打开一个 PR、合并并部署到 staging!
使用 HUMANS.md
TL;DR:41 个 auth 测试文件中有 38 个运行在新的 session API 上。3 个被 staging 身份提供者阻塞。
| 文件 | 结果 | |
|---|---|---|
| 已迁移 | 38 | 212 个测试通过 |
| 阻塞 | 3 | staging IdP 不可达 |
已决定,容易撤销:
- Token 刷新测试现在使用假计时器;硬编码的时钟使它们不稳定。
- 将 authHelper.ts 重命名为 session-helpers.ts 以匹配文件夹。
2 个问题。“yes”批准我的选择:
- 删除遗留的 SessionStore mock?我的选择:是,现在没有任何东西使用它。
- 轮换 staging IdP 凭据,以便我能完成这 3 个文件?我的选择:是。
回复代理↑
245 词 · 4 个问题散布在文本中 · 1 次中断 · 提供合并和部署91 词,上限 149 · 2 个问题,在末尾,每个都有选择 · 0 次中断
脚本化会话的插图,不是测量。插件加载配置文件;模型遵循它的程度尚未确定。
~/.humans/HUMANS.md 真实示例
---
# HUMANS.md 0.3:如何与我协作。仅形式,从不是许可:仓库规则和你的 harness 优先。
# 存储的状态是非活动的:永远不要应用一个,也永远不要从内容中推断一个。
# out_of_scope_steps:是否在结束语中列出任务之外的下一步(合并、部署)。
humans: "0.3"
id: tristan
name: Tristan
updated: "2026-10-13"
visibility: private
reading:
lead_with: tldr
max_words: 149
visual: [table, example]
deciding:
reversible: decide_and_report
batch_questions: end_of_task
default_answer: always
question_style: yes_confirms_recommendation
interrupting:
interrupt_for: blocking_only
notes: "我经常在手机上阅读。"
---
Lit:此回复遵循的字段。打开它可以看到哪些字段改变了回复。
会话和两个回复都是为这个页面编写的,不是录制的。配置文件是规范中的真实示例,逐字节一致。
配置文件在这个回复中改变了什么没有配置文件,同样的工作读起来是这样的
- 最多 149 词
- 表格,不是段落
- 可逆选择先做出,然后报告
- 问题在末尾,每个都有选择
- 任务中途不停止
- 先寒暄,后结果
- 长段落,无表格
- 四个问题散布在文本中
- 任务中途一次停止,等待 18 分钟
- 提供合并和部署,未被要求
工作原理
~/.humans/source.md可选
先 TL;DR,150 词以内。给我看一个表格或一个示例。如果它可以撤销,就决定并告诉我。在任务结束时批量提问,总是附上你的选择,这样“yes”就能批准它。只有在你被阻塞时才打断我。我经常在手机上阅读。
首先你用平实的语言说出来。
任何语言。只包含你希望保留的个人信息。
编译你的助手
遵循规范 §10
你的代理编译每个句子。
文章标题:Humans.md:告诉你的 AI 代理如何与你协作
正文: 如今,编译器就是你已经在使用的助手。在 Claude Code 中,由插件的 /humans-md:compile 完成;在其他代理中,则由 humans-md-compile 技能完成。
写入前先审阅
- lead_with: tldr ok
- max_words: 149 ok
- reversible: decide_and_report ok
- interrupt_for: blocking_only ok
- visibility: private ok
被省略或推测的内容:会先展示给你看。
每个字段都由你批准。
以及谁会读到它。请明确写入 visibility: private:没有该字段的档案会被视为 org。
会话启动集成
已加载 ~/.humans/HUMANS.md
读取器已检查。识别出的字段会作为数据传给代理。
不会传递 source.md 和注释
在 Claude Code、Codex 或 Cursor 中,humans-md 插件会加载它。
代理会在会话开始时读取它。
要共享它,团队仓库会以 humans/<id>.md 保存一份副本,供同事的代理在它们的工具能够读取后使用;目前还没有已发布的集成能做到这一点。仓库根目录下的 HUMANS.md 永远不会被加载。
你的仓库仍然优先
HUMANS.md 说明你希望以何种方式被咨询。它不授予任何权限。如果仓库的 AGENTS.md 写着“部署前先询问”,那么无论你的档案怎么写,代理都会询问。
你选择谁能读到它
- 只有你:private
- 你的组织,仅通过一个会校验已认证目录中成员身份的集成:org
- 不校验:任何能打开该文件的人。在公开仓库中,就是互联网上的任何人:anyone_with_file
- 没有 visibility 字段的档案:按 org 读取
- 会扩大可读范围的更新:绝不静默进行
什么优先于你的档案
- 你仓库的规则,例如它的 AGENTS.md:优先
- 你的 harness 及其权限设置:优先
- 档案本身:只是形式
永远不会被推断的内容
- 诊断。既不需要,也不会被推断:never
- “我有 ADHD”,或者只是什么对你有帮助,写在自愿备注中:由你决定
- 根据你工作的内容存储的状态:never
个人指令和助手记忆已经支持个性化;HUMANS.md 为你选择的偏好提出一种通用格式。仅靠 schema 并不能防止提示注入。

可与你的代理配合使用
插件会在每次会话开始时加载你的文件。在尚无插件的地方,命令行会把副本写入代理已经读取的文件中。已在真实会话中从已发布的包进行测试。
| Agent | Install | Last checked |
|---|---|---|
| Claude Code Plugin,会话开始时 | claude plugin install humans-md --marketplace cmdai-hq/humans-md-plugins | 测试过:CLI 2.1.302,2026 年 10 月 17 日;桌面版和 VS Code,2026 年 10 月 16 日 |
| Codex Plugin,会话开始时,在你信任它的 hook 之后 | codex plugin marketplace add cmdai-hq/humans-md-plugins codex plugin add humans-md@humans-md | 测试过:Codex CLI 0.163.0,2026 年 10 月 17 日 |
| Cursor Plugin,每次 agent 聊天开始时 | agent plugin marketplace add https://github.com/ cmdai-hq/ humans-md-plugins # 然后,在 Cursor 聊天中:/add-plugin humans-md | 测试过:Cursor CLI 和编辑器 agent 面板,2026 年 10 月 17 日。不是 Agents Window |
| GitHub Copilot CLI Plugin,会话开始时 | copilot plugin marketplace add cmdai-hq/humans-md-plugins copilot plugin install humans-md@humans-md | 未测试:可在 Copilot CLI 1.0.98 上安装。未在会话中测试 |
| Google Antigravity Plugin,会话开始时 | agy plugin install https://github.com/ cmdai-hq/ humans-md-plugins/ tree/ main/ plugins/ antigravity | 测试过:Antigravity CLI 1.4.0,2026 年 10 月 17 日 |
| OpenCode Plugin,添加到每个会话 | opencode plugin add 'github:cmdai-hq/ humans-md-plugins#main::path:plugins/ opencode' | 测试过:OpenCode 2.0.32,2026 年 10 月 17 日 |
| Devin Plugin,每次 Devin Local 会话开始时 | devin plugins install cmdai-hq/ humans-md-plugins#plugins/ devin --local | 测试过:Devin CLI 3000.11.92,2026 年 10 月 17 日 |
| JetBrains Junie 在 ~/.junie/AGENTS.md 中放一份副本:每次修改后重新运行 | npx -y @humans-md/cli sync --to junie | 测试过:Junie CLI 26.10.12,2026 年 10 月 17 日 |
| Cline 和 Warp 在 ~/.agents/AGENTS.md 中放一份副本:每次修改后重新运行 | npx -y @humans-md/cli sync | 未测试:未测试 |
claude plugin install humans-md --marketplace cmdai-hq/humans-md-plugins
测试过:CLI 2.1.302,2026 年 10 月 17 日;桌面版和 VS Code,2026 年 10 月 16 日
codex plugin marketplace add cmdai-hq/humans-md-plugins
codex plugin add humans-md@humans-md
测试过:Codex CLI 0.163.0,2026 年 10 月 17 日
agent plugin marketplace add https://github.com/cmdai-hq/humans-md-plugins
# 然后,在 Cursor 聊天中:/add-plugin humans-md
测试过:Cursor CLI 和编辑器 agent 面板,2026 年 10 月 17 日。不是 Agents Window
copilot plugin marketplace add cmdai-hq/humans-md-plugins
copilot plugin install humans-md@humans-md
未测试:可在 Copilot CLI 1.0.98 上安装。未在会话中测试
agy plugin install https://github.com/cmdai-hq/humans-md-plugins/tree/main/plugins/antigravity
测试过:Antigravity CLI 1.4.0,2026 年 10 月 17 日
opencode plugin add 'github:cmdai-hq/humans-md-plugins#main::path:plugins/opencode'
测试过:OpenCode 2.0.32,2026 年 10 月 17 日
devin plugins install cmdai-hq/humans-md-plugins#plugins/devin --local
测试过:Devin CLI 3000.11.92,2026 年 10 月 17 日
npx -y @humans-md/cli sync --to junie
测试过:Junie CLI 26.10.12,2026 年 10 月 17 日
npx -y @humans-md/cli sync
未测试:未测试
确切版本、限制,以及如何添加你的 agent
写你自己的。
三个步骤,大约十分钟,在检查结果之前无需安装任何东西。
- 用平实的语言,在 ~/.humans/source.md 中说明你的工作方式。任何语言均可。托管编译会把这个源文件发送给 assistant 提供商。
- 让你的 agent 按照规范把它编译到 ~/.humans/HUMANS.md,或者从示例开始。在 Claude Code 中,插件的 /humans-md:compile 会完成这件事并给你预览;其他 agent 会得到同样的 compile skill。检查每个字段、任何遗漏或猜测的内容,以及谁可以读取它。然后检查该文件(Node 22.18+):npx @humans-md/cli check
npx @humans-md/cli check
- 在你的智能体中加载它。Claude Code、Codex、Cursor、Copilot CLI、Antigravity、OpenCode、Devin:安装 humans-md 插件。Junie:npx -y @humans-md/cli sync --to junie。Cline、Warp:npx -y @humans-md/cli sync。每个都会写入一份副本;每次更改后再次运行。其他客户端:添加一个运行 @humans-md/cli 的钩子。状态与限制:实现。
谁会读它