Claude Code for open source: how to write contributor-friendly configs

The contributor quality problem

You have a clean codebase. Consistent naming, a clear folder structure, tests for everything. Then a contributor opens a PR and none of that carries over. Different variable names, no tests, a new utility function dropped in the wrong directory.

This is not laziness. Most contributors spend ten minutes with a README and then start coding. If your conventions are not immediately visible, they get missed. And now that a lot of contributors use AI coding tools, this problem is bigger than it used to be. An AI assistant with no context about your project will produce code that looks reasonable but does not fit your patterns at all.

The fix is not a longer CONTRIBUTING.md that nobody reads. It is a CLAUDE.md that any AI-assisted contributor picks up automatically when they clone your repo.

What AI-assisted contributors actually need

A contributor using Claude Code opens their terminal, runs claude in the cloned repo, and their AI assistant immediately reads your CLAUDE.md. From that point on, the AI knows your stack, your conventions, and what not to do.

If you have no CLAUDE.md, the AI fills in the blanks with generic patterns. That is where the off-convention PRs come from.

A good OSS CLAUDE.md answers these questions before a contributor asks them:

• What is the tech stack and which versions matter?
• How is the project structured? Where does new code go?
• How do you run the tests? What is the coverage requirement?
• What naming and formatting conventions apply?
• What should contributors never do (force push, drop tables, break the public API)?
• How do you submit a PR? What does the CI pipeline check?

That is a two-page document. Not twenty. Specific beats comprehensive every time.

The CLAUDE.md for OSS projects

Here is a working template for an open source project. Adjust the specifics to match your stack.

# Project: OpenQueue

A lightweight job queue library for Node.js.

## Stack
- Node.js 20+, TypeScript 5.x
- Jest for tests
- Prettier + ESLint (config in root)

## Structure
- src/         — Library source code
- src/core/    — Queue engine, scheduler, worker pool
- src/adapters/ — Storage adapters (Redis, Postgres, in-memory)
- tests/       — Unit and integration tests (mirror src/ structure)
- examples/    — Runnable examples, one file per use case
- docs/        — Markdown docs, auto-deployed to GitHub Pages

## Running tests
npm test               # all tests
npm test -- --watch    # watch mode
npm test -- src/core   # single directory

## Before submitting a PR
- Run npm test — all tests must pass
- Run npm run lint — zero lint errors
- Add tests for any new functionality
- Update docs/ if you change public API

## Conventions
- Exports: named exports only, no default exports
- Error handling: throw typed errors (see src/errors.ts), never swallow exceptions
- Async: async/await throughout, no raw Promise chains
- Types: no 'any'. Use 'unknown' and narrow with type guards.

## Guardrails
- Never modify CHANGELOG.md manually — it is generated on release
- Never change the public API without opening an issue first
- Do not install new dependencies without discussion in the PR

## Good first issues
Look for the 'good-first-issue' label on GitHub. Most of these are isolated to one adapter or one utility function.

This is about 250 words. Short enough that someone actually reads it. Specific enough that an AI-assisted contributor gets real signal about how to work.

You can generate a starter config for your project with the ContextKit generator, then check its coverage with the Analyzer.

Using .claude/rules/ for granular guidance

For larger projects, a single CLAUDE.md gets unwieldy fast. The .claude/rules/ directory lets you split instructions into focused files. Claude Code loads every .md file in that directory automatically.

your-oss-project/
  CLAUDE.md                       # Project overview, stack, quick start
  .claude/
    rules/
      conventions.md              # Naming, formatting, code style
      testing.md                  # Test framework, coverage, mocking rules
      guardrails.md               # What contributors must never do
      contributing-workflow.md    # PR process, branch naming, CI checks
      adapter-interface.md        # Rules for writing new adapters

The split keeps each file focused. A contributor working on a new storage adapter reads adapter-interface.md and gets exactly what they need, not a 400-line document they have to scan.

Here is what a contributing-workflow.md looks like in practice:

# Contributing Workflow

## Branches
- Feature branches: feature/short-description
- Bug fixes: fix/short-description
- Branch off main, target main in PR

## Commits
- Use conventional commits: feat:, fix:, docs:, chore:, test:
- Keep commits atomic. One logical change per commit.

## PR process
1. Fork the repo and create your branch
2. Write tests first or alongside the change (we review both)
3. Run npm test and npm run lint before pushing
4. Open a draft PR early if you want feedback before it is done
5. Link the issue your PR resolves in the description

## CI checks (all must pass before merge)
- Unit tests (Jest)
- Lint (ESLint + Prettier)
- Type check (tsc --noEmit)
- Bundle size check (no more than 5% increase without discussion)

## What maintainers look for
- Does it fit the existing patterns?
- Is it tested?
- Does it change the public API? (needs issue + discussion first)
- Is the diff easy to review? (smaller is better)

Committing this to your repo means every contributor, human or AI-assisted, starts with the same understanding of how the workflow runs.

AGENTS.md for multi-contributor workflows

AGENTS.md is a newer convention that some projects are starting to use alongside CLAUDE.md. Where CLAUDE.md covers how to work with the code, AGENTS.md describes agent responsibilities.

For OSS projects with multiple active contributors, it can document which areas are owned by whom. This matters most when automated workflows (CI agents, bots, review agents) are also active on the repo.

# AGENTS.md

## Repository areas

### Core engine (src/core/)
Owner: @maintainer-handle
New contributors: coordinate in GitHub issues before large changes.
Safe to fix bugs and add tests without prior discussion.

### Storage adapters (src/adapters/)
Open for contributions. Follow the adapter interface in .claude/rules/adapter-interface.md.
New adapters need a working example in examples/ and integration tests.

### Documentation (docs/)
Open for contributions. Run 'npm run docs:build' to preview locally.
Typo fixes and clarifications do not need an issue first.

## Automated agents on this repo
- Renovate: opens dependency update PRs on Mondays
- Label bot: applies labels based on PR title prefixes
- Size bot: comments on PRs that increase bundle size

This gives AI-assisted contributors a map of where they can move fast and where they should slow down and coordinate. It also prevents an AI from happily rewriting core engine code that a maintainer guards carefully.

A real checklist for OSS maintainers

Use this before your next release or contributor drive:

• CLAUDE.md exists in the repo root. Not in docs/, not as a gist. In the root so Claude Code finds it automatically.
• Stack and versions are explicit. "Node.js 20+" is better than "Node.js". "Jest 29" is better than "Jest".
• Test commands are copy-paste ready. If a contributor has to figure out how to run tests, your config is missing information.
• Guardrails are concrete. "Do not change the public API" is concrete. "Be careful with breaking changes" is not.
• .claude/rules/ is used if the project is large. A 300-line CLAUDE.md is a sign you should split.
• Both files are committed to the repo. They are project conventions, not personal settings.
• The config is reviewed the same way code is. When conventions change, update the config in the same PR.
• AGENTS.md documents automated bots if any are active. Prevents contributors from being confused by automated PR activity.

Get started

If you maintain an open source project and you have no CLAUDE.md, start with a 30-minute audit. Open your repo, list your actual conventions, and write them down in a format a contributor could follow from day one.

The contributors who open the most off-convention PRs are usually the ones who would have followed the rules if the rules were visible. A well-written config closes that gap without adding any friction to the contribution process.

You can generate a starter config for your project with the ContextKit generator, then check its coverage with the Analyzer.

Once your config is in the repo, every contributor who uses an AI coding tool gets your conventions loaded at the start of every session. That is the closest thing to onboarding that actually scales.