The mental model

§ 01 · THE STORY

It leads with Gary

Gary is the best developer you've ever worked with. He 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.

No matter how good Gary is, eventually chaos ensues. So you don't brief Gary with everything upfront — that burns 400 of the 500 words, and it's forgotten by lunch anyway. Instead you do two things:

1. You drop breadcrumbs through the codebase, so Gary picks up the context exactly where and when he needs it.
2. You add guardrails he can bounce off when he forgets anyway.

And here is the subtle part: Gary isn't trying to be difficult. He's brilliant and forgetful, not malicious. He wants to do it right. So the guardrails don't need to be prison walls — a firm reminder that redirects him is enough. Do this, and you can be confident where Gary ends up.

Your AI coding agent is Gary.Signposts is how you work with Gary.

The story earns its place because it does three jobs in one paragraph: it explainscontext drift without jargon (Gary forgets); it explains why front-loading fails(the 400 wasted words); and it explains why the rails can be gentle (he forgets, he doesn't rebel — which is exactly why deny-with-a-written-reason works, and why a broken rule letting the edit through is philosophically consistent, not a compromise).

§ 02 · THE AXIOM

Faithful but drifting

The agent is not careless or adversarial. On a fresh context it follows instructions loyally. But as the context grows, the relative weight of any early instruction decays, and it slides back into its default habits. The problem is not disobedience — it is fading. So the fix is not louder instructions; it is instructions that arrive closer to the moment of use.

§ 03 · THE PICTURE

The flashlight

The agent doesn't see your codebase; it sees a small circle of light on a huge dark room. Everything inside the beam is real to it; everything outside is assumption. ("Flashlight" was nearly the product's name.) Two consequences follow:

1. Guidance living far away — one giant instructions file, a conventions doc — isoutside the beam almost all the time. Read once at hour zero, then it decays.
2. Whatever is in the beam has enormous influence: agents also gather context by reading — the first few lines of a script to see what it does, the neighbouring files of an area before writing there.

§ 04 · THE REMEDY

Just-in-time context

Not just-in-time instructions — just-in-time context. The agent isalready pulling context just-in-time (that's how it works); Signposts works with that grain instead of against it. The right context, at the right place, at the exact moment it's needed.

Under this term, signs and rules unify. A rule is not "enforcement" as a separate category — it is just-in-time context with a harder delivery. There are two moments of delivery, one idea:

Even a block is teaching. A rule never just says no; it hands back instructions for doing it right. In theory you could run rules alone — but that denies the agent the chance to get it right first time. Signs give the first chance; rules give the guarantee. Neither is mandatory; a rule is the rarer, special case.

§ 05 · THE COROLLARY

Tight startup context

If proximity is the principle, the front-loaded thousand-rule prompt is the anti-pattern. Session-start context should be very tight — nothing the agent doesn't need for the area it's actually in. Signposts is a system for moving guidance out of hour zero and into the moment it's needed.

§ 06 · THE NAME

Why "Signposts", not "Flashlight"

Flashlight names the limitation; Signposts names the remedy. The road metaphor carries the whole model natively: 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 — and where a sign isn't enough, there's a barrier. Co-located, just-in-time, layered soft-to-hard.

§ 07 · THE MAP

Story noun → product noun

The landing page carries the compressed version of all this; thedocs are the reference. Ready to feel it? npx signposts.