Tim Conrad
← Thoughts

A humans.md for working with models

My repositories tell the agent how to work with me. Nothing tells me how to work with the agent. A first version of that file, and what I found when I looked for one.

Tim Conrad · Language models · Habits · Coding agents

Status
Draft
Started
Last revised

The missing file

Every repository of mine has a CLAUDE.md. It tells the agent how to build the project, what to leave alone and how I want my commits. When the agent gets something wrong, I add a line.

There is no such file for me. When a new model comes out, I switch, try a few tasks and go by feel. Sometimes I start a task without any CLAUDE.md, to see whether the new model does better without my old rules. Mostly I just notice things.

That is a strange split. The model gets a written manual and a changelog. The person who drives it gets a hunch. This thought is about the other file: a humans.md, with rules for me, written down and changed when the model changes.

The name is taken

I was not the first to think of it. I found three projects that use the name, and they mean three different things.

Files called humans.md, by who reads them and what they are about Horizontal axis: the agent reads it, or I read it. Vertical axis: how I work, or how the agent treats me. attogram/agents HUMANS.md, September 2025, is read by humans and is about how they work. thellmwhisperer/human.md, February 2026, is read by the agent and sets hours and breaks. cmdai-hq/HUMANS.md, October 2026, is read by the agent and says how to talk to me. The file in this thought sits next to attogram's and adds a log per model. the agent reads it I read it about how I work about how the agent treats me attogram/agents Sep 2025 · for humans this file + a log per model cmdai-hq/HUMANS.md Oct 2026 · how to reach me thellmwhisperer/human.md Feb 2026 · hours and breaks Files called humans.md, by who reads them and what they are about agent reads it I read it about how I work about how it treats me attogramSep 2025 this file+ log per model cmdai-hqOct 2026 thellmwhispererFeb 2026

Tap a point to read about that file.

  • attogram/agents, HUMANS.md: the oldest one I can date, first added on 5 September 2025. It sits next to AGENTS.md and is for humans to read: treat agents as junior developers, give clear instructions, review their pull requests. It has one guide per agent, for Jules, Claude and Claude Code [1].
  • thellmwhisperer/human.md, February 2026: a file the agent reads. It holds your working hours, breaks and the longest session you allow, and a hook makes the agent tell you when to stop [2].
  • cmdai-hq/HUMANS.md, October 2026: a profile in your home folder that tells your agents, and your colleagues' agents, how to write to you, when to ask you and when to interrupt you. "AGENTS.md is for your codebase. HUMANS.md is for you." [3]
  • This file: like attogram's, it is for me to read. What I could not find anywhere is the log: one entry for each new model, because the models change.
Fig. 1 · Three files with one name. Their places on the map are my reading of each project.

So "humans.md" is not my term, and it is not a standard either. Two of the three are files for the agent, about how it should treat me. Mine is the other way round: a file for me, about how I should work with it.

Models change under me

The vendors already write a kind of humans.md for every model. They call it a prompting guide, and the useful part is the section on what changed. Anthropic's guide puts the differences between models first [4]. Three of its examples:

  • Newer models listen more closely to the instructions. Capitals like "CRITICAL: You MUST", which once helped a model use a tool at all, now make it use the tool too often. The guide says to soften them.
  • Claude Opus 5 checks its own work. Old instructions to verify every step make it check again and again. The guide says to remove them.
  • Newer models take the words literally. "Can you suggest some changes?" can get suggestions and no changes.

Other vendors say the same. OpenAI's guide for GPT-5.5 says to treat it as a new model family and to start from a fresh baseline, instead of carrying over every instruction from older prompts [5]. Google recommends that Gemini 3 keep its default temperature of 1.0, although tuning the temperature was normal with older models [6].

