AI Coding Is Moving From Prompt Engineering to Context Engineering. intent.md Might Be More Important Than Your Next 1,000-Line Prompt
A few days ago, I thought I had finally figured out how to work properly with AI coding agents.
I had learned about CLAUDE.md.
And it felt like a superpower.
Instead of repeatedly telling Claude:
“Use this architecture.”
“Do not touch this folder.”
“Run these tests.”
“Follow this coding style.”
“Use Docker for local development.”
I could put all of that information inside one file.
Claude could read it.
The project suddenly had memory.
I thought:
This is it.
This must be how serious developers use AI coding agents.
Then I discovered something that completely changed how I think about AI-assisted development.
CLAUDE.md is only one layer.
There can also be:
intent.md
spec.md
plan.md
architecture.md
tasks.md
decisions.md
And suddenly I realized something important.
We may be moving toward a world where developers do not only write code.
We also write context for machines.
Imagine giving a very talented engineer access to your repository.
But you tell them almost nothing.
You say:
“Build the authentication system.”
That engineer now has dozens of questions.
What authentication method?
JWT?
Sessions?
OAuth?
Who are the users?
What database?
What security requirements?
What happens when the token expires?
Should refresh tokens exist?
Should there be MFA?
What should the API response look like?
An AI coding agent has exactly the same problem.
And yet this is how many of us use AI.
We give the agent one sentence.
Then we become surprised when it makes assumptions.
The agent writes technically correct code.
But it solves the wrong problem.
This is where structured context files become incredibly powerful.
Think of CLAUDE.md as the project's operating manual.
It can contain information such as:
Use Python 3.12.
Use FastAPI for APIs.
Use PostgreSQL.
Use pytest for tests.
Never modify database migrations manually.
Run tests before completing a task.
Use Docker Compose for local development.
This is extremely useful.
But notice something.
These instructions describe how the agent should behave.
They do not necessarily explain why the project exists.
That is where things become more interesting.
Imagine a project contains this:
This tiny file changes everything.
Now the AI understands the direction of the product.
If the agent needs to choose between:
A complex Kubernetes architecture
or
A simple Docker-based deployment system
the intent helps guide the decision.
Without intent, the AI might ask:
“What is technically possible?”
With intent, it can ask:
“What best matches the product we are trying to build?”
That is a huge difference.
Now imagine another file.
Now the AI does not have to invent requirements.
The requirements already exist.
This reduces one of the biggest problems with AI coding:
guessing.
A good specification turns an AI coding agent from:
“something that generates code”
into:
“something that implements decisions.”
Then you can go even further.
Now something interesting happens.
The AI no longer needs to solve the whole problem in one giant prompt.
It can work through a sequence.
This matters because large AI coding tasks often fail for the same reason large human projects fail.
Too much ambiguity.
Too many decisions.
Too much happening at once.
A plan reduces the search space.
And more like software engineering.
That was the part that surprised me.
For a long time, AI coding conversations looked like this:
Me:Build feature X.AI:Here is some code.
Then prompt engineering became popular.
People started writing longer prompts.
Then system prompts.
Then repository instructions.
But structured files like:
CLAUDE.mdintent.mdspec.mdplan.mdarchitecture.mdtasks.md
feel like the next step.
We are no longer writing one giant prompt.
We are creating a machine-readable development environment.
Here is how I now think about these files.
How should you work?
Coding rules, commands, conventions, constraints.
Why are we building this?
Business goals, user goals, philosophy, product direction.
What exactly should be built?
Requirements and expected behavior.
How will we build it?
Implementation sequence.
How is the system designed?
Services, databases, queues, APIs, boundaries.
What should be done next?
Concrete pieces of work.
Why did we choose this approach?
Important architectural decisions and trade-offs.
It opens the project.
It reads:
CLAUDE.md
Now it knows how to behave.
Then:
intent.md
Now it understands the purpose.
spec.md
Now it understands the requirements.
architecture.md
Now it understands the system.
plan.md
Now it understands the execution strategy.
At that point, the agent is no longer entering the project blind.
It has something surprisingly close to what a new engineer receives during good onboarding.
And that may be the real breakthrough.
Companies spend days onboarding engineers.
Here is the architecture.
Here are our standards.
Here is why we built the system this way.
Here is what the product is trying to achieve.
Here are the current priorities.
Here are the things you must never break.
But when we open an AI coding agent, we often give it none of that.
Then we expect senior-engineer-level decisions.
That is probably unrealistic.
Maybe the future of AI development is not about finding the perfect prompt.
Maybe it is about building the perfect context environment.
This is the part I find fascinating.
Repositories traditionally contain:
source codetestsconfigurationdocumentationCI/CDinfrastructure
Now they may increasingly contain another layer:
AI context
Files written specifically to help intelligent agents understand the project.
That means documentation is no longer only for humans.
It becomes part of the execution environment.
A missing specification might soon be almost as important as a missing configuration file.
They may be the people who are best at defining:
Because once those things are clear, AI can generate a surprising amount of the implementation.
This changes the developer’s role.
Instead of spending all day telling the computer:
how to write every line
we may spend more time telling it:
what the system should become.
project/│├── CLAUDE.md├── intent.md├── spec.md├── architecture.md├── plan.md├── tasks.md│├── src/├── tests/├── infrastructure/└── docker-compose.yml
The code is still there.
But the instructions surrounding the code become much richer.
The AI can understand the project before touching it.
Imagine multiple AI agents.
One reads the specification.
One designs the architecture.
One implements the backend.
One writes tests.
One reviews security.
One updates documentation.
All of them reading the same shared context.
At that point, these Markdown files are not just documentation anymore.
They are almost like an API between humans and AI agents.
Humans define intent.
Agents transform intent into software.
When I first learned about CLAUDE.md, I thought:
“Great. Now Claude understands my coding rules.”
After learning about intent.md, spec.md, and similar files, my thinking changed.
Now I think the bigger idea is:
AI coding agents need structured context just like human engineers need good documentation.
The better the context, the less the agent guesses.
The less it guesses, the better the implementation.
And that means the next generation of great developers may become extremely good at something we previously underestimated.
Writing clear instructions about what software should be.
Not just writing the software itself.
That is a very different skill.
And I have a feeling it is going to become one of the most important engineering skills of the AI era.
I Thought CLAUDE.md Was Enough. Then I discovered intent.md, spec.md and plan.md was originally published in Dev Genius on Medium, where people are continuing the conversation by highlighting and responding to this story.