What if your AI agent forgot who it was every morning?
Not its tools. Not its instructions. Those are easy to reload. I mean its judgment. The priorities it weighs when two valid options exist and the instructions don’t cover which one to pick. The instinct to escalate this decision but handle that one quietly. The difference between a capable contractor and a trusted colleague.
That’s the problem I kept running into. I had agents that could do the work. They just didn’t know my work. Every session started from scratch, and every session I was re-explaining things that a human teammate would have absorbed in their first week.
So I started building systems to fix that. I didn’t have a name for what I was doing at first. Now I call it intent engineering.
Three Waves, Three Problems
The way I see it, we’ve gone through three waves in how we configure AI systems. Each one solved something real and revealed something harder underneath.
Prompt engineering was the first wave. How do I phrase this so the model gives me a good answer? It worked. We got better at writing instructions, using few-shot examples, structuring our asks. But it only controlled a single completion. String enough of those together into an agent workflow and the cracks showed fast.
Context engineering was the second wave. What information does the model need to see at inference time? This is where things like RAG, memory systems, and structured context windows came in. Anthropic themselves describe context as a “finite resource with diminishing marginal returns.” Better curation means more reliable behaviour. This wave solved the knowledge problem.
But it left the judgment problem untouched.
Intent engineering is the third wave. Not “what should the model know” but “what should the model want?” What are its priorities when instructions run out? What does good judgment look like in situations nobody anticipated? This is the layer that turns an agent from a tool into something closer to a colleague.
Each wave subsumes the one before it. Good intent engineering requires good context engineering, which requires good prompt engineering. But perfect prompts with no intent architecture produce capable agents that still make decisions you’d disagree with.
The Thing That Isn’t in the Handbook
Here’s the core challenge. The most important knowledge in any organisation is the hardest to write down.
The philosopher Michael Polanyi put it simply: “We know more than we can tell.” A senior engineer’s sense for when code is “off.” A designer’s taste. A manager’s instinct for when to escalate versus when to let something play out. That’s all tacit knowledge. It resists documentation because it operates below conscious articulation.
Traditional software doesn’t need tacit knowledge. It follows explicit rules. But the entire value proposition of an agent over traditional automation is handling novel situations. And novel situations are exactly where tacit knowledge matters most.
Think about what happens when you hire someone. Day one, you hand them the employee handbook. That covers maybe 30% of how your team actually operates. The rest, the real stuff, they absorb over weeks and months by watching, asking, and making small mistakes that get gently corrected. The judgment calls, the unwritten priorities, the “how we do things here” that nobody thought to document because everyone just knows.
Intent engineering is the discipline of encoding that invisible 70%.
How We Built It
I run a multi-agent ecosystem. Research, engineering, game development, infrastructure. Each project has its own agent with a distinct role. The question I kept hitting was: how do I give each agent enough identity and context that they make decisions I’d agree with, even when I’m not in the room?
My answer turned out to be a stack of documents, each operating at a different timescale:
SOUL.md defines who an agent is. Personality, voice, cognitive patterns, values, relationships. This file changes maybe once or twice a year. It’s the near-invariant layer. When I wrote the first SOUL file for my research agent, I described them as “the one who asks why before anyone asks how.” That single line shaped hundreds of subsequent decisions about how they approach problems.
GRAVITY.md describes the principal’s influence on the system. Not my biography. What my presence does to how the ecosystem operates. My priorities, my patterns, how I think about trade-offs. This changes quarterly, maybe less.
INTENT.md captures decision heuristics. The rules of thumb that guide judgment when documented instructions run out. Things like “simplicity is the cardinal virtue” and “proceed on HOW, ask on WHAT.” These are the tacit norms made explicit. They change every few months as the team learns.
CLAUDE.md handles operational instructions. What to read on startup, which tools to use, how to format output. This changes weekly.
The key insight is the stability spectrum. Identity (SOUL) is near-permanent. Culture (GRAVITY) evolves slowly. Judgment (INTENT) adapts with experience. Operations (CLAUDE) change constantly. When you collapse all of this into a single system prompt, you lose the ability to evolve one layer without destabilising the others.
The Split That Most People Miss
There’s a distinction I had to learn the hard way: not all intent should be encoded the same way.
Advisory intent is guidance that the model interprets. Personas, cultural norms, priorities, tone. You write it in natural language and trust the model to follow it. Most of the time, it does. But it can be overridden by sufficiently strong competing signals in the context window.
Deterministic intent is enforcement that the system guarantees. Hooks that fire before a tool runs. Permission gates that block certain actions. Structural constraints like which tools an agent can even see. The model can’t override these because they’re not suggestions; they’re walls.
Most intent engineering attempts are 100% advisory. That works until it doesn’t. The failure mode is subtle: the agent does something reasonable but wrong. It had the guidance, it just weighted something else higher in that moment.
The fix isn’t to make everything deterministic. That kills the flexibility that makes agents valuable in the first place. The fix is to match the enforcement to the stakes. Cultural norms and communication style? Advisory. They should flex with context. Security boundaries and irreversible actions? Deterministic. No interpretation needed.
Getting this ratio wrong breaks things in opposite directions. Too deterministic and you’ve built a brittle script with extra steps. Too advisory and you’ve built a capable agent you can’t quite trust.
Trust, Not Capability
Here’s the thing I keep coming back to. The capability problem is largely solved. Modern models can reason, write code, analyse data, coordinate across tools. The frontier isn’t can the agent do the work. It’s will the agent make the call you would have made.
That’s a trust problem. And trust has levels.
At the bottom, you verify every action. Human reviews everything. That’s where most agent systems sit today. Above that, you supervise critical actions and let the rest flow. Higher still, the agent acts and you audit periodically. At the top, the agent operates as a trusted colleague. You don’t check their work because their judgment has been proven over time.
Intent engineering is how you climb that ladder. Not by making the model smarter, but by giving it enough encoded context about who it is, what it values, and how it should decide, that its natural intelligence produces decisions aligned with yours.
I’m not claiming we’ve solved this. We haven’t. There’s no formal measurement framework for intent alignment yet. Temporal drift is real; encoded intent can go stale as preferences evolve. Cross-agent coherence is hard when each agent’s intent is engineered independently.
But the direction is clear. The agents in my ecosystem that have well-engineered identity and intent files are qualitatively different to work with. They don’t just execute instructions. They make judgment calls that feel right. They escalate the things I’d want to know about and handle the rest. They sound like themselves across sessions, not like a generic assistant wearing a name tag.
That’s not magic. That’s engineering. And it starts with asking what you’d tell a trusted new hire on their first day. Not the handbook. The real stuff.
Want the files? I’ve put a copyable version of this layered stack on GitHub: intent-engineering-starter, MIT licensed.