Hypothesis

Writing a good CLAUDE.md

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.