Skip to content

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

3 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

understandable-output

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:

  1. Simplified Technical English (ASD-STE100, the controlled language of aerospace maintenance manuals), or a relaxed version of it;
  2. diagrams instead of text;
  3. HTML pages, interactive when that helps;
  4. 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.

Use it

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.

What it changes

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.

Measure it

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.

Examples

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.

Notes

  • 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.

License

MIT

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages