The Prompt Files I Keep in Every WordPress Repo

Most project instruction files fail for the same reason. They are too long to be read.

A CLAUDE.md file, a cursor rules file, a project instructions block. The name keeps changing but the job does not. It tells an assistant how this particular repo works before it touches a single line of code.

The instinct is to write everything down. Architecture, history, philosophy, every convention the team ever argued about. That produces a file nobody reads and a model that follows about half of it.

In every WordPress plugin repo I work in, the file is short. Usually under fifty lines. That is a deliberate choice. Instructions are supposed to reduce friction, not add a layer of ceremony to every task.

Why the file has to be short

The file is not documentation. It is context that gets re-read on every single task.

That changes what belongs in it. Documentation can be long because you read it once, deliberately, at the moment you need it. Project instructions compete for attention with the actual code, the actual task, and everything else already in the window.

A long file dilutes itself. When forty rules carry equal weight, none of them do.

So I use one filter: if the code already says it, do not repeat it.

An assistant can see that the admin is built in React. It can read the directory names. What it cannot see is which of those directories is generated, which prefix is reserved, and what has to happen before a release goes out.

Those are the things worth writing down.

The three things worth writing down

Across the WordPress plugin repos I maintain, the same three categories earn their place every time.

• Coding standards. Not a full style guide. Only the two or three rules an assistant will otherwise get wrong: the function prefix, the text domain, the escaping and sanitizing expectations, and the lint command to run before committing.
• Plugin structure. Which directory holds what, and more importantly which directories are generated. A build output folder that gets hand-edited is one of the most expensive mistakes to unwind.
• Release rules. A WordPress plugin carries its version number in more than one place. Writing down where those live and what a release commit must include prevents a broken deploy far more reliably than remembering does.

Everything else I have tried to include was either obvious from the code or quietly ignored in practice.

A template you can copy

Here is the skeleton I start from in a new plugin repo. It is generic on purpose. Swap the prefix, the text domain, and the directory names for your own.

# Project instructions

## Stack
- WordPress plugin. PHP 7.4 minimum. Assets are built with npm.
- Admin UI is React. Public-facing markup is PHP templates.

## Coding standards
- Follow WordPress Coding Standards. Run `composer lint` before committing.
- Prefix every global function, class, and option with `myplugin_`.
- Sanitize on input, escape on output. Never trust request data.
- Text domain is `my-plugin`. Every user-facing string is translatable.

## Structure
- `includes/` core classes, one class per file
- `admin/` admin screens and settings
- `assets/src/` source JS and CSS. Never edit `assets/dist/` by hand
- `templates/` markup a theme is allowed to override

## Release rules
- The version appears in the plugin header, the `VERSION` constant, and
  `readme.txt`. Bump all three together.
- Every release adds a `readme.txt` entry under `== Changelog ==`.
- Release branches are `release-<version>`, cut from `main`.
- Built assets are committed only in a release commit.

## Do not
- Do not add a dependency without asking.
- Do not change database schema without a migration and a version guard.
- Do not commit directly to `main`.

That is around thirty lines. It fits on one screen, which is the real test. If I have to scroll to read my own instructions file, it has stopped being instructions and started being documentation.

What I leave out on purpose

The tempting additions are the ones that feel most useful and turn out not to be:

• architecture overviews that git history already tells better
• API documentation that lives in the code
• explanations of what WordPress hooks are
• rules the team does not actually follow
• anything that changes more often than the file gets updated

That last one matters most. A stale rule is worse than no rule, because it gets followed.

Aspirational rules are the other trap. If a codebase has three hundred unprefixed functions, writing “always prefix functions” creates a mismatch between the instructions and everything the model can see. I would rather write the honest version. New code is prefixed, old code is not, and nothing gets renamed without asking.

When a rule belongs somewhere else

Not everything I want an assistant to know belongs in the instructions file. Two things pull rules out of it.

The first is a repeatable procedure. When a task has real steps in a real order, prose stops working. Preparing a release is the clearest example. Cut the branch, merge the feature work, bump three version strings, write the changelog entry, run the build, open the pull request. That is a skill file, not a paragraph. It loads only when the task comes up, which keeps it out of the way the rest of the time.

The second is anything the tool can enforce instead of read. Permissions, hooks, environment variables. Writing “do not run destructive database commands” in an instructions file is a request. Putting it in a settings file is a rule. Only one of those survives a bad day.

So the split I use is simple. CLAUDE.md holds what is always true, skills hold procedures with steps, and settings hold whatever should not depend on cooperation.

It is the same instinct behind small automation wins. Each file stays small, stays boring, and does one job.

Final thoughts

The best version of this file is one I barely notice.

It does not explain the project. It does not teach WordPress. It removes the handful of mistakes that would otherwise show up in every session, and then it gets out of the way.

If you are writing one for the first time, start smaller than feels right. Ten lines that are all true beats a hundred that are mostly aspirational. Add a rule the next time an assistant gets something wrong, and only then.

The file earns its length one mistake at a time.