Gary is the best developer you've ever worked with. Knows every API by heart, writes beautiful code, never sleeps. There's just one thing: Gary only remembers the last 500 things you tell him.
Brief him with everything upfront and you've burned 400 of those — forgotten by lunch anyway. No matter how brilliant Gary is, eventually: chaos.
Your AI coding agent is Gary.
Signposts is how you work with Gary.
You don't memorise every road in the country before you set off. The signage is on the road, at the junction, where the decision happens.
Signposts does the same for Gary: the right context, at the right place, at the exact moment it's needed. Two moments matter:
Agents read an area before they write to it. The moment Gary reads a matching file, the sign for that area drops into his context — "mind the shape here" — and is re-delivered as his memory fades. It steers; it never blocks.
Gives him the chance to get it right first time.
Gary isn't being difficult — he just forgets. So the rail doesn't need to be a prison wall: it blocks the bad write before it lands and hands back a written reason. Gary reads it, course-corrects, carries on.
Catches him when he forgets anyway.
FOR EXAMPLE
A real session: Gary goes to hand-edit a generated file, a rule blocks the write before it hits the disk, and he reads the reason and fixes the real source instead.
● Edit(src/db/schema.generated.ts) ✗ blocked — no-edit-generated "Generated — change the source, then regenerate."● Understood — editing the source instead.● Edit(src/db/schema.prisma) ✓● Bash(npx prisma generate) ✓ — the bad write never landed.
Every guardrail is a plain entry in one committed signposts.yaml in your repo. No service, no server — it travels with the code, and applies to anyone (and any agent) who clones it.
rules: local: - id: no-edit-generated use: core/protected-path deny: ["**/*.generated.ts"] message: "Generated — change the source, then regenerate."
THE LOOP
Signposts isn't a fixed ruleset you install once. You set it up once, then it grows: develop and reflect on repeat, every session — and share what works when you want to.
npx signposts lays down a known-good setup in any repo.It scaffolds a known-good setup — with a cheeky demo rule, so you see a block (and a self-correct) on day one. From there, grow your own rails as you work, and cherry-pick from any repo you trust.