Why I stopped using the system prompt
I used to put project rules in the system prompt. Things like “always use tabs,” “the entry point is app.py,” “tests live next to the file they test.” Then I realized three things and stopped.
The system prompt doesn’t survive the session
When the session ends, the system prompt is gone. The next session starts blank. So I spent the first 30 seconds of every session re-establishing context the agent should already have. The first 30 seconds are also when the agent is most likely to make assumptions. The setup was wrong: I was teaching the agent the project every time, and the agent was making decisions before the teaching was done.
The system prompt doesn’t survive the project
If I have two projects, each gets its own system prompt. I forget which is which. I copy-paste. The settings drift. The agent behaves differently in project A versus project B for reasons I can’t remember.
A file the agent reads every session fixes both
I moved everything to a CLAUDE.md (or AGENTS.md, depending on the agent) at the project root. The agent reads it on session start. It’s part of the repo. It gets reviewed in PRs. It changes when the project changes.
What goes in the file:
- Build and test commands (
pytest -x,npm run build, etc.) - Code style rules that aren’t auto-enforced (tabs vs spaces, import order, naming)
- File layout (
src/,tests/,scripts/, what lives where) - The “don’t” list (libraries to avoid, patterns to skip, the one bug we already fixed three times)
- How to run things locally (Python version, env vars, where the .env file goes)
What doesn’t go in the file:
- Personal preferences that aren’t project-specific
- Anything that’s a one-time instruction
- Long logs of “things to remember”
The file is small. The current one I’m using for the homelab repo is 47 lines. That’s the right size. If it’s longer than 100 lines, I’m probably over-fitting.
The agent still needs a system prompt for the things that are session-specific. “Look at the function in main.py and tell me why it’s slow” is a system prompt task. “Always use tabs” is a file task. Splitting them up makes both clearer.