CodeVetter · Repo Unpack · Contributor handoff
biomejs/biome
Read AGENTS.md and the relevant skill under .claude/skills before editing. Keep diffs small, add a failing test for bug fixes, and do not hand-edit generated registries. Run the crate's tests, then just f and just l before commit. User-facing changes need a changeset; PR prose is written by the human, not the agent. Internal dev-dependencies must use path dependencies.
- First files for any task: AGENTS.md, CONTRIBUTING.md, and the skill that matches the surface (lint-rule-development, parser-development, formatter-development, testing-codegen, changeset, doc-comments).
- Safe edit boundary: change the language crate that owns the behavior and its tests. Do not drive a formatter fix only through snapshots, and do not change biome_rowan unless the CST model itself is wrong.
- Bug fixes need a spec or unit test that fails without the fix. Lint fixtures use expectation comments. Formatter changes update insta snapshots only after the behavior is reviewed.
- After a rule or assist rename, run just gen-rules and just gen-configuration. After an .ungram edit, run just gen-grammar <lang> and just gen-formatter. Bindings can be left to CI autofix unless local verification needs them.
- Verification commands: cargo test -p <crate> or just test-crate <crate>, then just f and just l. Full just ready is codegen for the whole repo and is slow.
- Comments and rustdoc must follow doc-comments. Lint rustdoc inside declare_lint_rule! is end-user documentation and also follows the lint-rule guide. Do not narrate the PR in comments.
- User-facing behavior needs a changeset created with just new-changeset, targeting @biomejs/biome. Patch goes to main; minor or major features and nursery promotions that affect users target next. Internal refactors do not get a changeset.
- Do not write PR descriptions. Preserve .github/PULL_REQUEST_TEMPLATE.md. If a PR is opened, disclose AI assistance. Conventional commit titles are required.
- Dev-dependencies on internal crates use path = "../biome_*", never workspace = true. Regular dependencies keep workspace = true.
- Trap: nursery rules use version metadata "next" until release. Promoting a rule is a branch and versioning decision, not only a group move.
- Trap: syntax text must not assume token text is contiguous UTF-8 without the syntax-text-handling rules. TokenText and range APIs exist because trivia and embedded languages break naive slices.
- Review gate: after implementation, a fresh subagent runs biome-code-review with only the scope and requirements, not suspected bugs. Actionable findings are fixed and verification is repeated.
- The binary version baked into release builds uses BIOME_VERSION. A value other than 0.0.0 disables recommended nursery rules in production builds. Local cargo build --bin biome does not set that variable.