DEV Community: Corneliu Croitoru

You just write. The places find themselves.

Corneliu Croitoru — Sun, 06 Sep 2026 22:00:00 +0000

On my travel site you write a trip report the way you tell it to a friend. No field for the hotel. You publish, and a few minutes later a section appears under your story: the places you mentioned, pinned on a map, with the name a map would use.

An LLM does one part of that. Here is the whole pipeline, and where the model's job ends.

The contract: a reader, not a writer

The model gets the text of the report and a few rules. These are verbatim from the prompt:

- Only extract NAMED places: a place must have a proper name a map would show
  (e.g. "Restaurante O Tasco", "Mercado dos Lavradores"). Never extract
  descriptive references: "the old town", "restaurants near the river",
  "our hotel", "a nice restaurant", "the beach" — these are not names.
- Most short reports mention no named places — returning an empty places
  list is the correct and common answer.
- Do NOT invent places. Only extract what is explicitly mentioned.

Three things are in there on purpose.

What a name is, with counter-examples. "The old town" is not a place a map can show. Left alone, a model will happily return "Old Town", geocode it to something, and put a pin in the wrong district.

An empty answer is normal. That line took me the longest to learn. Ask a model to find places, it finds places. Most short reports name nothing. Without that sentence, the model fills the list with guesses.

Never invent. Not because the instruction is enough. It is not. Because the next step assumes the model might be wrong anyway.

The output is a small JSON contract: a name, a type (hotel, restaurant, beach, attraction, campsite, apartment), what the author did there (stayed, ate, visited), and a one-line caption taken from the text. Nothing about whether the author liked it. That question comes later, and it is asked to the author. One tap, or leave it blank.

The map's name, not the author's word

One rule looks small and does a lot:

"name": "the place's official name as it appears on a map, in its local
language (e.g. 'Mercado de Triana' even if the text says 'marché de
Triana') — never the author's translation."

People write on the site in three languages, in the language they think in. A French traveller writes "le marché de Triana". A Spanish one, "el Mercado de Triana". An English one, "Triana market". Three names, one building. If each became its own place, the map would show three pins and no reader would see that three people went there. So the model gives back the map's name. Everything else hangs on that name.

Every name has to pass a check the model cannot touch

Here is the part I trust. It is not the model.

Each name goes to OpenStreetMap, with the report's destination and country as context. The map answers with a real object, coordinates and an identity. Or it does not.

If it does not, one typo-tolerant search on the same map data gets a second look. Then the place is dropped. Not guessed. Not stored as a name without a pin. The log says "place dropped (no geocode)" and that is the end of it. A wrong pin is worse than no pin, because a reader trusts a pin.

If it does, two more gates run in plain code before anything is written:

Is it the kind of thing we pin? A closed list of map classes. A hotel, a restaurant, a beach, a viewpoint: yes. A whole region that happens to carry the same name: no. A model that returns "Madeira" for a report about Madeira did nothing wrong. The gate is what keeps it off the map.
Is it near the trip? A distance guard around the destination. A restaurant with the right name on the wrong continent fails here, silently.

Two towns with the same name is a real problem and it gets its own article: two Calhetas, 1,199 km apart, and the afternoon a verification pipeline picked the wrong one. For today, the shape is the point. The model proposes a name. The map decides. The model cannot argue.

Then the place is stored once, under its map identity. The next report that names it, in any language, lands on the same row.

It runs after publish, from a trigger, never from the request

Nothing here happens while the author waits. Publishing flips the report's status. A trigger on that change puts one job on a queue: "extract the places of report X". Not the text. Just the id.

A worker drains the queue a few jobs a minute, with retries. That pace is a choice, and what happens when a trigger fires 179 times in one afternoon is the next article in this series. The job reads the body from the stored record, by id. It never accepts text from a caller. Nothing outside the store can hand it a body to extract from. Same design as the moderation pipeline I wrote about, same reason: the model only ever sees what the author actually wrote.

The author sees a quiet note on their own report, "we're reading your story to find the places you mention". It goes away on its own when the job lands. Readers never see it. If the last retry fails, the note still resolves, to the honest state: no places yet, here is how to add one.

When it is wrong, the author wins

It is wrong sometimes. A campsite the model missed. A café pinned to the wrong town. So the author can add a place, move one, or remove one. A removed place never comes back: the removal is a mark on the row, not a delete, so a re-run of the extractor cannot undo a human decision.

That is the other half of "the model is a reader". You can correct a reader. You cannot correct a writer, you can only argue with it.

What the model is denied

Opinions. One line in the contract: sentiment "is NOT yours to classify". The model does not get to decide that the traveller recommended the hotel. The traveller answers "Would you stay here again?" themselves, with the same four answers the trip gets. No answer, no verdict, the row stays plain. Readers see the answered ones as small ink stamps next to the place. Every stamp is a person's tap. Never a model's guess.

The lesson

An extractor is a reader, not a writer. Give it a contract that says what a valid answer looks like, and says out loud that "nothing" is a valid answer. Then pass every answer through a source of truth the model cannot influence. Then let the human overrule. The model in the middle can be small, cheap and sometimes wrong. The map stays right.

The exact tuning of the gates stays behind the scenes on purpose. The shape is the part you can take.

If you built extraction on top of an LLM: which check caught the most, the one the model could not talk its way past? Surprise me.

The site is Back From My Trip: trip reports by people who were there, each ending on one question. Would I go back?

The librarian pattern: how I keep my AI coding assistant from breaking my app

Corneliu Croitoru — Wed, 26 Aug 2026 19:24:11 +0000

One index file, one doc per feature flow, and a 40-line bash hook. That's the whole system.

I build Back From My Trip — a travel site where real travellers write trip reports — almost entirely with an AI coding assistant (Claude Code). Solo project, 14 feature flows, lots of moving parts: moderation pipelines, verification with proof documents, place extraction, imports.

Every AI-assisted project I've seen hits the same two walls:

1 - The assistant changes code without knowing the rules of the feature it just touched. Tests pass. The flow is broken.
2 - You try to fix that by feeding it more context — and now every session starts by loading half the repo into the model.

The fix I use is old. Librarians solved it before computers existed.

The librarian pattern

A librarian doesn't know every book by heart. They check the catalog, and the catalog tells them the shelf. (The little drawers full of index cards, for those old enough to remember them.)

My documentation works the same way:

One file per flow. Every feature flow lives in its own markdown file: flows/moderation.md, flows/verification.md, flows/search.md... 14 files today. Each one is the authoritative end-to-end description: what triggers what, in what order, what happens on every branch.
One index. FLOWS.md lists them all with a one-line summary each.

The assistant reads the index, finds the right file, and loads only that one. Small context, right context. It never needs the whole library — it needs the shelf.

That's the library. But a library is only useful if the books are true. Here is how I keep it in sync.

Piece 1: every source file names its law

The first lines of verify-proof-document.ts, exactly as committed:

// FLOW-CRITICAL: implements flows/verification.md
// Read the doc(s) before changing behavior here. A change that alters a
// documented flow needs explicit user confirmation first, and the doc updated
// in the same commit.

It sits at the very top on purpose: the assistant reads a file from the first line, so it cannot touch the code without meeting the rule first. Same for me.

No registry, no config that maps files to docs. The mapping lives where it cannot be missed.

Piece 2: a hook that notices when the doc was forgotten

A pre-commit hook checks every staged source file: if it declares flow docs in its header and none of them are in the commit, it warns. The whole thing:

#!/bin/sh
# Flow-doc guard. Source files declare the flows they implement in a
# FLOW-CRITICAL header comment naming flows/*.md chunks. If such a file is
# committed and NONE of its named flow docs are in the same commit, warn —
# the change may have altered a documented flow without updating the doc.
# Warning only: plenty of edits (typos, styling) legitimately don't touch
# the flow, and a hard block just teaches people to bypass the hook.

staged=$(git diff --cached --name-only --diff-filter=ACMR)
warned=0

for f in $staged; do
  case "$f" in
    *.ts|*.tsx|*.sql) ;;
    *) continue ;;
  esac
  [ -f "$f" ] || continue

  docs=$(head -5 "$f" | grep -o 'flows/[a-z-]*\.md' | sort -u)
  [ -z "$docs" ] && continue

  found=0
  for doc in $docs; do
    if printf '%s\n' "$staged" | grep -qx "$doc"; then
      found=1
      break
    fi
  done

  if [ "$found" -eq 0 ]; then
    echo "flow-doc guard: $f changed, but none of its flow docs are in this commit:"
    for doc in $docs; do echo "  - $doc"; done
    warned=1
  fi
