Context belongs in the repository, not in the prompt
Our own repository has both CLAUDE.md and AGENTS.md: stack, commands, conventions, dark mode rules, SEO requirements and what the agent must not change. Every new session starts with the same knowledge. When the agent repeats a mistake, we do not rewrite the prompt, we add a rule to the file. Teams learn this on their own code: what belongs in the context, what only bloats it and when to split the file by folder.
- One rules file for the whole team, versioned in git
- Build, test and lint commands right in the instructions
- A repeated agent mistake becomes a new rule
- A shorter, precise file beats a long one