The same instruction, read by a newer model Three instructions written for older models. CRITICAL: You MUST use the search tool: I meant that it searches when it helps; a newer model searches far too often. After each step, verify your work twice: I meant one more check; a newer model that checks its own work checks again and again. Can you suggest some changes: I meant that it changes the code; a literal model lists ideas and changes nothing. Written for an older model What I meant What a newer model does CRITICAL: You MUST use the search tool when it helps. searches when it helps searches far too often how often it searches After each step, verify your work twice. checks once more checks again and again how often it checks Can you suggest some changes? changes the code lists ideas, changes nothing how much it changes The same instruction, read by a newer model Written for an older model CRITICAL: You MUST use the search tool when it helps. searches when it helps searches far too often how often it searches After each step, verify your work twice. checks once more checks again and again how often it checks Can you suggest some changes? changes the code lists ideas, changes nothing how much it changes
Fig. 2 · Switch between what I meant and what a newer model does with the same words. The examples are from Anthropic's guide [4], shortened. The bars show the direction, not a measurement.

A habit that helped with the last model can hurt with this one. And my trick of starting without a CLAUDE.md turns out to be the fresh baseline that OpenAI recommends. I just did it without knowing why.

Feel is a bad meter

That I go by feel worries me because of one study. In early 2025 METR gave 16 experienced open-source developers real tasks in their own projects, some with AI tools and some without [7].

Felt and measured speed in METR's 2025 study Before the tasks the developers expected to be 24 percent faster with AI. Afterwards they believed they had been 20 percent faster. Measured, they took 19 percent longer. Expected, before 24% faster Believed, after 20% faster Measured 19% slower ← slower faster → Felt and measured speed in METR's 2025 study: expected 24 percent faster, believed 20 percent faster, measured 19 percent slower Expected, before 24% faster Believed, after 20% faster Measured 19% slower ← slower faster →
Fig. 3 · METR, early 2025: what 16 developers expected, what they believed afterwards, and what was measured [7].

They expected to be 24% faster. Measured, they took 19% longer. Afterwards they still believed they had been 20% faster.

The number itself has aged. METR now marks the 2025 post as out of date. Its update from February 2026 says developers are likely faster than in early 2025, but calls its own data very weak evidence: many developers no longer wanted to work without AI for the test, and the timing breaks down when one person runs several agents at once [8]. Other studies found gains: 21% faster in a randomised trial at Google, with a wide margin of error [15], and 26% more completed tasks in three field experiments with code completion [16].

What stays is the gap between felt and measured. In November 2026 METR put the speed-up of work at Anthropic at about 2x on well-specified tasks, and treated the staff's own estimate of about 12x as very loose evidence [14]. People misjudge their own time in general: they plan too optimistically, and looking at how long past tasks took is what corrects it [19].

Measure without extra work

I will not log my tasks by hand. I know myself. So the numbers have to come from what is already recorded.

Claude Code keeps a transcript of every session on my machine. Besides the conversation, it records the model of each answer, the time of each step, the tokens and their price, and the lines changed [18]. Git adds the other half: Claude's commits carry the model's name in a trailer, and a revert or a fix two days later says something about the code that came before it.

Two records that already exist, and four questions they answer The session transcripts hold the model, time, tokens, cost, lines changed and corrections. Git holds the model trailer, reverts and fixes. The transcripts answer: am I faster, is the result good, how fast does the budget go, what keeps failing. Git also answers whether the result is good. Session transcripts model, time, tokens, cost, lines, corrections Git history model trailer, reverts, fixes two days later Am I faster? Is the result good? How fast does the budget go? What keeps failing? Two records that already exist, session transcripts and git history, and four questions they answer Transcripts time, tokens, cost Git history reverts, fixes Am I faster? Is the result good? How fast does the budget go? What keeps failing?

Tap a question to see what answers it.

  • Am I faster? Active time per session and per month, and the lines changed, for each model. Activity, not value.
  • Is the result good? Reverts, and fix commits on code that another commit changed two days before, counted against the model that wrote that code. Plus how often I had to correct the model in the session.
  • How fast does the budget go? Tokens and their price per month and model, and the price per active hour. On a subscription nothing is billed per token, but the number shows how fast the limits go.
  • What keeps failing? Corrections per ten prompts, interrupts, denied tools and tool errors, and a list of the sessions that went worst. Each of those gets one line on what went wrong: an unclear task, a missing or ignored rule, or a mistake of the model.
