---
title: Give agents addresses, not strings
url: https://www.grahambrooks.com/post/give-agents-addresses-not-strings/
date: 2026-11-21T09:30:00-07:00
author: Graham Brooks
description: Coding agents now keep the plan, the changelog and the spec up to date, and they edit those files by quoting text. Addressing Markdown by structure — section, row, item, link — cut reading by 88% on colab's own docs, refused every edit that would break a link, and found 11 links that were already broken.
tags:
- ai-agents
- developer-tools
- refactoring
series:
- agents-on-large-codebases
---

# Give agents addresses, not strings

*A lot of what a coding agent edits in my repositories isn't code. It's the plan: which milestones are done, what's next, what was decided and why. And the agent edits it the same way it edits code — by quoting a string and hoping it's unique.*

That's become an ordinary part of how I work. The development plan, the changelog, the `CLAUDE.md` that tells the agent how the repository works, the design notes: the agent reads them at the start of a task and updates them at the end. If a spec is going to stay true, something has to keep it true, and increasingly that something is the agent.

The trouble is that agents edit documents with tools built for text. Claude Code's `Edit` replaces an exact string in a file it has read. That works well for a line of code, which is usually unique. It works badly for documentation, which repeats itself on purpose. A status column says "Planned" on twenty rows. Every milestone section has a "Status" heading. Ticking off one roadmap item means quoting enough of the surrounding text to pick it out, which means reading the file first, which for a long plan is most of the cost.

This post is about the alternative I built into colab, a refactoring tool I've been writing about separately, and what happened when I used it to maintain colab's own documentation for a week. One person's repository, so read the numbers as one worked example. The approach doesn't depend on colab, though.

## Addresses, not quotes

The idea is the one the config backends already use for TOML and JSON, where you set a key by its path rather than finding its line. A Markdown document has structure too, and an agent can name a piece of it instead of quoting it:

| Address | Example |
|---|---|
| A section, by its heading path | `"M28 — Markdown structure > Phase 1"`, or its `#slug` |
| A table row, by its cell values | `"Changelog[Version=1.4.0]"` |
| A list item, in a section | `"Next[Faster startup]"` |
| A link, by its target | `"guide.md#install"` |
| A front matter key | `status` |

Here's a whole release's worth of documentation upkeep as one script, from colab's eval suite: add a changelog row above the previous release, tick a roadmap item, rename a section of the guide, and fix every link to its old anchor.

```
refactor "release docs" {
    match markdown::row "Changelog[Version=1.4.0] < [Version=1.3.0]" in "CHANGELOG.md" { insert "Date=2026-11-14
Summary=Faster startup" }
    match markdown::item "Next[Faster startup]" in "docs/roadmap.md" { replace "Faster startup (done)" }
    match markdown::section "Install" in "docs/guide.md" { replace "Installation" }
    match markdown::link "guide.md#install" { replace "guide.md#installation" }
    match markdown::link "#install" in "docs/guide.md" { replace "#installation" }
}
```

Nothing in that script is quoted from the files except the names a reader would use anyway: a version number, an item's text, a heading. The row is placed by its neighbour (`< [Version=1.3.0]`), not by line number. And the rules behave the way you'd want a tool that edits unattended to behave. An ambiguous or missing address is an error that lists the candidates, never a guess. Text the script doesn't touch is never reflowed. Running the script twice changes nothing the second time.

colab's eval suite prices that task at 2 calls and 1,654 bytes against 11 calls and 4,096 bytes for `Read` + `Edit`: 60% fewer. The `Read` + `Edit` side there is a model of the cheapest hand route, priced from the finished diff, not a recorded session, so take it as the shape of the difference rather than its exact size.

## Most of the saving is in reading

An agent reads documentation far more often than it writes it, and that's where structure paid off first. Instead of reading a 159-line plan whole, the agent can ask for its outline:

```
$ colab outline docs/development-plan.md
docs/development-plan.md (159 lines)
    1-159   # Colab Development Plan                                     4 tables, 6 lists
    6-20      ## Vision                                                  1 list
   22-29      ## Where things stand (2026-11-14)
   31-43      ## Order of work                                           1 table
   45-70      ## Stable gate before M20                                  1 table, 1 list
   63-70        ### Status (2026-11-14)                                  1 table
   72-92      ## Planned milestones                                      2 lists
   74-84        ### M20 — Agent install & guardrails                     1 list
   86-92        ### Decisions waiting (from M29)                         1 list
   94-112     ## Follow-ups from shipped milestones                      1 table
  114-121     ## Unscheduled                                             1 list
  123-143     ## Non-goals (for now)                                     1 list
  145-159     ## Risks and how we manage them                            1 table
```

