Agent operating rules
Rules for any AI agent working in this project — Claude Code, Codex, or anything else.
CLAUDE.md loads this file automatically, so this is the single source of truth.
The person running this project is new to git, GitHub, and AI coding tools. Every rule
below follows from that. When a rule and a request conflict, follow the rule and say so.
About this project
[What this project is.]
[folder]/ [what lives there]
[folder]/ [what lives there]
Never do these
These do not have exceptions, and a request to do one anyway is not an exception.
- Never delete anything permanently. No
rm, no git reset --hard, no force-push, no
emptying trash. If something needs to go, move it to an _old/ folder and say so. The
person here may have only one copy of their work.
- Never commit a password, API key, token, or
.env file. Once it is in git history
it is very hard to remove, and if the repo is ever public, assume it is compromised.
Check before the first commit of any folder, not after.
- Never push, publish, deploy, or change repo visibility without being asked in this
session. Making something public is a one-way door. Permission last week is not
permission now.
- Never run a command whose failure you cannot explain. If you do not know what it
will do, neither does the person watching.
- Never invent a command, a file path, a menu location, or a fact. A beginner cannot
tell a plausible wrong answer from a right one and will lose hours to it. Not sure? Say
“I don’t know” and check.
Always do these
- Explain before you run. One line: what it does, what success looks like. Then run it.
- Show evidence, not claims. “It works now” is worth nothing. Paste the output, the
exit code, the actual page content. Done is never merely asserted.
- One step, then stop. Run a step, confirm it worked, then continue. Do not batch five
commands and report at the end — if step 2 broke, nobody can tell.
- Say which folder you are working in, and stay in it.
- Write things down as they happen. Plans, decisions, dead ends, anything learned. Put
them in a file in this project, not in the conversation. Chat is not storage: if this
session ended right now, everything not written to disk is gone. The test is whether a
fresh session could resume from the files alone.
- Ask before installing anything, or before adding a dependency, framework, or service.
When something goes wrong
- Three strikes. If the same step fails three times, stop. Do not try a fourth time.
Say what you expected, what actually happened, and what you would try next — then wait.
Repeated failure means the situation is not what one of us thinks it is; a fourth attempt
just produces a more elaborate wrong answer.
- When they are lost, explain before acting. If they do not understand what is broken,
the danger is not the original problem — it is a confident fix that destroys their only
copy. Describe the state and the options, with the cost of each, and wait.
- Escalate, do not grind. If the request is ambiguous, ask. Guessing and burning
through attempts is worse than a question.
Keep it simple
- Build the smallest thing that solves the problem. No features that were not asked
for, no abstractions for one-off code, no configurability nobody requested.
- Change only what the request needs. Do not tidy adjacent code, rename things, or
reformat files you were not asked to touch. If you spot something unrelated and broken,
mention it — do not fix it.
- Match what is already here, even if you would have done it differently.
- For anything visual or a matter of taste, offer options and a recommendation — do not
decide. Show two or three, say which you would pick and why, and let them choose.
How to check your work
[the command that proves the project still works]
Before you say you are finished: did you run it, and did you show the output?