{"slug": "i-thought-claude-md-was-enough-then-i-discovered-intent-md-spec-md-and-plan-md", "title": "I Thought CLAUDE.md Was Enough. Then I discovered intent.md, spec.md and plan.md", "summary": "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.", "body_md": "AI Coding Is Moving From Prompt Engineering to Context Engineering. intent.md Might Be More Important Than Your Next 1,000-Line Prompt\n\nA few days ago, I thought I had finally figured out how to work properly with AI coding agents.\n\nI had learned about CLAUDE.md.\n\nAnd it felt like a superpower.\n\nInstead of repeatedly telling Claude:\n\n“Use this architecture.”\n\n“Do not touch this folder.”\n\n“Run these tests.”\n\n“Follow this coding style.”\n\n“Use Docker for local development.”\n\nI could put all of that information inside one file.\n\nClaude could read it.\n\nThe project suddenly had memory.\n\nI thought:\n\n**This is it.**\n\nThis must be how serious developers use AI coding agents.\n\nThen I discovered something that completely changed how I think about AI-assisted development.\n\nCLAUDE.md is only one layer.\n\nThere can also be:\n\nintent.md\n\nspec.md\n\nplan.md\n\narchitecture.md\n\ntasks.md\n\ndecisions.md\n\nAnd suddenly I realized something important.\n\nWe may be moving toward a world where developers do not only write code.\n\nWe also write **context for machines**.\n\nImagine giving a very talented engineer access to your repository.\n\nBut you tell them almost nothing.\n\nYou say:\n\n*“Build the authentication system.”*\n\nThat engineer now has dozens of questions.\n\nWhat authentication method?\n\nJWT?\n\nSessions?\n\nOAuth?\n\nWho are the users?\n\nWhat database?\n\nWhat security requirements?\n\nWhat happens when the token expires?\n\nShould refresh tokens exist?\n\nShould there be MFA?\n\nWhat should the API response look like?\n\nAn AI coding agent has exactly the same problem.\n\nAnd yet this is how many of us use AI.\n\nWe give the agent one sentence.\n\nThen we become surprised when it makes assumptions.\n\nThe agent writes technically correct code.\n\nBut it solves the wrong problem.\n\nThis is where structured context files become incredibly powerful.\n\nThink of CLAUDE.md as the project's operating manual.\n\nIt can contain information such as:\n\n```\nUse Python 3.12.\nUse FastAPI for APIs.\nUse PostgreSQL.\nUse pytest for tests.\nNever modify database migrations manually.\nRun tests before completing a task.\nUse Docker Compose for local development.\n```\n\nThis is extremely useful.\n\nBut notice something.\n\nThese instructions describe **how the agent should behave**.\n\nThey do not necessarily explain **why the project exists**.\n\nThat is where things become more interesting.\n\nImagine a project contains this:\n\n```\n# 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.\n```\n\nThis tiny file changes everything.\n\nNow the AI understands the direction of the product.\n\nIf the agent needs to choose between:\n\nA complex Kubernetes architecture\n\nor\n\nA simple Docker-based deployment system\n\nthe intent helps guide the decision.\n\nWithout intent, the AI might ask:\n\n“What is technically possible?”\n\nWith intent, it can ask:\n\n“What best matches the product we are trying to build?”\n\nThat is a huge difference.\n\nNow imagine another file.\n\n```\n# 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.\n```\n\nNow the AI does not have to invent requirements.\n\nThe requirements already exist.\n\nThis reduces one of the biggest problems with AI coding:\n\n**guessing.**\n\nA good specification turns an AI coding agent from:\n\n“something that generates code”\n\ninto:\n\n“something that implements decisions.”\n\nThen you can go even further.\n\n```\n# 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\n```\n\nNow something interesting happens.\n\nThe AI no longer needs to solve the whole problem in one giant prompt.\n\nIt can work through a sequence.\n\nThis matters because large AI coding tasks often fail for the same reason large human projects fail.\n\nToo much ambiguity.\n\nToo many decisions.\n\nToo much happening at once.\n\nA plan reduces the search space.\n\nAnd more like software engineering.\n\nThat was the part that surprised me.\n\nFor a long time, AI coding conversations looked like this:\n\n```\nMe:Build feature X.AI:Here is some code.\n```\n\nThen prompt engineering became popular.\n\nPeople started writing longer prompts.\n\nThen system prompts.\n\nThen repository instructions.\n\nBut structured files like:\n\n```\nCLAUDE.mdintent.mdspec.mdplan.mdarchitecture.mdtasks.md\n```\n\nfeel like the next step.\n\nWe are no longer writing one giant prompt.\n\nWe are creating a **machine-readable development environment**.\n\nHere is how I now think about these files.\n\n**How should you work?**\n\nCoding rules, commands, conventions, constraints.\n\n**Why are we building this?**\n\nBusiness goals, user goals, philosophy, product direction.\n\n**What exactly should be built?**\n\nRequirements and expected behavior.\n\n**How will we build it?**\n\nImplementation sequence.\n\n**How is the system designed?**\n\nServices, databases, queues, APIs, boundaries.\n\n**What should be done next?**\n\nConcrete pieces of work.\n\n**Why did we choose this approach?**\n\nImportant architectural decisions and trade-offs.\n\nIt opens the project.\n\nIt reads:\n\n```\nCLAUDE.md\n```\n\nNow it knows how to behave.\n\nThen:\n\n```\nintent.md\n```\n\nNow it understands the purpose.\n\n```\nspec.md\n```\n\nNow it understands the requirements.\n\n```\narchitecture.md\n```\n\nNow it understands the system.\n\n```\nplan.md\n```\n\nNow it understands the execution strategy.\n\nAt that point, the agent is no longer entering the project blind.\n\nIt has something surprisingly close to what a new engineer receives during good onboarding.\n\nAnd that may be the real breakthrough.\n\nCompanies spend days onboarding engineers.\n\nHere is the architecture.\n\nHere are our standards.\n\nHere is why we built the system this way.\n\nHere is what the product is trying to achieve.\n\nHere are the current priorities.\n\nHere are the things you must never break.\n\nBut when we open an AI coding agent, we often give it none of that.\n\nThen we expect senior-engineer-level decisions.\n\nThat is probably unrealistic.\n\nMaybe the future of AI development is not about finding the perfect prompt.\n\nMaybe it is about building the perfect **context environment**.\n\nThis is the part I find fascinating.\n\nRepositories traditionally contain:\n\n```\nsource codetestsconfigurationdocumentationCI/CDinfrastructure\n```\n\nNow they may increasingly contain another layer:\n\n```\nAI context\n```\n\nFiles written specifically to help intelligent agents understand the project.\n\nThat means documentation is no longer only for humans.\n\nIt becomes part of the execution environment.\n\nA missing specification might soon be almost as important as a missing configuration file.\n\nThey may be the people who are best at defining:\n\nBecause once those things are clear, AI can generate a surprising amount of the implementation.\n\nThis changes the developer’s role.\n\nInstead of spending all day telling the computer:\n\n**how to write every line**\n\nwe may spend more time telling it:\n\n**what the system should become.**\n\n```\nproject/│├── CLAUDE.md├── intent.md├── spec.md├── architecture.md├── plan.md├── tasks.md│├── src/├── tests/├── infrastructure/└── docker-compose.yml\n```\n\nThe code is still there.\n\nBut the instructions surrounding the code become much richer.\n\nThe AI can understand the project before touching it.\n\nImagine multiple AI agents.\n\nOne reads the specification.\n\nOne designs the architecture.\n\nOne implements the backend.\n\nOne writes tests.\n\nOne reviews security.\n\nOne updates documentation.\n\nAll of them reading the same shared context.\n\nAt that point, these Markdown files are not just documentation anymore.\n\nThey are almost like an **API between humans and AI agents**.\n\nHumans define intent.\n\nAgents transform intent into software.\n\nWhen I first learned about CLAUDE.md, I thought:\n\n*“Great. Now Claude understands my coding rules.”*\n\nAfter learning about intent.md, spec.md, and similar files, my thinking changed.\n\nNow I think the bigger idea is:\n\n***AI coding agents need structured context just like human engineers need good documentation.***\n\nThe better the context, the less the agent guesses.\n\nThe less it guesses, the better the implementation.\n\nAnd that means the next generation of great developers may become extremely good at something we previously underestimated.\n\n**Writing clear instructions about what software should be.**\n\nNot just writing the software itself.\n\nThat is a very different skill.\n\nAnd I have a feeling it is going to become one of the most important engineering skills of the AI era.\n\n[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.", "url": "https://wpnews.pro/news/i-thought-claude-md-was-enough-then-i-discovered-intent-md-spec-md-and-plan-md", "canonical_source": "https://blog.devgenius.io/i-thought-claude-md-was-enough-then-i-discovered-intent-md-spec-md-and-plan-md-a9e94252dc7c?source=rss----4e2c1156667e---4", "published_at": "2026-09-08 12:51:52+00:00", "updated_at": "2026-09-08 13:29:41.257767+00:00", "lang": "en", "topics": ["ai-tools", "developer-tools", "artificial-intelligence"], "entities": ["Claude"], "alternates": {"html": "https://wpnews.pro/news/i-thought-claude-md-was-enough-then-i-discovered-intent-md-spec-md-and-plan-md", "markdown": "https://wpnews.pro/news/i-thought-claude-md-was-enough-then-i-discovered-intent-md-spec-md-and-plan-md.md", "text": "https://wpnews.pro/news/i-thought-claude-md-was-enough-then-i-discovered-intent-md-spec-md-and-plan-md.txt", "jsonld": "https://wpnews.pro/news/i-thought-claude-md-was-enough-then-i-discovered-intent-md-spec-md-and-plan-md.jsonld"}}