How to tell an AI exactly what to change in your HTML

An AI assistant will happily edit your HTML. Whether it edits the part you meant depends almost entirely on how you identified the target, and describing it from memory is the step where most of these requests quietly go wrong.

Three ways an edit request fails

The target is ambiguous. "Make the card heading smaller" on a page with nine cards. The assistant picks one. It may not be yours, and if it edits a shared CSS rule it changes all nine.

The location moves. "Change line 214." The first edit shifts every line after it, so the second instruction in your list now points somewhere else. Line numbers are only valid against the file as it was when you read it.

Where and what get confused. "This heading should be smaller" names an element, but the change belongs in a CSS rule, not in the element's markup. An assistant that takes the instruction literally adds an inline style and leaves the stylesheet contradicting it.

What a precise instruction contains

Four things, and the first is the one people leave out.

• An anchor that is unique in the file. A verbatim excerpt of your source that occurs exactly once, so the assistant can find it with a plain search instead of interpreting a description.
• The kind of change. Edit, delete, add, or a question. Deleting an element means opening tag through closing tag, which is worth stating rather than assuming.
• The change itself, in plain words. "Cut this to one line." "This should read 32,248."
• A note that the anchor marks where, not what. Otherwise a styling request gets applied to the markup rather than the rule that governs it.

What that looks like in practice

This is the shape FixMyHtml exports after you click an element and write a note. Every item carries its own anchor, so nothing depends on line numbers surviving the previous edit.

Apply the changes below to `report.html`.

Source fingerprint: `a3f91c2e` · 1 edit(s), 0 question(s), 0 global note(s).

## How to read this
- Each item's code block is a **verbatim excerpt from the source file**,
  used as a location anchor. It is unique in the file, so locate it with
  Grep or Read before editing.
- The anchor marks *where*, not *what to change*. The change is defined
  by the item's `Instruction` line. A styling request, for example, means
  editing the CSS rule in <style> — not the element markup.

## Edits — document order, 1 total

### FMH-1 · [EDIT] report.html:118 · Q3 revenue by region
selector: `section.kpi > div.card:nth-of-type(2) > h3`
```html
<h3 class="card-title">Q3 revenue by region</h3>
```

Instruction: this figure is stale, it should be 32,248

The assistant greps for the excerpt, gets one hit, and edits there. The line number is present for you to read, not for the assistant to rely on.

Writing the instruction itself

For an insertion, say where relative to the anchor: before it, as its last child, or after it. An assistant that is not told will pick, and picking is the failure you are trying to avoid.

Questions are not edits

Some notes are not changes. "Where did this number come from?" is a question, and an assistant handed a list of edits will try to edit something in response to it. Keep them in a separate section that says plainly not to touch the file, and answer in the reply instead.

Common questions

Does this work with Claude Code, Cursor and ChatGPT?

The output is plain text with markdown structure, so anything that reads a prompt can use it. Agents with file access, such as Claude Code and Cursor, benefit most because they can grep the anchor and edit in place.

Why not just paste the whole file?

You can, for a small document. It gets expensive quickly, it puts the contents somewhere you may not want them, and it does not solve the ambiguity problem: the assistant still has to work out which of the nine cards you meant.

What if the file changed since I made the notes?

Anchors are matched by content rather than position, so most notes survive an edit round. Any that cannot be placed are listed separately rather than attached to whatever is nearest.