done

if [ "$warned" -eq 1 ]; then
  echo "flow-doc guard: if the flow itself didn't change, ignore this. (warning only)"
fi

exit 0

Two details I care about:

It warns, it never blocks. Plenty of edits (typos, styling) legitimately don't touch the flow. A hard block just teaches people to bypass the hook. A warning teaches the assistant — it sees the message and updates the doc in the same commit.
head -5. The declaration must be in the first five lines. If it's not at the top, it doesn't count. Placement is the contract.

Piece 3: two lines of standing instructions

In the project's instructions file (CLAUDE.md in my case — every assistant has an equivalent):

Flow docs are law — read the chunk before changing behavior.
A change that alters a documented flow requires my explicit confirmation first.

The second line matters more than it looks. The assistant can fix bugs freely, but changing documented behavior needs a human yes. The docs are not notes about the system — they are the spec the system must keep obeying.

The loop

So every change runs the same cycle:

1 - Flow docs — one file per flow, one index
2 - Read — the assistant loads only the flow concerned
3 - Change — the code, guided by the doc
4 - Update — the flow doc, in the same commit

The loop feeds itself. The doc the assistant reads next time is always true, because updating it was part of the last change. Documentation rot — the thing every team accepts as inevitable — becomes structurally impossible, not heroically avoided.

Most tooling in this space attacks the problem from the other side: detect drift, then repair it with an agent that sweeps the repo at night. I'd rather have no drift to detect.

The honest limits

The hook checks file presence, not content. A lazy one-line doc update passes. The real check is me reading the diff.
At my size, one index is enough. With more content the pattern nests: a top index pointing to chapter indexes, one file per chapter pointing to the actual docs. Real libraries do the same — the catalog says which floor, the floor says which shelf.
The assistant follows the header rule because the instructions file reinforces it. The header alone, without the standing instruction, gets ignored under pressure.

Why not a framework

Every week I see a new framework, a new magic method that promises to solve this. I run away from them — I generally like to go against the current. Markdown files, a bash hook, two rules. Everything here is readable in five minutes and will still work in ten years.

This is how I've built backfrommytrip.com from the beginning without the assistant quietly breaking one of the flows — and I use the same method at work, on a much bigger codebase.

Are you using an even simpler method to keep your assistant in line? Hard to go simpler than markdown and bash, but surprise me.