{"slug": "claude-md-is-not-a-prompt-file-it-is-an-operating-boundary", "title": "CLAUDE.md Is Not a Prompt File. It Is an Operating Boundary.", "summary": "A developer argues that CLAUDE.md files should be treated as operating boundaries rather than prompt files. The file should define project boundaries, destructive operations, and completion criteria to prevent AI agents from making incorrect assumptions. The developer recommends starting with small, operational instructions and keeping only three types of content: project purpose, boundaries, and done criteria.", "body_md": "I keep seeing teams treat `CLAUDE.md`\n\nas a better prompt.\n\nThey write things like:\n\nNone of that is wrong. It is just too weak to operate a real project.\n\nThe question is not whether the AI wants to write good code. The question is what \"good\" means in this repository.\n\nIn one project, the right move is a tiny patch. In another, preserving an old compatibility layer is the dangerous part. In one repo, generated files are never touched. In another, generated files must be committed because that is how deployment works.\n\nA generic prompt cannot carry that difference.\n\n`CLAUDE.md`\n\nworks best when it is not a motivational note to the model. It is an onboarding sheet for the work environment.\n\nA prompt is a request for this task.\n\nAn operating boundary is context that should shape every task before it starts.\n\nThat difference matters because most AI-assisted development failures I see are not caused by the model being evil or lazy. They happen because the model was not given the project boundary.\n\nThe Git assumptions were missing.\n\nThe target OS was not stated.\n\n\"Do the same as the existing code\" had no clear reference point.\n\nA one-line fix became a broad cleanup because nothing said where to stop.\n\nHumans often pass these boundaries by tone and memory. Before a task, someone says \"do not touch that file\" or \"this affects production, ask first.\" A human teammate slowly learns those lines.\n\nAn AI agent does not learn the room that way.\n\n`CLAUDE.md`\n\nis where you write the room down.\n\nDo not start by writing a grand engineering constitution.\n\nThe first useful `CLAUDE.md`\n\ncan be small.\n\nProject:\n\nThis repository maps note.com draft URLs to local stock articles.\n\nBoundaries:\n\nPublishing, deletion, billing, and force operations require human confirmation.\n\nBefore overwriting an untracked file, check why it exists and whether it should be tracked.\n\nDo not revert user-created changes.\n\nDone:\n\nWhen article text changes, run check and preview while keeping the draft URL stable.\n\nDo not change owner_reviewed until the user explicitly approves it.\n\nThis is not beautiful. It is useful.\n\nThe AI does not first need the deep philosophy of the project. It needs to know which lines are expensive to cross.\n\nCan it publish?\n\nCan it delete?\n\nCan it touch untracked files?\n\nWho is allowed to flip the reviewed flag?\n\nThose are not style preferences. They are accident boundaries.\n\nWhen I create a `CLAUDE.md`\n\n, I start with three buckets.\n\nWhat is this repository for?\n\nThis should be written in operational language, not branding language.\n\nBad:\n\nThis project improves productivity with AI.\n\nBetter:\n\nThis repository converts Markdown articles into note.com drafts and preserves the draft URL so the same remote draft can be updated.\n\nThe second version tells the AI what must not be broken.\n\nWhat can the AI touch without asking?\n\nWhat requires confirmation?\n\nWhat must never be done automatically?\n\nThis is where destructive operations belong:\n\n`rm -rf`\n\n`git reset --hard`\n\nBut it should also include local project boundaries:\n\nGood boundaries are boring. That is the point.\n\nWhat does \"finished\" mean here?\n\nFor a web app, it might be build, lint, and a browser screenshot.\n\nFor a note pipeline, it might be check, preview, and keeping the draft URL stable.\n\nFor an API change, it might be tests plus a contract sample.\n\nWithout this section, an AI agent tends to stop at \"the code was edited.\" In a real workflow, editing is rarely the definition of done.\n\nThe danger of `CLAUDE.md`\n\nis that it is convenient.\n\nAfter every incident, someone adds a sentence. After every useful command, someone pastes a snippet. After every successful prompt, someone stores it there \"just in case.\"\n\nEventually nobody reads it. The AI technically receives it, but the useful signal is buried under stale instructions.\n\nI try to keep only three kinds of text in the file:\n\nEverything else should fight for its place.\n\nRemove:\n\n`--help`\n\nDeleting instructions is part of maintaining them.\n\nWhen a rule fails, the usual reaction is to make it louder.\n\n\"Be careful before publishing.\"\n\n\"Really be careful before publishing.\"\n\n\"Never forget to be careful before publishing.\"\n\nThat rarely helps.\n\nA better move is to convert the sentence into a stop condition:\n\n`owner_reviewed: true`\n\n`owner_reviewed`\n\nis false, stop and print the draft URLThe more concrete the stop condition, the less you depend on the model's mood, attention, or interpretation.\n\nThis is the same reason hooks, tests, and small guard scripts work better than reminders. They interrupt the workflow at the point where the mistake would happen.\n\n`CLAUDE.md`\n\ndoes not replace physical guardrails. It should point to them and explain the intent behind them.\n\nThere is another benefit: `CLAUDE.md`\n\nforces humans to notice what they had not explained.\n\nIf you cannot write the boundary, you probably do not have one.\n\nIf every operation feels like an exception, the workflow is not ready for delegation.\n\nIf the \"done\" condition depends on one person's memory, the AI is not the only risk.\n\nWriting `CLAUDE.md`\n\nexposes these gaps early. The file becomes a small design review for your own process.\n\nThat is why I do not think of it as prompt engineering.\n\nI think of it as operational design.\n\nDo not wait until the AI has already broken something.\n\nBefore the first real task, write one page:\n\nThen run the first task and watch where the agent still guesses.\n\nIf it guesses wrong, improve the boundary.\n\nIf it stops in the right place, keep the rule.\n\nIf the same rule is now enforced by a script or hook, shorten the prose and point to the mechanism.\n\n`CLAUDE.md`\n\nis not a prompt file.\n\nIt is the first orientation document you give a non-human teammate before letting it work inside your repository.\n\nThe lesson from AI-driven development failures is not \"be afraid of AI.\"\n\nIt is that humans have been relying on unspoken boundaries for too long.\n\nWrite the boundary down, and the AI becomes less like a code generator running loose and more like a teammate working inside a room with walls.\n\nThis article was adapted from a Japanese note essay with AI assistance for the English rewrite. The operational claims and conclusions are mine.\n\nReferences:", "url": "https://wpnews.pro/news/claude-md-is-not-a-prompt-file-it-is-an-operating-boundary", "canonical_source": "https://dev.to/nomurasan/claudemd-is-not-a-prompt-file-it-is-an-operating-boundary-6gl", "published_at": "2026-07-14 08:49:38+00:00", "updated_at": "2026-07-14 09:00:21.972227+00:00", "lang": "en", "topics": ["ai-agents", "developer-tools", "ai-safety"], "entities": ["Claude"], "alternates": {"html": "https://wpnews.pro/news/claude-md-is-not-a-prompt-file-it-is-an-operating-boundary", "markdown": "https://wpnews.pro/news/claude-md-is-not-a-prompt-file-it-is-an-operating-boundary.md", "text": "https://wpnews.pro/news/claude-md-is-not-a-prompt-file-it-is-an-operating-boundary.txt", "jsonld": "https://wpnews.pro/news/claude-md-is-not-a-prompt-file-it-is-an-operating-boundary.jsonld"}}