Fig. 7 · What is already recorded, and what it can answer.

The last question matters most to me. The sessions where I corrected the model most often are a small, personal eval set. After a month they say more about a model than my impression of it, and after a model switch they show whether my instructions still work.

I wrote this down as a skill for my agent, with a script that reads the transcripts and git and prints a report per month and model. The numbers are signs of activity and friction, not of value, and METR treats counts like these as an upper bound for the real gain [17]. They are good for one thing: comparing my own months and models with each other. One catch: Claude Code deletes transcripts after 30 days unless I raise that limit [18].

Agree first, then build

The best habit I picked up this year comes from Matt Pocock's skills for coding agents [9]. Before any code, /grill-me makes the model ask me questions, round after round, until every branch of the plan is decided. Then a spec, then tickets, then the build test first, then a review. A small change skips the spec and the tickets.

Matt Pocock's flow from idea to merged change Five steps: grill (/grill-me), spec (/to-spec), tickets (/to-tickets), build (/tdd) and review (/code-review). A bigger change goes through all five. A small change goes from grill straight to build. Grill Spec Tickets Build Review /grill-me /to-spec /to-tickets /tdd /code-review a bigger change: all five steps a small change: from the questions straight to the build Matt Pocock's flow: grill, spec, tickets, build, review. A small change goes from grill straight to build. Grill Spec Tickets Build Review /grill-me /to-spec /to-tickets /tdd /code-review

Switch between a bigger and a small change, or tap a step.

  • Grill: the model interviews me until the plan has no open branch. The variant grill-with-docs also writes the terms we settle into a glossary and the hard-to-reverse decisions into ADRs.
  • Spec: the agreed plan, written down.
  • Tickets: the spec, cut into pieces that can be built one at a time.
  • Build: test first, one ticket at a time.
  • Review: a code review closes each change.
Fig. 4 · The main flow of Matt Pocock's skills [9]. The README says they work with any model.

What I like about it: it turns the instructions around. I do not tell the model what to do in one long prompt. The model checks whether I know what I want. That works on the one part of the session that I control, and it works with every model.

Stay able to do it

The second rule that holds for every model is about me, not the model. In a study by Anthropic, 52 developers, most of them junior, learned a new Python library [10]. The group with an AI assistant scored 50% on a quiz afterwards, the group that wrote the code by hand 67%. The AI group was not significantly faster.

How people used the AI mattered more than whether they used it:

Quiz scores by how people used the AI Asked to understand: generated code and then asked why, 86 percent, 2 people; asked for code with an explanation, 68 percent, 3 people; asked only about concepts, 65 percent, 7 people. Handed it over: handed over all the code, 39 percent, 4 people; slid into full reliance, 35 percent, 4 people; let the AI debug, 24 percent, 4 people. For comparison: the hand-coding group scored 67 percent, the whole AI group 50 percent. by hand: 67% all with AI: 50% Asked to understand generated, then asked why (2) 86% asked for code + explanation (3) 68% asked only about concepts (7) 65% Handed it over handed over all the code (4) 39% slid into full reliance (4) 35% let the AI debug (4) 24% Quiz scores by how people used the AI by hand: 67% all with AI: 50% Asked to understand generated, then asked why (2) 86% asked for code + explanation (3) 68% asked only about concepts (7) 65% Handed it over handed over all the code (4) 39% slid into full reliance (4) 35% let the AI debug (4) 24%
Fig. 5 · Quiz scores by pattern of use, number of people in brackets [10]. The groups are tiny, and the authors say this shows no cause.

Those who asked why scored like the hand coders. Those who handed the work over scored below 40%. The groups have two to seven people each, so this is a hint, not a result. It matches a survey of 319 knowledge workers by Microsoft Research and Carnegie Mellon: the more people trusted the AI, the less critical thinking they reported, and the more they trusted themselves, the more [11]. Their work moved from doing the task to overseeing it.

