DEV Community

Sho Naka
Sho Naka

Posted on

CLAUDE.md Is Not a Prompt File. It Is an Operating Boundary.

#ai #claude #contextengineering #devops

I keep seeing teams treat CLAUDE.md as a better prompt.

They write things like:

  • think carefully
  • make small changes
  • write readable code
  • value tests

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 asks. An operating boundary constrains.

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.

The first version can be ten lines.

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.

Three sections are usually enough.

When I create a CLAUDE.md, I start with three buckets.

1. Project

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.

2. Boundaries

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
  • force push
  • publishing
  • billing
  • production deploys
  • external account changes

But it should also include local project boundaries:

  • generated files are read-only
  • migrations need a matching rollback
  • user edits must not be reverted
  • screenshots are evidence, not source of truth
  • credentials are never requested in chat

Good boundaries are boring. That is the point.

3. Done

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.

Do not turn CLAUDE.md into a junk drawer.

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:

  1. rules that break something if violated
  2. decisions that come up again and again
  3. project-specific words the AI would otherwise guess from names

Everything else should fight for its place.

Remove:

  • generic engineering virtues
  • commands already explained by --help
  • one-off prompts
  • old workaround notes after the tool has been fixed
  • rules nobody follows

Deleting instructions is part of maintaining them.

If the AI ignores the rule, rewrite the stop condition.

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:

  • before publishing, check owner_reviewed: true
  • if owner_reviewed is false, stop and print the draft URL
  • if a browser review timestamp is missing, open the draft first
  • if the user did not explicitly approve, do not flip the flag

The 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.

The file is not for the AI only.

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.

Start before the first task.

Do not wait until the AI has already broken something.

Before the first real task, write one page:

  • what this project exists to do
  • what the AI must not touch
  • which operations require a human
  • what checks define done
  • what local terms mean

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:

Top comments (0)