v0.1 · for Claude Code, Codex, Cursor

`claude.html`

A short guide and drop-in starter for getting more out of coding agents. Two ideas: tell the agent what good looks like (Karpathy), and ask for HTML, not Markdown (Thariq), so you actually read the result.

You're reading this in HTML, not Markdown. That's the point. Open the source and you'll find a self-contained file: one HTML doc, inline CSS, ~30 lines of JS, no build step.

01Quick start

Three steps. Five minutes.

Step 1

Drop a ruleset at the root of your repo.

Copy the starter template below into a file called CLAUDE.md (Claude Code) or AGENTS.md (most other agents). Edit the repo-specific bits.

Step 2

Stop asking for Markdown when you want a document.

For specs, PR reviews, explainers, status reports, and editable mini-UIs, ask for an HTML artifact instead. See the prompt patterns.

Step 3

Open the artifact in a browser. Share the link.

Local: have the agent open it for you. Shareable: drop on S3 / GitHub Pages / any static host. The chance someone reads your spec goes way up.

02Why HTML beats Markdown (for documents you'll actually read)

Markdown won the early-agent era because tokens were tight and chat windows were the only renderer. Both constraints are gone.

Information density

Tables, CSS, SVG, JS, canvases, images — almost anything an agent might want to show you renders natively.

Visual clarity

You don't read 100-line Markdown files. You read 100-line HTML files with tabs, sections and diagrams.

Easy to share

One static file, one URL. No "open this in a Markdown viewer" dance.

Two-way interaction

Sliders, draggable cards, live previews — and an Export button that pastes back into the next prompt.

Full context

Your coding agent already has your filesystem, git history, and MCP tools. The HTML it produces is grounded in your repo.

It's joyful

Building things you can see and click is more fun, so you do it more, so the loop tightens.

Same information, two shapes. Right-hand side is what humans actually read.

03Use cases & prompt patterns

Verbatim starter prompts, adapted from Thariq Shihipar's examples site. Copy, adapt, paste.

1. Specs, planning & exploration

For: directional work where the answer isn't picked yet.

I'm not sure what direction to take the onboarding screen. Generate 6 distinctly different approaches — vary layout, tone, and density — and lay them out as a single HTML file in a grid so I can compare them side by side. Label each with the tradeoff it's making.

Create a thorough implementation plan in a HTML file, be sure to make some mockups, show data flow and add important code snippets I might want to review. Make it easy to read and digest.

2. Code review & understanding

For: PRs, reading unfamiliar code, explaining a change to reviewers. · live example →

Help me review this PR by creating an HTML artifact that describes it. I'm not very familiar with the streaming/backpressure logic so focus on that. Render the actual diff with inline margin annotations, color-code findings by severity and whatever else might be needed to convey the concept well.

3. Design & prototyping

For: motion, interaction, anything where prose can't capture it.

I want to prototype a new checkout button, when clicked it does a play animation and then turns purple quickly. Create a HTML file with several sliders and options for me to try different options on this animation, give me a copy button to copy the parameters that worked well.

4. Reports, research & learning

For: explainers, post-mortems, status updates, anything someone busy will read once. · live example →

I don't understand how our rate limiter actually works. Read the relevant code and produce a single HTML explainer page: a diagram of the token-bucket flow, the 3–4 key code snippets annotated, and a "gotchas" section at the bottom. Optimize it for someone reading it once.

5. Custom editing interfaces

For: things painful to express in a chat box. Always end with an Export button. · live example →

I need to reprioritize these 30 Linear tickets. Make me an HTML file with each ticket as a draggable card across Now / Next / Later / Cut columns. Pre-sort them by your best guess. Add a "copy as markdown" button that exports the final ordering with a one-line rationale per bucket.

Here's our feature flag config. Build a form-based editor for it, group flags by area, show dependencies between them, warn me if I enable a flag whose prerequisite is off. Add a "copy diff" button that gives me just the changed keys.

I'm tuning this system prompt. Make a side-by-side editor: editable prompt on the left with the variable slots highlighted, three sample inputs on the right that re-render the filled template live. Add a character/token counter and a copy button.

04Karpathy's four rules

Verbatim from Andrej Karpathy's CLAUDE.md. Tradeoff: these bias toward caution over speed. For trivial tasks, use judgement.

Rule 01

Think Before Coding

Don't assume. Don't hide confusion. Surface tradeoffs.

State your assumptions explicitly. If uncertain, ask.
If multiple interpretations exist, present them — don't pick silently.
If a simpler approach exists, say so. Push back when warranted.
If something is unclear, stop. Name what's confusing. Ask.

Rule 02

Simplicity First

Minimum code that solves the problem. Nothing speculative.

No features beyond what was asked.
No abstractions for single-use code.
No "flexibility" or "configurability" that wasn't requested.
No error handling for impossible scenarios.
If you write 200 lines and it could be 50, rewrite it.

Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.

Rule 03

Surgical Changes

Touch only what you must. Clean up only your own mess.

When editing existing code:

Don't "improve" adjacent code, comments, or formatting.
Don't refactor things that aren't broken.
Match existing style, even if you'd do it differently.
If you notice unrelated dead code, mention it — don't delete it.

When your changes create orphans:

Remove imports/variables/functions that YOUR changes made unused.
Don't remove pre-existing dead code unless asked.

The test: every changed line should trace directly to the user's request.

Rule 04

Goal-Driven Execution

Define success criteria. Loop until verified.

Transform tasks into verifiable goals:

"Add validation" → "Write tests for invalid inputs, then make them pass"
"Fix the bug" → "Write a test that reproduces it, then make it pass"
"Refactor X" → "Ensure tests pass before and after"

Strong success criteria let the agent loop independently. Weak criteria ("make it work") require constant clarification.

These guidelines are working if diffs have fewer unnecessary changes, fewer rewrites due to overcomplication, and clarifying questions come before implementation rather than after mistakes.

05Drop-in starter

Copy the block below into CLAUDE.md (Claude Code) or AGENTS.md (Codex, Cursor, most others) at the root of your repo. Edit the repo-specific section. That's it.

# CLAUDE.md / AGENTS.md

Behavioural guidelines for any AI coding agent working in this repo.
Merge with project-specific instructions as needed.

**Tradeoff:** these guidelines bias toward caution over speed. For
trivial tasks, use judgement.

---

## How to work in this repo

### 1. Think before coding
Don't assume. Don't hide confusion. Surface tradeoffs.
- State your assumptions explicitly. If uncertain, ask.
- If multiple interpretations exist, present them — don't pick silently.
- If a simpler approach exists, say so. Push back when warranted.
- If something is unclear, stop. Name what's confusing. Ask.

### 2. Simplicity first
Minimum code that solves the problem. Nothing speculative.
- No features beyond what was asked.
- No abstractions for single-use code.
- No "flexibility" or "configurability" that wasn't requested.
- No error handling for impossible scenarios.
- If you write 200 lines and it could be 50, rewrite it.

### 3. Surgical changes
Touch only what you must. Clean up only your own mess.
- Don't "improve" adjacent code, comments, or formatting.
- Don't refactor things that aren't broken.
- Match existing style, even if you'd do it differently.
- If you notice unrelated dead code, mention it — don't delete it.
- Remove imports/variables/functions that YOUR changes made unused.
- Don't remove pre-existing dead code unless asked.

The test: every changed line should trace directly to the request.

### 4. Goal-driven execution
Define success criteria. Loop until verified.
- "Add validation"  → "Write tests for invalid inputs, then make them pass"
- "Fix the bug"     → "Write a test that reproduces it, then make it pass"
- "Refactor X"      → "Ensure tests pass before and after"

Strong success criteria let you loop independently. Weak criteria
("make it work") require constant clarification.

---

## Output format

Default to **Markdown** for: READMEs, commit messages, PR descriptions,
issue bodies — anything that flows into another tool that expects Markdown.

Use a single self-contained **HTML artifact** when the deliverable is:
- a spec, plan, or option-comparison,
- a code/PR review or code explainer,
- a design or interactive prototype,
- a report, post-mortem, or explainer with diagrams,
- a throwaway editing UI for config / prompts / triage.

HTML rules:
- One file. Inline all CSS and JS. No build step. No runtime API calls.
- Use SVG for diagrams (vector means I can ask you to edit it next turn).
- If the page lets me edit something, end with an Export button that
  produces text I can paste back to you.
- For visual consistency, reference ./design-system.html (generated once
  from this codebase) when producing new HTML artifacts.

---

## Repo specifics

- Language: TypeScript, strict mode.
- No new dependencies without asking.
- Tests live next to the code they test, named `*.test.ts`.
- Run `pnpm check` before declaring done.

---

These guidelines are working if diffs have fewer unnecessary changes,
fewer rewrites due to overcomplication, and clarifying questions come
*before* implementation rather than after mistakes.

Credits: rules 1–4 are from Andrej Karpathy's CLAUDE.md. The HTML
output guidance is adapted from Thariq Shihipar's "The Unreasonable
Effectiveness of HTML." See claude.html for the full guide.

Note on filenames. Most agents read a file at the repo root by convention: Claude Code looks for CLAUDE.md, Codex/Cursor for AGENTS.md. The starter above is in Markdown because that's what those tools auto-load. To get the HTML-output behaviour the rest of this page argues for, the ruleset itself doesn't need to be HTML — it needs to tell the agent to produce HTML, which it does.

06Honest tradeoffs

From Thariq's FAQ. The HTML-first move isn't free.

Concern	Reality
Tokens	HTML uses more than Markdown. With long-context models (1M ctx Opus) it's not noticeable; the increased usefulness pays for it.
Latency	HTML can take 2–4× longer to generate than Markdown. Worth it for things you'll actually read; not for one-off chat replies.
Version control	HTML diffs are noisy and hard to review. Real downside. Keep authoritative content in code/Markdown; treat HTML artifacts as renderings, not source-of-truth.
Taste / consistency	The agent will reinvent the look every time unless you anchor it. Generate one `design-system.html` from your codebase, reference it from every prompt.
Discoverability	An HTML file in a repo isn't a great share unless hosted. GitHub Pages takes 5 minutes and is free.