Good AI Rule Files to Share - Writing Effective CLAUDE.md Files
Good AI Rule Files to Share - Writing Effective CLAUDE.md Files
A 200-line CLAUDE.md file with mandatory testing rules changes everything about how an AI agent interacts with your codebase. Without it, the agent guesses. With it, the agent follows your team's actual standards.
What Makes a Good Rule File
The best CLAUDE.md files are not documentation. They are executable instructions. Every line should change the agent's behavior in a measurable way.
Start with mandatory testing. If your rule file says "every task must be verified before it is considered done," the agent will run tests before reporting completion. If it says "build and launch the app after UI changes," the agent will do that instead of just editing files and hoping.
Structure That Works
Break your rule file into clear sections:
- Testing requirements - what must be verified and how
- Coding standards - naming conventions, file organization, import patterns
- Project context - architecture decisions, key dependencies, deployment targets
- Forbidden patterns - things the agent should never do (force push, skip hooks, create unnecessary files)
The Mandatory Testing Pattern
The most impactful rule you can add is a testing matrix. Map change types to verification methods. UI changes get screenshots. Logic changes get programmatic test hooks. Backend changes get log verification. This eliminates the most common failure mode - agents that edit code but never check if it works.
Keep It Honest
Do not pad your rule file with aspirational guidelines nobody follows. Every rule should reflect how your team actually works. If you do not enforce consistent naming in code review, do not put it in the rule file. The agent will spend tokens on something that does not matter.
Share and Iterate
The best rule files are shared across teams. When someone discovers a pattern that prevents a class of agent mistakes, add it. When a rule creates more friction than value, remove it. Treat it like any other piece of infrastructure code.
Fazm is an open source macOS AI agent. Open source on GitHub.