Writing a CLAUDE.md That Claude Actually Follows — Transcript

Full transcript

1. 0:02The ClaudeMD file is not an enforced configuration, meaning if you keep adding to one gigantic file, the less Claude is able to follow it correctly.
2. 0:09Here's how you can keep your ClaudeMD file tight and to follow your instructions much more reliably.
3. 0:16Simply put, the longer the file gets, the more it has to compete with itself.
4. 0:20First, is ClaudeMD even the right tool for the job?
5. 0:23A hard rule like never push to main belongs in a pre-tool use hook instead.
6. 0:27The hook is designed to stop the push even when Claude does try to do it.
7. 0:32The CloudMD file doesn't just exist in your project file.
8. 0:35There's three other places.
9. 0:37One's your managed policy, then your user file, then your project file, and finally local.
10. 0:42Cloud loads every memory file together.
11. 0:44Nothing gets dropped, and org policy is always in play.
12. 0:46Local is for what's just yours in this project.
13. 0:49Say you're refactoring off the sprint and want Cloud to hold your architectural decisions in mind.
14. 0:54Well, that goes in local, not the shared project file.
15. 0:58To make your claude.md files easier to maintain, use the path to file syntax to split up your instructions.
16. 1:04Just know what they buy you though.
17. 1:06Claude expands imported files inline at launch right alongside the file that references them.
18. 1:11Imports help you organize a large claude.md file, but everything still loads up front and they don't reduce context.
19. 1:18So we can make our Claude.md file much shorter.
20. 1:21Whether Claude obeys it comes down to phrasing, and most rules fail because they're pretty vague.
21. 1:26First, be specific and checkable.
22. 1:28Don't put things like follow best practices.
23. 1:30Do you even know what that means?
24. 1:32Well, don't expect Claude to magically.
25. 1:34Put new API routes and source API handlers, one per file.
26. 1:38Well, that's explicit, so put that instead.
27. 1:41Name the replacement.
28. 1:42Don't use default exports leaves the alternative open.
29. 1:45Use name exports, not default exports, closes that potential misinterpretation.
30. 1:50And then realize that emphasis is a budget.
31. 1:53Important and you must raises a rule priority, but only relative to everything quieter around it.
32. 1:59Spend them on the two or three rules that hurt when broken.
33. 2:02The file also stays under revision.
34. 2:04When Claude does the wrong thing, we'll treat that as a bug report against your Claude.md file.
35. 2:09Tell it, add that to the Claude.md file and it'll write that rule for you.
36. 2:17Treat your clod.md file like production code.
37. 2:20If you can't justify a line, well, delete it.
38. 2:22Move enforcement to hooks, organize with imports, and scope past specific conventions into your rules so that they load only when they apply.
39. 2:31The leaner the file, the more of it clod follows.