# CLAUDE.md Is Not a Prompt File. It Is an Operating Boundary. > Source: > Published: 2026-07-14 08:49:38+00:00 I keep seeing teams treat `CLAUDE.md` as a better prompt. They write things like: None of that is wrong. It is just too weak to operate a real project. The question is not whether the AI wants to write good code. The question is what "good" means in this repository. In 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. A generic prompt cannot carry that difference. `CLAUDE.md` works best when it is not a motivational note to the model. It is an onboarding sheet for the work environment. A prompt is a request for this task. An operating boundary is context that should shape every task before it starts. That 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. The Git assumptions were missing. The target OS was not stated. "Do the same as the existing code" had no clear reference point. A one-line fix became a broad cleanup because nothing said where to stop. Humans 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. An AI agent does not learn the room that way. `CLAUDE.md` is where you write the room down. Do not start by writing a grand engineering constitution. The first useful `CLAUDE.md` can be small. Project: This repository maps note.com draft URLs to local stock articles. Boundaries: Publishing, deletion, billing, and force operations require human confirmation. Before overwriting an untracked file, check why it exists and whether it should be tracked. Do not revert user-created changes. Done: When article text changes, run check and preview while keeping the draft URL stable. Do not change owner_reviewed until the user explicitly approves it. This is not beautiful. It is useful. The AI does not first need the deep philosophy of the project. It needs to know which lines are expensive to cross. Can it publish? Can it delete? Can it touch untracked files? Who is allowed to flip the reviewed flag? Those are not style preferences. They are accident boundaries. When I create a `CLAUDE.md` , I start with three buckets. What is this repository for? This should be written in operational language, not branding language. Bad: This project improves productivity with AI. Better: This repository converts Markdown articles into note.com drafts and preserves the draft URL so the same remote draft can be updated. The second version tells the AI what must not be broken. What can the AI touch without asking? What requires confirmation? What must never be done automatically? This is where destructive operations belong: `rm -rf` `git reset --hard` But it should also include local project boundaries: Good boundaries are boring. That is the point. What does "finished" mean here? For a web app, it might be build, lint, and a browser screenshot. For a note pipeline, it might be check, preview, and keeping the draft URL stable. For an API change, it might be tests plus a contract sample. Without this section, an AI agent tends to stop at "the code was edited." In a real workflow, editing is rarely the definition of done. The danger of `CLAUDE.md` is that it is convenient. After 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." Eventually nobody reads it. The AI technically receives it, but the useful signal is buried under stale instructions. I try to keep only three kinds of text in the file: Everything else should fight for its place. Remove: `--help` Deleting instructions is part of maintaining them. When a rule fails, the usual reaction is to make it louder. "Be careful before publishing." "Really be careful before publishing." "Never forget to be careful before publishing." That rarely helps. A better move is to convert the sentence into a stop condition: `owner_reviewed: true` `owner_reviewed` is false, stop and print the draft URLThe more concrete the stop condition, the less you depend on the model's mood, attention, or interpretation. This 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. `CLAUDE.md` does not replace physical guardrails. It should point to them and explain the intent behind them. There is another benefit: `CLAUDE.md` forces humans to notice what they had not explained. If you cannot write the boundary, you probably do not have one. If every operation feels like an exception, the workflow is not ready for delegation. If the "done" condition depends on one person's memory, the AI is not the only risk. Writing `CLAUDE.md` exposes these gaps early. The file becomes a small design review for your own process. That is why I do not think of it as prompt engineering. I think of it as operational design. Do not wait until the AI has already broken something. Before the first real task, write one page: Then run the first task and watch where the agent still guesses. If it guesses wrong, improve the boundary. If it stops in the right place, keep the rule. If the same rule is now enforced by a script or hook, shorten the prose and point to the mechanism. `CLAUDE.md` is not a prompt file. It is the first orientation document you give a non-human teammate before letting it work inside your repository. The lesson from AI-driven development failures is not "be afraid of AI." It is that humans have been relying on unspoken boundaries for too long. Write 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. This article was adapted from a Japanese note essay with AI assistance for the English rewrite. The operational claims and conclusions are mine. References: