On this page
keeping “Style/Behavior” in one and “Permissions/Capabilities” in the other is a very clean way to organize your AI’s brain.
CLAUDE.md: The “Personal Assistant” Guide
This file became a “thing” largely because of Cursor (the AI-native IDE). It acts as a persistent memory bank for the AI. Instead of reminding Claude every five minutes to “use functional components” or “don’t use semicolons,” you put it here.
Common contents include:
- Coding Standards: “Use TypeScript, strict mode, and Tailwind CSS.”
- Architecture Patterns: “We use the Feature-Sliced Design (FSD) pattern.”
- Testing Rules: “Always write a Vitest spec before submitting a PR.”
Tone: “Be concise; don’t explain things I already know.”
AGENTS.md: The “Operational Manual”
AGENTS.md is more agnostic and often more functional. It’s designed for autonomous agents that might be performing tasks like running tests, fixing bugs, or managing documentation without a human constantly over their shoulder.
Common contents include:
- Tool Access: “You have permission to run npm test but NOT npm publish.”
- Environment Context: Information about the CI/CD pipeline or Docker containers.
- Inter-Agent Communication: Rules for how “Agent A” (the Coder) should talk to “Agent B” (the Reviewer).
- Security Boundaries: “Do not read files inside the .env directory.”