Waymarks

Our environment is full of signs. Stop signs, McDonald’s Golden Arch, Neon Billboards. Phone numbers slapped on the back of family-owned contractor trucks next to a legacy 2000-era Facebook logo. We’re constantly being prompt injected. Our attention has been under attack for a while now. And we mostly just tune these things out.

And today’s LLMs are no different. To be able to effectively wield AI today, you need to be good at writing signs and avoid writing bad signs.

Bad Sign Rising

There’s a very easy heuristic to determine a good sign from a bad sign—bad signs serve the people who created them. Good signs serve the people who read them. In short, most ads are bad signs. After all, we can’t possibly blindly follow every instruction laid in front of us. Bad signs have zero trust. They are in your face. They SHOUT IMPORTANT!!!!

Waymarks

In hiking, there’s the concept of waymarking—physical markers that help guide travelers along a path. They can be groups of stones or paint on a tree. They aren’t explicit or in your face but provide just enough information to help steer you.

Waymarks are so effective because they are inherently social. When you see a waymark, you know there’s another person that left it for you. There’s high trust because the motivation is clear. Waymarks are left behind from people who have blazed the trail before you to help you avoid some undesirable outcome they had to experience themselves. Waymarks are anti-Boomers.

All good signs follow the same pattern:

When you observe or experience an undesirable outcome, write down a way to avoid that outcome.

When too many people trip at the pool, you put up a No Running sign. This was the core idea of Geoff Huntley’s original Ralph Wiggum post. When your AI agent does something you don’t like, you stop it, put up a new Waymark, and try again. If it uses too many em dashes, you change your prompt “do a thing. Don’t use em dashes”.

A Waymark can be a skill¹, a subagent, a prompt, an MCP tool, or a Slack message. The names of these things will continue to change. The thing that matters most is the pattern. A Waymark is the act of sharing experience with the intent of improving those that come after.

We finally have a way to encode and decode information with almost zero friction. How many times is the same problem, under the same context, being solved by multiple people in your organization right now solely because neither of them knew the problem had been already solved to begin with?

Missing the Mark

It might then make sense to build a marketplace of Waymarks, but we’d only be addressing a symptom. The best Waymarks are invisible. They’re built into the environment. At worst, they’re desire paths.

Why is our environment so littered with signs? Why are our AGENTS.md files becoming essays? Because it’s a lot easier to just throw up a sign than actually change the environment.

A sign that starts with “THIS IS A PLACE FOR FUN!!!” and ends with police involvement and drug use. Reads a lot like “YOU ARE SENIOR SOFTWARE ENGINEER”. You have to wonder what the story was behind this sign. How often were people throwing stink bombs that they needed to put a waymark up about it? There’s also likely some legal requirement behind a sign like this. But that requirement doesn’t serve the user. It serves the maker of the sign. I can’t imagine the type of person who would be disrespectful at a trampoline park would abstain because they read the sign.

No, many signs exist because it’s a lot easier to try and prompt inject people than it is to change the environment. All of our cursor rules and markdown yappings work about just as well. Instead of that “No Running” sign at the pool, change the environment so it discourages running or even flat out prevents it. Engineer a solution. Why are people running? Is it because the bathroom is too far? Too many bored teenagers? Move the bathroom closer. Replace the hard concrete with that spongey stuff.

Of course these things aren’t practical in the physical world where the cost of changing the environment is enormous. But in the digital world, the cost of software is at an all time low.

You don’t blame the intern who takes down production. You blame the person who created the environment that allowed an intern to take down production. Instead of shouting at the model to stop using css selectors in e2e tests, write a hook or a lint rule to enforce it out of the loop. It costs nothing to write these things now. Maybe it doesn’t have enough prior art. Give it access to more of your internal codebases.

And unlike our physical world, if the LLM starts throwing stink bombs, just ask it why it started throwing stink bombs. Ask it how to make it not throw stink bombs next time. Hire a whole team of psychologists for the cost of $20/mo.