Use CLAUDE.md as instructions, not project documentation
Global and project-specific work best when they have different jobs. A global file should hold rules that apply across all projects, such as general working style and personal ps.
A project-specific file should hold only the commands, rules, and cautions needed for that one . should guide how Claude behaves, not describe the codebase in detail.
This keeps old code descriptions from misleading Claude. It also reduces , repeated rules, and conflicting instructions.
Key points
- should mainly tell Claude how to work, not explain the whole codebase.
- Use a global for rules that apply to every project.
- Use a project-specific for commands and cautions that only apply to one .
- Separating the two helps avoid repeated or conflicting instructions.
- Short, current instructions reduce and stale guidance.