Why Open Source Projects Need a CLAUDE.md
Open source projects have always struggled with contribution consistency. Contributors come from different backgrounds, use different editors, and follow different conventions. CONTRIBUTING.md helps, but it relies on contributors reading and remembering a document — which many don't, especially for drive-by contributions.
A growing percentage of open source contributions are now AI-assisted. Contributors use Claude Code, Cursor, or Copilot to understand unfamiliar codebases and generate patches. Without a CLAUDE.md, the AI generates code based on its training data — which may not match your project's specific patterns. The contributor submits a PR, the maintainer requests style changes, and the contributor may never come back.
A CLAUDE.md in your repo root changes this dynamic. When a contributor opens your project with an AI assistant, the AI reads your conventions before generating anything. The contribution matches your style from the first attempt. Fewer review rounds, happier contributors, less maintainer burden.
What OSS Rule Files Should Cover
Open source CLAUDE.md files need to balance two goals: give enough context for consistent contributions, and keep rules simple enough that contributors don't need deep project knowledge to follow them.
Focus on the conventions that contributors get wrong most often. Check your PR history — what feedback do you give repeatedly? 'We use X testing framework, not Y.' 'We don't use default exports.' 'Error types go in src/errors/, not inline.' These recurring comments are your highest-priority rules.
Avoid project-internal rules that only the core team needs to know. Database migration patterns, deployment procedures, and release workflows don't belong in a contributor-facing CLAUDE.md. Keep it focused on code style, architecture patterns, and contribution workflow — the things that affect PRs.
- Code style: naming, exports, formatting preferences beyond what the linter handles
- Architecture: directory structure, where new files go, module boundaries
- Dependencies: approved libraries, what to use instead of common alternatives
- Testing: framework, file naming, what needs tests and what doesn't
- PR conventions: commit message format, branch naming, what to include in PR description
Check your PR history for the feedback you give repeatedly. Those recurring comments are your highest-priority rules — each one eliminates a round of review back-and-forth.
A Template for Open Source Projects
This template is designed for open source projects. It's shorter than a company CLAUDE.md because contributors need less context — they're working on focused PRs, not full features. Target 30-50 lines.
Start with a project overview: what the project does, what stack it uses, and the key architectural decisions. This gives the AI enough context to generate appropriate code without the contributor needing to read the entire codebase first.
Follow with contribution-specific rules: where to add new features, how to write tests, what the PR process looks like. End with a short 'don't' section for the most common mistakes contributors make.
Include a line referencing CONTRIBUTING.md for non-AI details: 'For contribution workflow, see CONTRIBUTING.md. This file focuses on AI-specific coding conventions.' This avoids duplicating content between the two files.
The most effective OSS rule files are under 50 lines. Contributors need 10-15 conventions that determine whether their PR passes review — not your entire architecture.
Updating CONTRIBUTING.md to Reference CLAUDE.md
If your project has a CONTRIBUTING.md (and it should), add a section that references the CLAUDE.md. Something like: 'If you use an AI coding assistant, this project includes a CLAUDE.md with project-specific conventions. Your AI assistant will read it automatically and generate code that matches our style.'
This serves two purposes: it tells contributors with AI tools that the rules exist (they might not notice the file), and it tells contributors without AI tools that the conventions are documented somewhere they can read manually.
Some maintainers worry that adding a CLAUDE.md sends the message 'we expect AI-generated contributions.' It doesn't — it sends the message 'if you use AI tools, we've made it easy to contribute quality code.' It's an accessibility improvement, not a mandate.
Maintaining Rules as the Project Evolves
Open source CLAUDE.md files need lighter maintenance than company rule files. The conventions in an OSS project change less frequently — major framework migrations are rare, and style decisions are usually settled early in the project's life.
Update the CLAUDE.md when you make a significant architectural decision: adopting a new testing framework, changing the module structure, adding a new major dependency. These are the changes that affect how contributors write code.
Accept CLAUDE.md improvements from contributors. If someone submits a PR that adds a helpful rule they discovered while contributing, merge it. The file gets better over time through the same collaborative process that improves the rest of the codebase.
Accept CLAUDE.md improvements from contributors. If someone adds a helpful rule while contributing, merge it. The file improves through the same process as the rest of the codebase.
Patterns from Popular Projects
Several high-profile open source projects now include CLAUDE.md or equivalent files. The pattern is emerging across the ecosystem as maintainers recognize the leverage: one file improves the quality of every AI-assisted contribution.
Common patterns in successful OSS rule files: a brief project description (2-3 sentences), stack declaration (language, framework, key libraries), directory structure overview, testing requirements (what needs tests, what framework to use), and a short 'avoid' list (patterns the maintainer doesn't want to see).
The most effective OSS rule files are under 50 lines. Contributors don't need to know your entire architecture — they need to know the 10-15 conventions that determine whether their PR passes review on the first try. Everything else is context for core maintainers, not contributors.