• CLAUDE.md is a special onboarding file to familiarize Claude (an AI code assistant) with your codebase.
• It should clearly outline the WHY (purpose of the project), WHAT (tech stack, project structure, key components), and HOW (development process, running tests, build commands) for Claude.
• The file helps Claude understand your monorepo or multi-application project and know where to look for things without flooding it with unnecessary details.
• Keep CLAUDE.md concise and focused; ideally, it should be under 300 lines, with many recommending less than 60 lines for clarity and relevance.
• Use progressive disclosure: point Claude to where to find further information rather than including all details upfront, avoiding overwhelming the model’s context window.
• Complement CLAUDE.md with tools like linters, code formatters, hooks, and slash commands to separate concerns like implementation and formatting.
• CLAUDE.md is a powerful leverage point for getting better coding assistance but must be carefully crafted—not auto-generated.
• The file should include core commands, environment setup, guidelines, and unexpected behaviors relevant to the repository.
• Encouraging Claude to selectively read or confirm files before use can help maintain focus during sessions.

Hacker News Discussion

• Users emphasized the benefit of explicit instruction patterns like "This is what I'm doing, this is what I expect," which improves monitoring and recovery from errors.
• Some commenters felt these markdown files had marginal gains and that model quality mattered more than the presence of CLAUDE.md.
• A few highlighted the importance of writing documentation primarily for humans rather than solely for LLMs.
• Discussion included anticipation of more stateful LLMs with better memory, which would impact how such onboarding files evolve.
• Recommendations included hierarchical or recursive context structures in CLAUDE.md for large projects, allowing a root file plus targeted sub-files.
• Comments supported having Claude address the user specifically to verify it is following instructions properly.
• Some users noted improvements in model adherence compared to past versions, making CLAUDE.md files more effective now.
• Practical tips were shared for managing large monorepos and integrating CLAUDE.md with version control status.