Drop-in instructions that make coding agents (Claude Code, Codex, Cursor and others) give answers that are fast to understand and to check.
More and more of our time goes into understanding what models produce, not producing it. This repo turns that idea into one instruction file. The idea comes from a post by Andrej Karpathy (2 Oct 2026). In short, the post suggests that you ask models for:
- Simplified Technical English (ASD-STE100, the controlled language of aerospace maintenance manuals), or a relaxed version of it;
- diagrams instead of text;
- HTML pages, interactive when that helps;
- explainer videos, made on demand.
It also says that code is now abundant, so a large throwaway tool is often worth building only to understand something. This summary is a paraphrase; read the post itself.
This repo is an independent project. It is not affiliated with or endorsed by the author of the post.
| Agent | What to do |
|---|---|
| Claude Code | Copy AGENTS.md into your project root. If the project has no CLAUDE.md, copy CLAUDE.md too: it holds only @AGENTS.md, which imports the file. If the project has a CLAUDE.md, add the line @AGENTS.md to it. For all your projects, put the file somewhere and add @<path>/AGENTS.md to ~/.claude/CLAUDE.md. |
Codex CLI, Cursor, and other agents that read AGENTS.md |
Copy AGENTS.md into your project root. If you have one already, add this file as a new section. |
| Any chat model | Paste the text of AGENTS.md into the system prompt or custom instructions. |
Your own instructions and the project's instructions win over this file. It says so itself.
AGENTS.md tells the agent to:
- give the answer in a fixed order: a warning if there is a risk, the answer, a table or a diagram if one helps, the details, and at most one offer;
- write short, active sentences with one instruction each;
- draw diagrams in ASCII by default, because terminals do not render Mermaid;
- offer an HTML page, an explainer video or a throwaway tool only when it helps, and make the files only after the user agrees, outside the project.
A trigger table decides the format. For example: 2 or more options compared on 2 or more attributes → a table; 3 or more parts that interact → a diagram; a long answer → an offer of an HTML page. A simple question gets plain text.
evals/ asks each prompt with and without AGENTS.md, and scores the answers
with text heuristics. It runs with the Codex CLI login you already have, or with an API
key. It has a tuning set and a held-out set; judge the file on the held-out set.
See evals/README.md.
Held-out results with Codex, 27 answers per condition (details and limits):
| baseline | with AGENTS.md | |
|---|---|---|
| Expected table/diagram present | 6/12 | 12/12 |
| Expected offer present | 0/12 | 10/12 |
| Offers the prompt does not call for | 0 | 0 |
| Control prompts kept plain | 6/6 | 6/6 |
| Diagrams drawn as Mermaid (terminal) | 2/4 | 0/20 |
| Mean words per sentence | 12.6 | 10.6 |
| Passive verbs per 10 sentences | 1.3 | 0.2 |
These numbers measure whether answers follow the rules, not how fast people understand them. The HTML-page offer for a long guide is the weak point: it was missing in 2 of 3 answers.
All four examples explain the same thing, git rebase main, so you can compare the formats.
| File | Format |
|---|---|
examples/1-ste-rewrite.md |
A typical answer, then the same answer in relaxed STE |
examples/2-diagram.md |
An ASCII diagram, and Mermaid for files that GitHub renders |
examples/3-explainer.html |
A step-through page: one file, no dependencies, works offline |
examples/4-video-script.md |
A video script scene by scene, with an ffmpeg outline |
To try the HTML example, download it and open it in a browser.
- The writing rules are a relaxed subset of ASD-STE100. The file adds two rules that are stricter than STE (active voice everywhere, no progressive tenses), and it does not use the STE dictionary of approved words. Read the official specification from ASD if you need full compliance.
- The video section works with any text-to-speech API, or with a free local model.