CLAUDE.md for Open Source Maintainers

# CLAUDE.md

## Project

[Project] — [one sentence]. Open source ([license]), used by [scale: e.g. "~40k weekly downloads"]. Compatibility and community trust outrank feature velocity here.

## Commands

```bash
[install / test / lint / docs-build commands]
```

## Compatibility rules (the prime directive)

- Public API = everything documented + anything a reasonable user could depend on (exported names, CLI flags, config keys, error message FORMATS if parseable)
- Breaking changes: only in majors, with a deprecation period of at least one minor first — deprecate with a warning that says what to use instead
- New features must not change existing default behavior
- When in doubt whether something is public API: it is

## Working on issues

- Reproduce before fixing — ask for a minimal reproduction on the issue if one isn't provided; don't guess-fix
- Bug fixes ship with a regression test derived from the reproduction
- Check for duplicate/related issues and link them
- Never close an issue as stale if it has a valid reproduction

## Reviewing external PRs

- Review the contribution that exists, not the one you'd have written — style nits below project-lint level don't block
- Required regardless of contributor: tests for behavior changes, docs for user-facing changes, no unrelated diffs mixed in
- If a PR is 80% right, suggest the specific 20% rather than rewriting it yourself — contributors return when their PR ships
- Security-sensitive areas ([list yours: e.g. auth, deserialization, sandboxing]) always need a maintainer's human review — flag, don't merge

## Tone in public writing (issues, PRs, release notes)

- Assume good faith and competence; thank first-time contributors specifically
- Explain the WHY behind rejections with a link to precedent or policy where possible
- No corporate-speak — write like a helpful human maintainer

## Releases

- Follow semver strictly (see compatibility rules)
- Changelog entries are user-facing: what changed for THEM (use the changelog format in .github/)
- Never publish/release without the maintainer's explicit go

How to use

1. 1Copy to your repo root, fill in your commands, license, scale, and security-sensitive paths.
2. 2The compatibility section is the heart of it — adjust the deprecation policy to yours.
3. 3The PR review section makes agent-assisted triage safe: it encodes maintainer judgment, not just correctness checks.

Examples

Pro tips

• The 'review the contribution that exists' rule is the difference between a project that attracts contributors and one that exhausts them.