The Repo Is the Prompt: rules that earn their place

Once checks are in place, the next thing that limits an agent is not capability, it is that it starts every session knowing nothing about your project except what it can read. Some of what it needs is not readable. The build script that works, the directory that is generated, the fact that the config file lies.

There are three places to put that knowledge, they cost different amounts, and picking wrong is the usual reason a rule you wrote down gets ignored anyway.

CLAUDE.md is expensive, so make every line fight for its place

A CLAUDE.md in the repo root is read at the start of every session. That makes it the right place for rules with no exceptions and the wrong place for everything else, because you pay for all of it on every turn, including the turns where none of it applies.

The test for a line is simple and most files fail it: would the agent get this wrong without being told? A list of your dependencies fails, because it can read package.json. A description of your folder structure fails, because it can look. What passes is the surprising part.

## Build and deploy
- The app lives in `.app/`; the repo root is the served docroot.
- `npm run build` writes `.app/dist/`. It does NOT publish.
- `node .app/deploy.js` mirrors `dist/` into the docroot. That is the deploy.
- `api/*.php` is not part of the build. Editing it is live immediately.

## Traps
- Do not run `prettier --write`. The config exists but the repo was never
  formatted with it, so it rewrites every file it touches.
- `#about` must not get `overflow-hidden`; it breaks the sticky photo card.

Every line there is something that has actually gone wrong. That is what a good file looks like: not documentation, a list of scars. It is also short, which is the other half of the job, because a long file gets skimmed by humans and diluted by everything around it.

Memory is for what the repository cannot say

Some things are true, load bearing, and unwritable in a repo file. Why the ugly implementation was the right call. That the staging database is a March restore and its numbers mean nothing. That the client already rejected the obvious design. None of it belongs in a file every contributor reads, and all of it changes the advice you get.

The discipline that makes memory useful is one fact per note, with the reason attached. “We do not use soft deletes” is half a note. “We do not use soft deletes, because the reporting views join on deleted rows and silently double count” is a whole one, and it is the half you left out that stops the next agent from helpfully re-enabling them.

Skills are procedures, and the description is the index

The third layer is the one people underuse. A skill is a folder with a markdown file, read only when the task matches its description. That makes it right for anything long and situational: a deploy runbook, a review checklist, the exact sequence for regenerating a client.

---
name: deploy
description: Build and publish this site to the served docroot. Use when
  asked to deploy, publish, ship, release, or push the site live.
---

1. `npm run lint` and `npm run build` must both be clean first.
2. `node .app/deploy.js` mirrors `dist/` into the docroot.
3. Verify: the docroot `index.html` must match `dist/index.html`.
4. `api/*.php` is not deployed. It is already live.

The description is not a label, it is the entire retrieval mechanism, and it is the only part read before the skill is opened. Write it with the words that will actually be in the request, synonyms included. “Deployment helper” will sit unused forever; “deploy, publish, ship, release, push live” gets found.

Which layer does this belong in?

And the timing rule that matters more than the taxonomy: do not write any of this in advance. Write a rule the third time you repeat yourself. Rules written from imagination describe a project you think you have; rules written from repetition describe the one you do.