The authors warn that a skill used only in the rare hard case decays. That is an old finding. In 1983 Lisanne Bainbridge called it one of the ironies of automation: the machine takes the routine work, and the human keeps the hard cases without the practice they need [12]. Simkute and others found the same ironies in generative AI [13].

So: when something breaks, I look first myself, or I ask for the explanation along with the fix. And I keep some small work without a model.

When a new model ships

Put together, the file has two parts. One part holds for every model. The other is a loop that I run each time a model comes out.

The loop for a new model A circle of six steps: new model, read the card, fresh baseline, prune, work, write it down, then back to the next new model. In the middle: HUMANS.md, one entry per model. HUMANS.md one entry per model New model Read the card Fresh baseline Prune Work Write it down The loop for a new model: new model, read the card, fresh baseline, prune, work, write it down HUMANS.md one entry per model New model Read the card Fresh baseline Prune Work Write it down

Tap a step.

  • New model: a release, or a new default in the tool I use.
  • Read the card: the model card and the vendor's prompting guide. I look for what the model does more, what it does less, and what the guide says to remove.
  • Fresh baseline: one real task without my CLAUDE.md files, to see what the model does on its own.
  • Prune: remove what it no longer needs: capitals, old workarounds, extra checks.
  • Work: with the rules that hold for every model: agree first, read what I merge, ask why.
  • Write it down: one line in the log of HUMANS.md, and two weeks later a second look: was it right?
Fig. 6 · The loop. The log keeps what I noticed, so the next model does not start from a hunch again.

Reviewing my CLAUDE.md

One open question of the first version was whether a skill could read a new model card and propose the changes to my CLAUDE.md files. I built one. It reads my session transcripts to see which models I actually use, reads the current prompting guides for those models, runs a fresh research round on the last three months, checks every instruction file of a project, and proposes changes with a reason for each. It changes nothing without my OK.

I ran it on this site. The research found one consistent message, all of it from Anthropic's own docs and none of it measured: keep the always-loaded file under about 200 lines, leave out what the agent can read from the repository, drop capitals and "IMPORTANT", turn rules that must always hold into hooks or checks, and put the check command first [20][21]. Claude Code even has a built-in audit for instructions written for older models [21].

Length of this site's CLAUDE.md 76 lines before the review, 61 after the first review, 33 after the changes from the research. Before 76 lines After the review 61 lines After the research 33 lines Length of this site's CLAUDE.md: 76 lines before, 61 after the review, 33 after the research Before 76 lines After the review 61 lines After the research 33 lines
Fig. 8 · The always-loaded instructions of this site, before and after the review. The rest did not disappear: it moved into skills, a hook, a check script and rules that load only when they apply.

What changed: the workflow for my review notes moved into a skill, with a hook that counts the open notes when a session starts. A script now checks the page rules in CI, where four sentences in four files used to ask for them. The rules for new pages load only when the agent works on a page. The file layout went, because the agent reads the repository anyway. And the file now starts with how to check the work.

Whether the agent works better with it, I do not know yet. That is what the monthly report is for, and the "two weeks later" column of the log.

Some trends I wanted to check found no evidence either way in the last three months: formal verification such as TLA+ as the agent's check, dropping hand-written tests, and deleting code comments so they cannot mislead the model. They stay on my list as open questions.

The file, version 0

This is the first version. It is short on purpose: a rule I do not follow is worse than no rule.

