Writing a good Claude.md (humanlayer.dev)

Article summary

The article discusses the importance of writing a good CLAUDE.md file, which is used to onboard Claude, a coding agent, into a codebase. A good CLAUDE.md file should cover the project's purpose, structure, and how to work on it, but should be concise and focused on universally applicable information. The article provides guidelines on how to write a good CLAUDE.md file, including keeping it short, using progressive disclosure, and not using it as a linter. The goal is to help Claude understand the codebase and work effectively on tasks.

Main themes

• CLAUDE.md best practices
• Coding agent onboarding
• Concise documentation
• Progressive disclosure
• LLM instruction following
• Codebase management

What commenters say

• Documenting code for humans is not sufficient for AI tools like Claude, and special considerations are needed.
• A centralized location like a README or CLAUDE.md is necessary for providing context to AI tools.
• Some argue that CLAUDE.md is unnecessary and that good code documentation and linting are enough.
• Others believe that CLAUDE.md is essential for providing specific instructions and context to AI tools, and that it should be used in conjunction with other tools like linting and testing.
• The effectiveness of CLAUDE.md depends on its length and applicability, with shorter and more focused files being more effective.
• There is a need for a better understanding of how AI tools like Claude interact with codebases and how to provide them with the necessary context and instructions.
• Some commenters have had negative experiences with Claude ignoring instructions in CLAUDE.md or causing unintended consequences, highlighting the need for careful consideration and testing.
• The use of CLAUDE.md is not a replacement for good coding practices, but rather a supplement to help AI tools work effectively with the codebase.