Newshot

Humans.md:告诉你的 AI 智能体如何与你协作

Translation(model translation, not the source's own text)

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 说只在被阻塞时才打断你。其他一切等到任务结束。

SettingValueMeaning
interrupting.interrupt_forblocking_only仅当工作无法继续时才打断
deciding.batch_questionsend_of_task非阻塞问题集中在最后提出
deciding.reversibledecide_and_report可逆的选择直接做出,之后汇报
deciding.question_styleyes_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 文件(是空的),所以这来自你环境上下文中的配置数据:

SettingValue
interrupting.interrupt_forblocking_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 交换机的接线员,排成长长一排坐在插孔墙式的交换机前,手工插接线路。
1912 年巴黎 Gutenberg 交换机的接线员,排成长长一排坐在插孔墙式的交换机前,手工插接线路。

每一通电话都要经过接线员。由她决定哪通电话能接通,以及何时接通。

那是 1912 年巴黎的 Gutenberg 交换机。你的 agent 也只拨一个台:你的。HUMANS.md 告诉它们哪些来电可以现在响,哪些要等到任务结束。

1913 年的一台法国电话交换机:一排排编号插孔、通话计时器,以及两根横跨面板的插接线。
1913 年的一台法国电话交换机:一排排编号插孔、通话计时器,以及两根横跨面板的插接线。

一个文件。每个会话。一个人。

  • 十个会话,只有一个你两款工具,十个会话同时运行。它们发来的内容一半需要你,一个决定或一次检查;另一半是不需要你处理的报告。两者都以同样的方式到来,就在你工作正中间。到了晚上: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 身份提供者阻塞。

文件结果
已迁移38212 个测试通过
阻塞3staging 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 并不能防止提示注入。

1945 年,波茨坦胜利交换台,戴着耳机的陆军电话接线员,每个人都用手工转接电话。
1945 年,波茨坦胜利交换台,戴着耳机的陆军电话接线员,每个人都用手工转接电话。

可与你的代理配合使用

插件会在每次会话开始时加载你的文件。在尚无插件的地方,命令行会把副本写入代理已经读取的文件中。已在真实会话中从已发布的包进行测试。

AgentInstallLast 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 的钩子。状态与限制:实现。

谁会读它

The translation is machine-generated and individual terms may be off. Nothing is rewritten or cut; the original is authoritative.

Published by HN AI
This site only summarises and aggregates; copyright stays with the original author. Headlines and summaries follow the source — where they differ, the original wins.
Read the original ↗