HUMANS.md
# HUMANS.md How I work with language models. The agent has its CLAUDE.md. This file is for me. Version 0.2, 10 Nov 2026. The thinking behind it: https://t7d.dev/thoughts/humans-md/ ## With every model 1. Agree first. For anything bigger than a small fix, let the model ask me questions until the plan is clear. Keep the words we agreed on.2. Say what I want done. "Change it", not "can you suggest". Give the reason for a rule instead of capital letters.3. Give context as to a new colleague: the goal, the limits, where to look.4. Read what I merge. Tests show that it works. Reading shows that I understand it.5. When something breaks, look first myself, or ask for the explanation with the fix.6. Do some small work without a model, regularly, so I can still do it.7. Measure instead of feel, without extra work: once a month and after each model switch, read the report from the session transcripts and git. Look at the sessions that went worst. ## When a new model ships 1. Read the model card and the vendor's prompting guide. Look for what the model does more, what it does less, and what to remove.2. Do one real task without my CLAUDE.md files. Compare.3. Remove what the new model no longer needs: capitals, old workarounds, extra checks.   Let a review skill and `/doctor prompt-audit` in Claude Code find these, then decide myself.4. Write one entry in the log.5. Two weeks later, read the entry again. Was it right? ## Log | Date | Model | What the guide says changed | What I change | Two weeks later || --- | --- | --- | --- | --- || 10 Nov 2026 | Claude Opus 5.5 | Newer Claude models follow instructions literally, check their own work, and react strongly to words like CRITICAL | To try: remove capitals and "verify each step" lines from my CLAUDE.md files | || 10 Nov 2026 | Claude Opus 5.5, Fable 5.2 | Claude Code docs: CLAUDE.md under 200 lines, no file layout, no emphasis, hooks for hard rules, the check command first | t7d.dev CLAUDE.md from 76 to 33 lines: notes into a skill and a hook, a page check in CI, page rules on demand | |
Download HUMANS.md

Open questions

  • Should the agent read part of it too? "Ask me questions before a big change" could live in CLAUDE.md as well.
  • Which of the numbers in the monthly report really track what I care about? I will know after a few months of it.
  • Models now come out every few months. Is one log entry per model too much, or too little?
  • Do formal checks, fewer tests or fewer comments help an agent? I found no evidence yet.

Starting points

  • My own question: if the agent gets a CLAUDE.md, what would the human's file say?
  • Matt Pocock's skills, above all /grill-me [9].

Sources

  1. attogram: agents, HUMANS.md, first added 5 Sep 2025.
  2. The LLM Whisperer: human.md, Feb 2026.
  3. cmdai: HUMANS.md, Oct 2026.
  4. Anthropic: Prompting best practices, read Nov 2026.
  5. OpenAI: GPT-5.5 prompting guide, Apr 2026.
  6. Google: Gemini 3 developer guide.
  7. METR: Measuring the impact of early-2025 AI on experienced open-source developer productivity, Jul 2025.
  8. METR: We are changing our developer productivity experiment design, Feb 2026.
  9. Matt Pocock: skills.
  10. Shen and Tamkin, Anthropic: arXiv 2601.20245, Jan 2026, and Anthropic's summary of the study.
  11. Hao-Ping Lee and others: The impact of generative AI on critical thinking, CHI 2025.
  12. Lisanne Bainbridge: Ironies of automation, Automatica, 1983.
  13. Auste Simkute and others: Ironies of generative AI, 2024.
  14. METR: Anthropic AI R&D acceleration assessment, Nov 2026.
  15. Elise Paradis and others, Google: How much does AI impact development speed? An enterprise-based randomized controlled trial, ICSE 2025.
  16. Kevin Zheyuan Cui and others: The effects of generative AI on high-skilled work: evidence from three field experiments with software developers, Management Science.
  17. METR: Exploratory transcript analysis for estimating time savings from coding agents, Feb 2026.
  18. Claude Code docs: costs and usage, the .claude directory, monitoring, read Nov 2026.
  19. Claude Code docs: best practices, read Nov 2026.
  20. Claude Code docs: memory and CLAUDE.md, read Nov 2026.
  21. Roger Buehler, Dale Griffin, Michael Ross: Exploring the "planning fallacy", Journal of Personality and Social Psychology 67, 1994.

The METR pages [8], [14] and [17], and the studies [15] and [16], I could read only through summaries, not the full text. The numbers are as those summaries give them.

Revisions

  • Added "Reviewing my CLAUDE.md": what a review of this site's instructions against current guidance found and changed. The file got a step for that and a new log entry.
  • Measurement: METR's 2025 numbers are out of date; added later studies, the gap between felt and measured, and a section on measuring from what Claude Code and git already record. Rule 7 of the file changed to match.
  • First version.

Feedback

Not shared yet. When I post about it, what people answer goes here, with what it changed.