Then it reads only the sections it needs. The first time I did this for real, four `outline` and `section` calls cost 12.7 KB, against 104 KB to read the four files whole. Both sides of that are measured, since reading a file whole costs exactly its size: 88% less.

The outline is also more correct than the shortcut agents reach for. A `grep '^#'` outline counts a `# comment` inside a shell code block as a heading, and in colab's own `docs/cli.md` one did. Parsing the document doesn't make that mistake.

## Links are the invariant

The failure I most wanted to prevent in agent-maintained docs is the quiet one: a heading renamed in one file, and three other files still linking to the old anchor. Nothing fails, the docs just rot. So every colab run checks the Markdown links it would break and refuses to write if there are any. Renaming a heading lists every file that links to it, and a link rule in the same script clears them.

The first time I ran that check on its own over colab's docs, it found 11 links that were already broken — anchors such as `cli.md#explain` that had never matched a heading. Fixing them took nine link rules.

The better story is the time it stopped me. Moving a finished milestone out of the plan into the completed-milestones file is a chore the agent does every few days, so colab has a command for it:

```sh
colab mv-section docs/development-plan.md "M29 — Follow-up sweep" \
  --to docs/completed-milestones.md --under "Follow-up sweep (M29)"
```

Its first run refused, with exit code 11. The section being moved linked to `#follow-ups-from-shipped-milestones`, a section that stayed behind in the plan, so the move would have broken its own link. The fix went into `mv-section` itself: it now rewrites the moved section's links, so an anchor left behind gains the path back to the source file and a relative path is recomputed from its new home. Then the move ran clean. By hand, or by an agent quoting strings, that link would simply have broken.

## Code in the docs is code

Documentation that shows an API goes stale the moment the API changes. With `in fences`, a code rule also runs inside the matching code blocks in Markdown files, with its edits mapped back to the right lines. An API migration then updates the README's examples in the same run as the code, and `colab find` lists the examples alongside the call sites. Dogfooding it on colab's own docs brought the fenced API in `docs/architecture.md` back in line with the code it described, which it had quietly drifted from.

## Writing saved less, and why

Writing is where the numbers were least flattering, so it's worth being specific. All of these compare the bytes colab actually used in my sessions, failed attempts included, with the modelled cheapest `Read` + `Edit` route to the same diff.

The first round of doc updates saved only 12%. Replacing a section's body re-sends the whole section, which for a small change is more than quoting a line. Once table rows and list items could be edited on their own, the next round saved 52%. Half of that round's bytes went on failed attempts, every one of them a quoting mistake in the rule language: a quoted `"#anchor"` inside a raw string closed it early, and the error said only "invalid token". Without those it would have saved 77%. After the error message started saying where the string had closed and how to avoid it, the next round — 27 rules over three files — saved 66% with no failed attempts.

So the honest summary is that structured writing beats quoting by a margin that depends on how fine-grained the address is. Sections are too coarse for small edits. Rows and items are about right.

## What it doesn't do

Plain paragraphs aren't addressable. A lead paragraph, a sentence in `CLAUDE.md`, the grammar in an unlabelled code block: text that isn't a section, row, item or link was still edited by hand, and a paragraph module is an open item. New list items are written on one line however long they are, while my docs wrap at about 72 columns.

And a structural tool can still fail silently, which is worth saying because silence is exactly what it was meant to fix. Twice, a rule reported that it matched nothing when the row or item was plainly there. Once a code span in the file hid the word colab was using to skip files quickly. Once the item was in a section's fourth list, and an item address reads the first unless told otherwise. Both are fixed, and the second now says `address it as S@N[…]`. But the lesson I'd generalise is that a miss has to say where else it looked, or an agent will report success.

## The document is a data structure

None of this needs colab specifically. If agents are going to keep specs and plans true, the tools they use should treat a document the way we already treat config: addressed by structure, edited idempotently, and checked for broken references before anything is written. An address is cheaper than a quote to read, harder to get subtly wrong, and something a tool can check.

The figures here come from colab's [dogfood log](https://github.com/grahambrooks/colab/blob/main/docs/dogfood-log.md) and its eval suite, both in the repository with their method. The broader case for giving agents tools whose cost is per change rather than per site is in [Edits an agent shouldn't make one at a time](https://www.grahambrooks.com/post/edits-an-agent-should-not-make-one-at-a-time/).
