I Thought CLAUDE.md Was Enough. Then I discovered intent.md, spec.md and plan.md

A developer argues that AI coding agents require structured context files beyond CLAUDE.md, such as intent.md, spec.md, and plan.md, to reduce assumptions and align code with product goals. The article suggests that as AI coding evolves, developers will increasingly write context for machines, not just code.

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: IntentWe are building a simple deployment platform for small development teams.The goal is to allow a developer to connect a Git repository and deploy an application without manually managing servers.The product should feel simpler than Kubernetes.Users should not need infrastructure knowledge. 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. Authentication SpecificationUsers must be able to:- register with email and password- verify their email- log in- request password reset- refresh access tokensAccess tokens expire after 15 minutes.Refresh tokens expire after 30 days.Passwords must be hashed using Argon2.The API must return JSON responses. 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. Implementation Plan1. Create user database model2. Add password hashing3. Add registration endpoint4. Add login endpoint5. Add JWT generation6. Add refresh token support7. Add password reset8. Add tests9. Update API documentation 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 https://blog.devgenius.io/i-thought-claude-md-was-enough-then-i-discovered-intent-md-spec-md-and-plan-md-a9e94252dc7c was originally published in Dev Genius https://blog.devgenius.io on Medium, where people are continuing the conversation by highlighting and responding to this story.