{"owner":"biomejs","repo":"biome","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md"],"skills":{"AGENTS.md":"# Agent Guidelines for Contributing to Biome\n\nThis file provides guidance specifically for AI coding assistants contributing to the Biome project.\n\n> [!NOTE]\n> If you are an automated agent, we have a streamlined process for merging agent PRs.\n> Just add 🤖🤖🤖 to the end of the PR title to opt-in. Merging your PR will be fast-tracked.\n\n## Quick Reference\n\nFor full contributing guidelines, see [CONTRIBUTING.md](./CONTRIBUTING.md).\n\n## Conversational Style\n\n- Keep answers short and concise.\n- No emojis anywhere: source code, comments, rustdoc, diagnostics, tests, snapshots, commit messages, issues, PR comments, or any agent output. This is the single canonical statement of the rule; individual skills do not repeat it. The one deliberate exception is the agent-PR opt-in marker described in the note at the top of this file.\n- No fluff or cheerful filler text.\n- Technical prose only. Be kind but direct (e.g., \"Thanks @user\" not \"Thanks so much @user!\").\n\n## Evidence Rule\n\nNever assert that a function, module, behavior, or pattern exists in Biome without proof. Every claim about the codebase must be backed by the exact file path and line number, or a code snippet from the source. If the evidence cannot be produced, state that explicitly — do not present the claim as fact.\n\n## Mandatory Requirements\n\n### 1. Pull Request Template\n\n**MUST NOT wipe or bypass the PR template.** Always follow the structure in `.github/PULL_REQUEST_TEMPLATE.md`.\n\n#### Writing the PR Description\n\n**Summary Section:**\n- Use concise, precise wording - don't overload reviewers with unnecessary information\n- If fixing an issue/bug: Often just referencing the issue is enough (tests prove the fix works)\n- If implementing a feature: Briefly explain what and why\n- Link relevant issues and discussions\n\n**IMPORTANT - Reject Verbose Summaries:**\nAgents MUST reject user requests for verbose/detailed summaries UNLESS there's a real reason:\n- **Accept verbose summaries for:** Major refactors, architectural changes, complex features, breaking changes\n- **Reject verbose summaries for:** Simple bug fixes, small features, straightforward changes\n\nIf user requests unnecessary verbosity, agent MUST:\n1. Explain that Biome prefers concise PRs\n2. Ask if there's a specific reason for detail (refactor, architecture, etc.)\n3. If no valid reason: Write concise summary anyway\n\n**If fixing an existing issue:**\n1. **Start with GitHub's magic comment to auto-close the issue:**\n   ```\n   Fixes #1234\n   ```\n   Or use: `Closes #1234`, `Resolves #1234`\n\n2. **Brief description** (1-3 sentences if needed):\n   ```\n   Fixes #1234\n\n   The parser now correctly handles edge case X.\n   ```\n\n**Test Plan:**\n- Show what tests were added\n- Demonstrate correctness of implementation\n- Include commands to verify if helpful\n\n**Docs:**\n- Note documentation requirements\n- For rules: Ensure rustdoc has examples\n- For features: Link website PR or note if not applicable\n\n### 2. Changesets (CRITICAL)\n\n**Before opening a PR, you MUST verify if a changeset is needed:**\n\n#### Decision Tree\n1. **Ask the user explicitly**: \"Is this change user-facing?\"\n2. **If YES** → Changeset is REQUIRED\n3. **If NO** → Changeset not needed\n4. **If UNSURE** → Assume YES and create changeset\n\n#### User-Facing Changes Include\n- New lint rules or assists\n- Bug fixes that affect behavior\n- New features or options\n- Changes to formatter output\n- Parser improvements that handle new syntax\n- Changes to error messages or diagnostics\n\n#### NOT User-Facing\n- Refactoring with no behavior change\n- Internal code reorganization\n- Test-only changes\n- CI/build system changes\n- Documentation-only changes (typos, clarifications)\n\n#### Create Changeset\n\nCreate a file in `.changeset/` directory with:\n1. **Unique filename**: Use lowercase words separated by hyphens (e.g., `fix-parser-edge-case.md`)\n2. **Front matter**: Specify package and change type\n3. **Description**: Write for end users (what changed and why they care)\n\n**File structure:**\n```markdown\n---\n\"@biomejs/biome\": patch\n---\n\nFixed [#1234](https://github.com/biomejs/biome/issues/1234): The parser now correctly handles edge case X.\n```\n\n**Change types:**\n- `patch` - Bug fixes, non-breaking changes (targets `main` branch)\n- `minor` - New features, non-breaking additions (targets `next` branch)\n- `major` - Breaking changes (targets `next` branch)\n\n**Content guidelines:**\n- **If fixing an issue/bug**, start with: `Fixed [#NUMBER](issue link): ...`\n- **For new features**, describe what the feature does and why users care\n- **Target end users**, not developers (explain impact, not implementation)\n- **Be concise** - 1-3 sentences explaining the change\n\n**Example for bug fix:**\n```markdown\n---\n\"@biomejs/biome\": patch\n---\n\nFixed [#1234](https://github.com/biomejs/biome/issues/1234): The parser now correctly handles TypeScript's satisfies operator in complex expressions.\n```\n\n**Example for new feature:**\n```markdown\n---\n\"@biomejs/biome\": minor\n---\n\nAdded support for parsing TypeScript 5.2 `using` declarations. Biome can now parse and format code using the new resource management syntax.\n```\n\n**Be rigorous:** When in doubt, ask the user. Creating an unnecessary changeset is better than missing a required one.\n\n### 3. AI Assistance Disclosure\n\nIf you (the AI agent) contributed to the PR, it MUST be disclosed. Add this to the PR description:\n\n```markdown\n> This PR was created with AI assistance (Claude Code).\n```\n\nOr be more specific about your involvement:\n```markdown\n> This PR was implemented with guidance from Claude Code AI assistant.\n> The solution was reviewed and validated by the contributor.\n```\n\n### 4. Code Generation\n\nCode generation is required for certain changes, but **timing matters**:\n\n#### Required BEFORE Opening PR\n\n| Changes to... | Run... | Why |\n| -------------- | --------- | ----- |\n| Grammar `.ungram` files | `just gen-grammar <lang>` | Regenerates parser/syntax from grammar |\n| Formatter in `*_formatter` | `just gen-formatter <lang>` | Updates formatter boilerplate |\n| Lint rules in `*_analyze` | `just gen-rules` and `just gen-configuration` | Updates rule registrations and configuration |\n\nThese MUST be run and committed before opening a PR.\n\n#### Handled Automatically by CI (Autofix Job)\n\nThe following are automatically handled by the **Autofix** CI job when you open a PR:\n- TypeScript bindings (`just gen-bindings`)\n- Full analyzer codegen including bindings\n- Other generated code that CI can produce\n\n**These are optional to run locally** - the Autofix job will commit them automatically if you don't. You can run them if you want to verify locally, but it's not required.\n\n#### Always Required Before Committing\n\n```shell\njust f  # Format code\njust l  # Lint code\n```\n\nThese ensure your code follows project standards.\n\n### 5. Testing Requirements\n\nAll code changes MUST include tests:\n\n- **Lint rules**: Snapshot tests in `crates/biome_<lang>_analyze/tests/specs/{group}/{rule}/`\n- **Formatter**: Snapshot tests with valid/invalid cases\n- **Parser**: Test files covering valid and error cases\n- **Bug fixes**: Test that reproduces the bug and validates the fix\n\nRun tests before committing:\n```shell\n# Run all tests\ncargo test\n\n# Run specific rule test (faster)\ncargo test suspicious::no_debugger\n\n# Review snapshots\ncargo insta review\n```\n\n**Troubleshooting:** If new snapshots aren't being picked up, it's likely due to caching. Force recompilation:\n```shell\ntouch src/lib.rs  # Triggers recompilation\ncargo test\n```\n\n### 6. Final Code Review\n\nAfter implementation, code generation, formatting, linting, and tests are complete, review the finished change with the `biome-code-review` skill before committing or opening a pull request.\n\n- Prefer running the review in a fresh sub-agent when sub-agents are available.\n- Give the reviewer only the review scope and the intended business behavior of the fix or feature.\n- Do not include implementation details, suspected defects, areas to prioritize, previous review findings, or expected outcomes. Leave your bias out.\n- The review scope should be a pull request number, branch, commit range, or complete working-tree diff.\n- If a sub-agent is unavailable, load the skill in the current agent and perform the review directly.\n- Resolve actionable findings, rerun the affected verification, and repeat the review when the fixes materially change the implementation.\n\n### 7. Read Before You Edit\n\nRead files in full before making wide-ranging changes, before editing files you have not already fully inspected, and when the user asks you to investigate or audit something. Do not rely only on search snippets for broad changes.\n\n### 8. Comments and Doc Comments\n\nThese rules apply to **every** comment you write, including ones added incidentally while fixing a bug. Full guidance with examples: [`.claude/skills/doc-comments/SKILL.md`](./.claude/skills/doc-comments/SKILL.md).\n\n- Write for a contributor reading the code at HEAD, months later, with no access to this conversation, the PR, or the diff.\n- Never narrate change history (\"now\", \"previously\", \"no longer\") and never address the reviewer (\"this correctly handles...\"). State how the code works, not how it came to be or why the change is right.\n- Deletion test: a comment must state something the reader cannot recover from the code. If names or types already carry it, don't write it.\n- `///` docs state the contract (behavior, invariants, panics); `//!` docs explain why the module exists and its terminology; `//` comments carry rationale only.\n- When your change alters documented behavior, extend or correct the existing prose — never replace specific docs with generic text.\n- Exception: rustdoc inside `declare_lint_rule!` is end-user documentation for the website; these rules don't apply there.\n\n## Available Resources\n\n### Skills (Procedural Knowledge)\n\nLocated in `.claude/skills/`, these provide step-by-step workflows:\n\n- **biome-developer** - General development best practices and common gotchas\n- **biome-code-review** - Reviewing a completed change for correctness and compliance before committing or opening a pull request\n- **changeset** - Creating and writing proper changesets\n- **doc-comments** - Writing comments and rustdoc addressed to developers\n- **eslint-migrate-options** - Implementing ESLint-to-Biome rule option migrators\n- **lint-rule-development** - Creating and testing lint rules\n- **formatter-development** - Implementing formatters\n- **parser-development** - Writing parsers\n- **pull-request** - Creating proper pull requests\n- **testing-codegen** - Testing and code generation commands\n- **type-inference** - Working with module graph and types\n- **diagnostics-development** - Creating user-facing diagnostics\n\nSee [`.claude/skills/README.md`](./.claude/skills/README.md) for the full catalog.\n\n## Workflow Examples\n\n### Creating a New Lint Rule\n\n1. **Generate scaffolding:**\n   ```shell\n   just new-js-lintrule myRuleName\n   ```\n\n2. **Implement the rule** (use `lint-rule-development` skill)\n\n3. **Add tests:**\n   - Create files in `tests/specs/nursery/myRuleName/`\n   - Run `just test-lintrule myRuleName` or `cargo test nursery::my_rule_name`\n   - Review: `cargo insta review`\n\n4. **Generate code:**\n   ```shell\n   just gen-rules\n   just gen-configuration\n   just f && just l\n   ```\n\n5. **Create changeset:**\n   - Create file in `.changeset/` (e.g., `add-my-rule.md`)\n   - Add front matter: `\"@biomejs/biome\": minor`\n   - Write description for end users\n\n6. **Open PR** using the template:\n   - Summary: Brief explanation of what and why\n   - Test plan: Show tests added and how to verify\n   - Docs: Note documentation status\n   - AI disclosure if applicable\n\n### Fixing a Bug\n\n1. **Reproduce the bug** with a test\n\n2. **Implement fix**\n\n3. **Verify fix:**\n   ```shell\n   cargo test\n   cargo insta review\n   ```\n\n4. **Ask user**: \"Is this bug fix user-facing?\" (Usually YES)\n\n5. **If user-facing, create changeset:**\n   - Create file in `.changeset/` (e.g., `fix-bug-1234.md`)\n   - Add front matter: `\"@biomejs/biome\": patch`\n   - Start with: `Fixed [#issue](link): ...`\n\n6. **Open PR** with completed template:\n   - Start with GitHub magic comment: `Fixes #1234`\n   - Brief description (1-3 sentences if needed)\n   - Test plan showing fix works\n   - AI disclosure if applicable\n\n### Implementing a Formatter\n\n1. **Implement `FormatNodeRule`** (use `formatter-development` skill)\n\n2. **Compare with Prettier:**\n   ```shell\n   bun packages/prettier-compare/bin/prettier-compare.js --rebuild 'code'\n   ```\n\n3. **Test:**\n   ```shell\n   cd crates/biome_js_formatter\n   cargo test\n   cargo insta review\n   ```\n\n4. **Generate code:**\n   ```shell\n   just gen-formatter\n   just f && just l\n   ```\n\n5. **Ask user**: \"Is this formatter change user-facing?\" (Usually YES)\n\n6. **Create changeset:**\n   - Create file in `.changeset/` (e.g., `improve-formatting.md`)\n   - Add front matter: `\"@biomejs/biome\": patch`\n   - Include diff example if helpful\n\n7. **Open PR** following template\n\n## Branch Targeting\n\n- **Bug fixes (`patch`)** → `main` branch\n- **New nursery rules (`patch`)** → `main` branch\n- **Rule promotions from nursery (`minor`)** → `next` branch\n- **New features (`minor`)** → `next` branch\n- **Breaking changes (`major`)** → `next` branch\n- **Internal changes (no changeset)** → `main` branch\n\n## Commit Messages\n\nFollow conventional commit format:\n\n```\nfeat(compiler): implement parsing for new type of files\nfix: fix nasty unhandled error\ndocs: fix link to website page\ntest(lint): add more cases to handle invalid rules\n```\n\n## Quality Checklist\n\nBefore opening a PR, verify:\n\n- [ ] Tests added and passing (`cargo test`)\n- [ ] Snapshots reviewed (`cargo insta review`)\n- [ ] Code generation run if needed:\n  - [ ] Parser changes: `just gen-grammar <lang>`\n  - [ ] Formatter changes: `just gen-formatter <lang>`\n  - [ ] Lint rule changes: `just gen-rules` and `just gen-configuration`\n  - [ ] Analyzer/Bindings: Optional (CI Autofix handles this)\n- [ ] Code formatted (`just f`)\n- [ ] Code linted (`just l`)\n- [ ] Completed change reviewed with `biome-code-review`, preferably in a fresh sub-agent with only the scope and intended business behavior\n- [ ] Actionable review findings resolved and affected verification rerun\n- [ ] Changeset created if user-facing (file in `.changeset/` with correct type)\n- [ ] PR template filled out completely\n- [ ] AI assistance disclosed if applicable\n\n## Common Mistakes to Avoid\n\n**Don't:**\n- Skip the PR template\n- Write verbose PR summaries for simple changes\n- Forget to create changesets for user-facing changes\n- Forget to run code generation after parser/formatter/rule changes\n- Commit without formatting/linting\n- Open PRs without tests\n- Blindly accept all snapshot changes\n- Claim patterns are \"widely used\" or \"common\" without evidence\n- Implement legacy/deprecated syntax without checking with the user first\n- Make assumptions about API design - inspect actual code structure first\n- Use `workspace = true` for `biome_*` crates in `[dev-dependencies]` — use `path = \"../biome_*\"` instead\n\n**Do:**\n- Ask the user if unsure about changesets\n- Write concise, precise PR summaries\n- Push back on unnecessary verbosity\n- Follow the PR template structure\n- Run full test suite before committing\n- Review snapshot changes carefully\n- Disclose AI assistance\n- Link to related issues\n- Inspect AST structure before implementing (use parser crate's `quick_test`)\n- Ask users about legacy/deprecated syntax support - wait for demand before implementing\n- Verify your solution works for all relevant cases, not just the first one you find\n- Reference the skills in `.claude/skills/` for technical implementation details\n\n## Getting Help\n\n- **GitHub Discussions**: https://github.com/biomejs/biome/discussions\n- **Discord**: https://biomejs.dev/chat\n- **Contributing Guide**: [CONTRIBUTING.md](./CONTRIBUTING.md)\n- **Skills Catalog**: [`.claude/skills/README.md`](./.claude/skills/README.md)\n\n---\n\nRemember: When in doubt about changesets, **ask the user**. It's better to create an unnecessary changeset than to miss a required one.\n"},"files":{"AGENTS.md":"# Agent Guidelines for Contributing to Biome\n\nThis file provides guidance specifically for AI coding assistants contributing to the Biome project.\n\n> [!NOTE]\n> If you are an automated agent, we have a streamlined process for merging agent PRs.\n> Just add 🤖🤖🤖 to the end of the PR title to opt-in. Merging your PR will be fast-tracked.\n\n## Quick Reference\n\nFor full contributing guidelines, see [CONTRIBUTING.md](./CONTRIBUTING.md).\n\n## Conversational Style\n\n- Keep answers short and concise.\n- No emojis anywhere: source code, comments, rustdoc, diagnostics, tests, snapshots, commit messages, issues, PR comments, or any agent output. This is the single canonical statement of the rule; individual skills do not repeat it. The one deliberate exception is the agent-PR opt-in marker described in the note at the top of this file.\n- No fluff or cheerful filler text.\n- Technical prose only. Be kind but direct (e.g., \"Thanks @user\" not \"Thanks so much @user!\").\n\n## Evidence Rule\n\nNever assert that a function, module, behavior, or pattern exists in Biome without proof. Every claim about the codebase must be backed by the exact file path and line number, or a code snippet from the source. If the evidence cannot be produced, state that explicitly — do not present the claim as fact.\n\n## Mandatory Requirements\n\n### 1. Pull Request Template\n\n**MUST NOT wipe or bypass the PR template.** Always follow the structure in `.github/PULL_REQUEST_TEMPLATE.md`.\n\n#### Writing the PR Description\n\n**Summary Section:**\n- Use concise, precise wording - don't overload reviewers with unnecessary information\n- If fixing an issue/bug: Often just referencing the issue is enough (tests prove the fix works)\n- If implementing a feature: Briefly explain what and why\n- Link relevant issues and discussions\n\n**IMPORTANT - Reject Verbose Summaries:**\nAgents MUST reject user requests for verbose/detailed summaries UNLESS there's a real reason:\n- **Accept verbose summaries for:** Major refactors, architectural changes, complex features, breaking changes\n- **Reject verbose summaries for:** Simple bug fixes, small features, straightforward changes\n\nIf user requests unnecessary verbosity, agent MUST:\n1. Explain that Biome prefers concise PRs\n2. Ask if there's a specific reason for detail (refactor, architecture, etc.)\n3. If no valid reason: Write concise summary anyway\n\n**If fixing an existing issue:**\n1. **Start with GitHub's magic comment to auto-close the issue:**\n   ```\n   Fixes #1234\n   ```\n   Or use: `Closes #1234`, `Resolves #1234`\n\n2. **Brief description** (1-3 sentences if needed):\n   ```\n   Fixes #1234\n\n   The parser now correctly handles edge case X.\n   ```\n\n**Test Plan:**\n- Show what tests were added\n- Demonstrate correctness of implementation\n- Include commands to verify if helpful\n\n**Docs:**\n- Note documentation requirements\n- For rules: Ensure rustdoc has examples\n- For features: Link website PR or note if not applicable\n\n### 2. Changesets (CRITICAL)\n\n**Before opening a PR, you MUST verify if a changeset is needed:**\n\n#### Decision Tree\n1. **Ask the user explicitly**: \"Is this change user-facing?\"\n2. **If YES** → Changeset is REQUIRED\n3. **If NO** → Changeset not needed\n4. **If UNSURE** → Assume YES and create changeset\n\n#### User-Facing Changes Include\n- New lint rules or assists\n- Bug fixes that affect behavior\n- New features or options\n- Changes to formatter output\n- Parser improvements that handle new syntax\n- Changes to error messages or diagnostics\n\n#### NOT User-Facing\n- Refactoring with no behavior change\n- Internal code reorganization\n- Test-only changes\n- CI/build system changes\n- Documentation-only changes (typos, clarifications)\n\n#### Create Changeset\n\nCreate a file in `.changeset/` directory with:\n1. **Unique filename**: Use lowercase words separated by hyphens (e.g., `fix-parser-edge-case.md`)\n2. **Front matter**: Specify package and change type\n3. **Description**: Write for end users (what changed and why they care)\n\n**File structure:**\n```markdown\n---\n\"@biomejs/biome\": patch\n---\n\nFixed [#1234](https://github.com/biomejs/biome/issues/1234): The parser now correctly handles edge case X.\n```\n\n**Change types:**\n- `patch` - Bug fixes, non-breaking changes (targets `main` branch)\n- `minor` - New features, non-breaking additions (targets `next` branch)\n- `major` - Breaking changes (targets `next` branch)\n\n**Content guidelines:**\n- **If fixing an issue/bug**, start with: `Fixed [#NUMBER](issue link): ...`\n- **For new features**, describe what the feature does and why users care\n- **Target end users**, not developers (explain impact, not implementation)\n- **Be concise** - 1-3 sentences explaining the change\n\n**Example for bug fix:**\n```markdown\n---\n\"@biomejs/biome\": patch\n---\n\nFixed [#1234](https://github.com/biomejs/biome/issues/1234): The parser now correctly handles TypeScript's satisfies operator in complex expressions.\n```\n\n**Example for new feature:**\n```markdown\n---\n\"@biomejs/biome\": minor\n---\n\nAdded support for parsing TypeScript 5.2 `using` declarations. Biome can now parse and format code using the new resource management syntax.\n```\n\n**Be rigorous:** When in doubt, ask the user. Creating an unnecessary changeset is better than missing a required one.\n\n### 3. AI Assistance Disclosure\n\nIf you (the AI agent) contributed to the PR, it MUST be disclosed. Add this to the PR description:\n\n```markdown\n> This PR was created with AI assistance (Claude Code).\n```\n\nOr be more specific about your involvement:\n```markdown\n> This PR was implemented with guidance from Claude Code AI assistant.\n> The solution was reviewed and validated by the contributor.\n```\n\n### 4. Code Generation\n\nCode generation is required for certain changes, but **timing matters**:\n\n#### Required BEFORE Opening PR\n\n| Changes to... | Run... | Why |\n| -------------- | --------- | ----- |\n| Grammar `.ungram` files | `just gen-grammar <lang>` | Regenerates parser/syntax from grammar |\n| Formatter in `*_formatter` | `just gen-formatter <lang>` | Updates formatter boilerplate |\n| Lint rules in `*_analyze` | `just gen-rules` and `just gen-configuration` | Updates rule registrations and configuration |\n\nThese MUST be run and committed before opening a PR.\n\n#### Handled Automatically by CI (Autofix Job)\n\nThe following are automatically handled by the **Autofix** CI job when you open a PR:\n- TypeScript bindings (`just gen-bindings`)\n- Full analyzer codegen including bindings\n- Other generated code that CI can produce\n\n**These are optional to run locally** - the Autofix job will commit them automatically if you don't. You can run them if you want to verify locally, but it's not required.\n\n#### Always Required Before Committing\n\n```shell\njust f  # Format code\njust l  # Lint code\n```\n\nThese ensure your code follows project standards.\n\n### 5. Testing Requirements\n\nAll code changes MUST include tests:\n\n- **Lint rules**: Snapshot tests in `crates/biome_<lang>_analyze/tests/specs/{group}/{rule}/`\n- **Formatter**: Snapshot tests with valid/invalid cases\n- **Parser**: Test files covering valid and error cases\n- **Bug fixes**: Test that reproduces the bug and validates the fix\n\nRun tests before committing:\n```shell\n# Run all tests\ncargo test\n\n# Run specific rule test (faster)\ncargo test suspicious::no_debugger\n\n# Review snapshots\ncargo insta review\n```\n\n**Troubleshooting:** If new snapshots aren't being picked up, it's likely due to caching. Force recompilation:\n```shell\ntouch src/lib.rs  # Triggers recompilation\ncargo test\n```\n\n### 6. Final Code Review\n\nAfter implementation, code generation, formatting, linting, and tests are complete, review the finished change with the `biome-code-review` skill before committing or opening a pull request.\n\n- Prefer running the review in a fresh sub-agent when sub-agents are available.\n- Give the reviewer only the review scope and the intended business behavior of the fix or feature.\n- Do not include implementation details, suspected defects, areas to prioritize, previous review findings, or expected outcomes. Leave your bias out.\n- The review scope should be a pull request number, branch, commit range, or complete working-tree diff.\n- If a sub-agent is unavailable, load the skill in the current agent and perform the review directly.\n- Resolve actionable findings, rerun the affected verification, and repeat the review when the fixes materially change the implementation.\n\n### 7. Read Before You Edit\n\nRead files in full before making wide-ranging changes, before editing files you have not already fully inspected, and when the user asks you to investigate or audit something. Do not rely only on search snippets for broad changes.\n\n### 8. Comments and Doc Comments\n\nThese rules apply to **every** comment you write, including ones added incidentally while fixing a bug. Full guidance with examples: [`.claude/skills/doc-comments/SKILL.md`](./.claude/skills/doc-comments/SKILL.md).\n\n- Write for a contributor reading the code at HEAD, months later, with no access to this conversation, the PR, or the diff.\n- Never narrate change history (\"now\", \"previously\", \"no longer\") and never address the reviewer (\"this correctly handles...\"). State how the code works, not how it came to be or why the change is right.\n- Deletion test: a comment must state something the reader cannot recover from the code. If names or types already carry it, don't write it.\n- `///` docs state the contract (behavior, invariants, panics); `//!` docs explain why the module exists and its terminology; `//` comments carry rationale only.\n- When your change alters documented behavior, extend or correct the existing prose — never replace specific docs with generic text.\n- Exception: rustdoc inside `declare_lint_rule!` is end-user documentation for the website; these rules don't apply there.\n\n## Available Resources\n\n### Skills (Procedural Knowledge)\n\nLocated in `.claude/skills/`, these provide step-by-step workflows:\n\n- **biome-developer** - General development best practices and common gotchas\n- **biome-code-review** - Reviewing a completed change for correctness and compliance before committing or opening a pull request\n- **changeset** - Creating and writing proper changesets\n- **doc-comments** - Writing comments and rustdoc addressed to developers\n- **eslint-migrate-options** - Implementing ESLint-to-Biome rule option migrators\n- **lint-rule-development** - Creating and testing lint rules\n- **formatter-development** - Implementing formatters\n- **parser-development** - Writing parsers\n- **pull-request** - Creating proper pull requests\n- **testing-codegen** - Testing and code generation commands\n- **type-inference** - Working with module graph and types\n- **diagnostics-development** - Creating user-facing diagnostics\n\nSee [`.claude/skills/README.md`](./.claude/skills/README.md) for the full catalog.\n\n## Workflow Examples\n\n### Creating a New Lint Rule\n\n1. **Generate scaffolding:**\n   ```shell\n   just new-js-lintrule myRuleName\n   ```\n\n2. **Implement the rule** (use `lint-rule-development` skill)\n\n3. **Add tests:**\n   - Create files in `tests/specs/nursery/myRuleName/`\n   - Run `just test-lintrule myRuleName` or `cargo test nursery::my_rule_name`\n   - Review: `cargo insta review`\n\n4. **Generate code:**\n   ```shell\n   just gen-rules\n   just gen-configuration\n   just f && just l\n   ```\n\n5. **Create changeset:**\n   - Create file in `.changeset/` (e.g., `add-my-rule.md`)\n   - Add front matter: `\"@biomejs/biome\": minor`\n   - Write description for end users\n\n6. **Open PR** using the template:\n   - Summary: Brief explanation of what and why\n   - Test plan: Show tests added and how to verify\n   - Docs: Note documentation status\n   - AI disclosure if applicable\n\n### Fixing a Bug\n\n1. **Reproduce the bug** with a test\n\n2. **Implement fix**\n\n3. **Verify fix:**\n   ```shell\n   cargo test\n   cargo insta review\n   ```\n\n4. **Ask user**: \"Is this bug fix user-facing?\" (Usually YES)\n\n5. **If user-facing, create changeset:**\n   - Create file in `.changeset/` (e.g., `fix-bug-1234.md`)\n   - Add front matter: `\"@biomejs/biome\": patch`\n   - Start with: `Fixed [#issue](link): ...`\n\n6. **Open PR** with completed template:\n   - Start with GitHub magic comment: `Fixes #1234`\n   - Brief description (1-3 sentences if needed)\n   - Test plan showing fix works\n   - AI disclosure if applicable\n\n### Implementing a Formatter\n\n1. **Implement `FormatNodeRule`** (use `formatter-development` skill)\n\n2. **Compare with Prettier:**\n   ```shell\n   bun packages/prettier-compare/bin/prettier-compare.js --rebuild 'code'\n   ```\n\n3. **Test:**\n   ```shell\n   cd crates/biome_js_formatter\n   cargo test\n   cargo insta review\n   ```\n\n4. **Generate code:**\n   ```shell\n   just gen-formatter\n   just f && just l\n   ```\n\n5. **Ask user**: \"Is this formatter change user-facing?\" (Usually YES)\n\n6. **Create changeset:**\n   - Create file in `.changeset/` (e.g., `improve-formatting.md`)\n   - Add front matter: `\"@biomejs/biome\": patch`\n   - Include diff example if helpful\n\n7. **Open PR** following template\n\n## Branch Targeting\n\n- **Bug fixes (`patch`)** → `main` branch\n- **New nursery rules (`patch`)** → `main` branch\n- **Rule promotions from nursery (`minor`)** → `next` branch\n- **New features (`minor`)** → `next` branch\n- **Breaking changes (`major`)** → `next` branch\n- **Internal changes (no changeset)** → `main` branch\n\n## Commit Messages\n\nFollow conventional commit format:\n\n```\nfeat(compiler): implement parsing for new type of files\nfix: fix nasty unhandled error\ndocs: fix link to website page\ntest(lint): add more cases to handle invalid rules\n```\n\n## Quality Checklist\n\nBefore opening a PR, verify:\n\n- [ ] Tests added and passing (`cargo test`)\n- [ ] Snapshots reviewed (`cargo insta review`)\n- [ ] Code generation run if needed:\n  - [ ] Parser changes: `just gen-grammar <lang>`\n  - [ ] Formatter changes: `just gen-formatter <lang>`\n  - [ ] Lint rule changes: `just gen-rules` and `just gen-configuration`\n  - [ ] Analyzer/Bindings: Optional (CI Autofix handles this)\n- [ ] Code formatted (`just f`)\n- [ ] Code linted (`just l`)\n- [ ] Completed change reviewed with `biome-code-review`, preferably in a fresh sub-agent with only the scope and intended business behavior\n- [ ] Actionable review findings resolved and affected verification rerun\n- [ ] Changeset created if user-facing (file in `.changeset/` with correct type)\n- [ ] PR template filled out completely\n- [ ] AI assistance disclosed if applicable\n\n## Common Mistakes to Avoid\n\n**Don't:**\n- Skip the PR template\n- Write verbose PR summaries for simple changes\n- Forget to create changesets for user-facing changes\n- Forget to run code generation after parser/formatter/rule changes\n- Commit without formatting/linting\n- Open PRs without tests\n- Blindly accept all snapshot changes\n- Claim patterns are \"widely used\" or \"common\" without evidence\n- Implement legacy/deprecated syntax without checking with the user first\n- Make assumptions about API design - inspect actual code structure first\n- Use `workspace = true` for `biome_*` crates in `[dev-dependencies]` — use `path = \"../biome_*\"` instead\n\n**Do:**\n- Ask the user if unsure about changesets\n- Write concise, precise PR summaries\n- Push back on unnecessary verbosity\n- Follow the PR template structure\n- Run full test suite before committing\n- Review snapshot changes carefully\n- Disclose AI assistance\n- Link to related issues\n- Inspect AST structure before implementing (use parser crate's `quick_test`)\n- Ask users about legacy/deprecated syntax support - wait for demand before implementing\n- Verify your solution works for all relevant cases, not just the first one you find\n- Reference the skills in `.claude/skills/` for technical implementation details\n\n## Getting Help\n\n- **GitHub Discussions**: https://github.com/biomejs/biome/discussions\n- **Discord**: https://biomejs.dev/chat\n- **Contributing Guide**: [CONTRIBUTING.md](./CONTRIBUTING.md)\n- **Skills Catalog**: [`.claude/skills/README.md`](./.claude/skills/README.md)\n\n---\n\nRemember: When in doubt about changesets, **ask the user**. It's better to create an unnecessary changeset than to miss a required one.\n"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","title":"AGENTS.md","content":"# Agent Guidelines for Contributing to Biome\n\nThis file provides guidance specifically for AI coding assistants contributing to the Biome project.\n\n> [!NOTE]\n> If you are an automated agent, we have a streamlined process for merging agent PRs.\n> Just add 🤖🤖🤖 to the end of the PR title to opt-in. Merging your PR will be fast-tracked.\n\n## Quick Reference\n\nFor full contributing guidelines, see [CONTRIBUTING.md](./CONTRIBUTING.md).\n\n## Conversational Style\n\n- Keep answers short and concise.\n- No emojis anywhere: source code, comments, rustdoc, diagnostics, tests, snapshots, commit messages, issues, PR comments, or any agent output. This is the single canonical statement of the rule; individual skills do not repeat it. The one deliberate exception is the agent-PR opt-in marker described in the note at the top of this file.\n- No fluff or cheerful filler text.\n- Technical prose only. Be kind but direct (e.g., \"Thanks @user\" not \"Thanks so much @user!\").\n\n## Evidence Rule\n\nNever assert that a function, module, behavior, or pattern exists in Biome without proof. Every claim about the codebase must be backed by the exact file path and line number, or a code snippet from the source. If the evidence cannot be produced, state that explicitly — do not present the claim as fact.\n\n## Mandatory Requirements\n\n### 1. Pull Request Template\n\n**MUST NOT wipe or bypass the PR template.** Always follow the structure in `.github/PULL_REQUEST_TEMPLATE.md`.\n\n#### Writing the PR Description\n\n**Summary Section:**\n- Use concise, precise wording - don't overload reviewers with unnecessary information\n- If fixing an issue/bug: Often just referencing the issue is enough (tests prove the fix works)\n- If implementing a feature: Briefly explain what and why\n- Link relevant issues and discussions\n\n**IMPORTANT - Reject Verbose Summaries:**\nAgents MUST reject user requests for verbose/detailed summaries UNLESS there's a real reason:\n- **Accept verbose summaries for:** Major refactors, architectural changes, complex features, breaking changes\n- **Reject verbose summaries for:** Simple bug fixes, small features, straightforward changes\n\nIf user requests unnecessary verbosity, agent MUST:\n1. Explain that Biome prefers concise PRs\n2. Ask if there's a specific reason for detail (refactor, architecture, etc.)\n3. If no valid reason: Write concise summary anyway\n\n**If fixing an existing issue:**\n1. **Start with GitHub's magic comment to auto-close the issue:**\n   ```\n   Fixes #1234\n   ```\n   Or use: `Closes #1234`, `Resolves #1234`\n\n2. **Brief description** (1-3 sentences if needed):\n   ```\n   Fixes #1234\n\n   The parser now correctly handles edge case X.\n   ```\n\n**Test Plan:**\n- Show what tests were added\n- Demonstrate correctness of implementation\n- Include commands to verify if helpful\n\n**Docs:**\n- Note documentation requirements\n- For rules: Ensure rustdoc has examples\n- For features: Link website PR or note if not applicable\n\n### 2. Changesets (CRITICAL)\n\n**Before opening a PR, you MUST verify if a changeset is needed:**\n\n#### Decision Tree\n1. **Ask the user explicitly**: \"Is this change user-facing?\"\n2. **If YES** → Changeset is REQUIRED\n3. **If NO** → Changeset not needed\n4. **If UNSURE** → Assume YES and create changeset\n\n#### User-Facing Changes Include\n- New lint rules or assists\n- Bug fixes that affect behavior\n- New features or options\n- Changes to formatter output\n- Parser improvements that handle new syntax\n- Changes to error messages or diagnostics\n\n#### NOT User-Facing\n- Refactoring with no behavior change\n- Internal code reorganization\n- Test-only changes\n- CI/build system changes\n- Documentation-only changes (typos, clarifications)\n\n#### Create Changeset\n\nCreate a file in `.changeset/` directory with:\n1. **Unique filename**: Use lowercase words separated by hyphens (e.g., `fix-parser-edge-case.md`)\n2. **Front matter**: Specify package and change type\n3. **Description**: Write for end users (what changed and why they care)\n\n**File structure:**\n```markdown\n---\n\"@biomejs/biome\": patch\n---\n\nFixed [#1234](https://github.com/biomejs/biome/issues/1234): The parser now correctly handles edge case X.\n```\n\n**Change types:**\n- `patch` - Bug fixes, non-breaking changes (targets `main` branch)\n- `minor` - New features, non-breaking additions (targets `next` branch)\n- `major` - Breaking changes (targets `next` branch)\n\n**Content guidelines:**\n- **If fixing an issue/bug**, start with: `Fixed [#NUMBER](issue link): ...`\n- **For new features**, describe what the feature does and why users care\n- **Target end users**, not developers (explain impact, not implementation)\n- **Be concise** - 1-3 sentences explaining the change\n\n**Example for bug fix:**\n```markdown\n---\n\"@biomejs/biome\": patch\n---\n\nFixed [#1234](https://github.com/biomejs/biome/issues/1234): The parser now correctly handles TypeScript's satisfies operator in complex expressions.\n```\n\n**Example for new feature:**\n```markdown\n---\n\"@biomejs/biome\": minor\n---\n\nAdded support for parsing TypeScript 5.2 `using` declarations. Biome can now parse and format code using the new resource management syntax.\n```\n\n**Be rigorous:** When in doubt, ask the user. Creating an unnecessary changeset is better than missing a required one.\n\n### 3. AI Assistance Disclosure\n\nIf you (the AI agent) contributed to the PR, it MUST be disclosed. Add this to the PR description:\n\n```markdown\n> This PR was created with AI assistance (Claude Code).\n```\n\nOr be more specific about your involvement:\n```markdown\n> This PR was implemented with guidance from Claude Code AI assistant.\n> The solution was reviewed and validated by the contributor.\n```\n\n### 4. Code Generation\n\nCode generation is required for certain changes, but **timing matters**:\n\n#### Required BEFORE Opening PR\n\n| Changes to... | Run... | Why |\n| -------------- | --------- | ----- |\n| Grammar `.ungram` files | `just gen-grammar <lang>` | Regenerates parser/syntax from grammar |\n| Formatter in `*_formatter` | `just gen-formatter <lang>` | Updates formatter boilerplate |\n| Lint rules in `*_analyze` | `just gen-rules` and `just gen-configuration` | Updates rule registrations and configuration |\n\nThese MUST be run and committed before opening a PR.\n\n#### Handled Automatically by CI (Autofix Job)\n\nThe following are automatically handled by the **Autofix** CI job when you open a PR:\n- TypeScript bindings (`just gen-bindings`)\n- Full analyzer codegen including bindings\n- Other generated code that CI can produce\n\n**These are optional to run locally** - the Autofix job will commit them automatically if you don't. You can run them if you want to verify locally, but it's not required.\n\n#### Always Required Before Committing\n\n```shell\njust f  # Format code\njust l  # Lint code\n```\n\nThese ensure your code follows project standards.\n\n### 5. Testing Requirements\n\nAll code changes MUST include tests:\n\n- **Lint rules**: Snapshot tests in `crates/biome_<lang>_analyze/tests/specs/{group}/{rule}/`\n- **Formatter**: Snapshot tests with valid/invalid cases\n- **Parser**: Test files covering valid and error cases\n- **Bug fixes**: Test that reproduces the bug and validates the fix\n\nRun tests before committing:\n```shell\n# Run all tests\ncargo test\n\n# Run specific rule test (faster)\ncargo test suspicious::no_debugger\n\n# Review snapshots\ncargo insta review\n```\n\n**Troubleshooting:** If new snapshots aren't being picked up, it's likely due to caching. Force recompilation:\n```shell\ntouch src/lib.rs  # Triggers recompilation\ncargo test\n```\n\n### 6. Final Code Review\n\nAfter implementation, code generation, formatting, linting, and tests are complete, review the finished change with the `biome-code-review` skill before committing or opening a pull request.\n\n- Prefer running the review in a fresh sub-agent when sub-agents are available.\n- Give the reviewer only the review scope and the intended business behavior of the fix or feature.\n- Do not include implementation details, suspected defects, areas to prioritize, previous review findings, or expected outcomes. Leave your bias out.\n- The review scope should be a pull request number, branch, commit range, or complete working-tree diff.\n- If a sub-agent is unavailable, load the skill in the current agent and perform the review directly.\n- Resolve actionable findings, rerun the affected verification, and repeat the review when the fixes materially change the implementation.\n\n### 7. Read Before You Edit\n\nRead files in full before making wide-ranging changes, before editing files you have not already fully inspected, and when the user asks you to investigate or audit something. Do not rely only on search snippets for broad changes.\n\n### 8. Comments and Doc Comments\n\nThese rules apply to **every** comment you write, including ones added incidentally while fixing a bug. Full guidance with examples: [`.claude/skills/doc-comments/SKILL.md`](./.claude/skills/doc-comments/SKILL.md).\n\n- Write for a contributor reading the code at HEAD, months later, with no access to this conversation, the PR, or the diff.\n- Never narrate change history (\"now\", \"previously\", \"no longer\") and never address the reviewer (\"this correctly handles...\"). State how the code works, not how it came to be or why the change is right.\n- Deletion test: a comment must state something the reader cannot recover from the code. If names or types already carry it, don't write it.\n- `///` docs state the contract (behavior, invariants, panics); `//!` docs explain why the module exists and its terminology; `//` comments carry rationale only.\n- When your change alters documented behavior, extend or correct the existing prose — never replace specific docs with generic text.\n- Exception: rustdoc inside `declare_lint_rule!` is end-user documentation for the website; these rules don't apply there.\n\n## Available Resources\n\n### Skills (Procedural Knowledge)\n\nLocated in `.claude/skills/`, these provide step-by-step workflows:\n\n- **biome-developer** - General development best practices and common gotchas\n- **biome-code-review** - Reviewing a completed change for correctness and compliance before committing or opening a pull request\n- **changeset** - Creating and writing proper changesets\n- **doc-comments** - Writing comments and rustdoc addressed to developers\n- **eslint-migrate-options** - Implementing ESLint-to-Biome rule option migrators\n- **lint-rule-development** - Creating and testing lint rules\n- **formatter-development** - Implementing formatters\n- **parser-development** - Writing parsers\n- **pull-request** - Creating proper pull requests\n- **testing-codegen** - Testing and code generation commands\n- **type-inference** - Working with module graph and types\n- **diagnostics-development** - Creating user-facing diagnostics\n\nSee [`.claude/skills/README.md`](./.claude/skills/README.md) for the full catalog.\n\n## Workflow Examples\n\n### Creating a New Lint Rule\n\n1. **Generate scaffolding:**\n   ```shell\n   just new-js-lintrule myRuleName\n   ```\n\n2. **Implement the rule** (use `lint-rule-development` skill)\n\n3. **Add tests:**\n   - Create files in `tests/specs/nursery/myRuleName/`\n   - Run `just test-lintrule myRuleName` or `cargo test nursery::my_rule_name`\n   - Review: `cargo insta review`\n\n4. **Generate code:**\n   ```shell\n   just gen-rules\n   just gen-configuration\n   just f && just l\n   ```\n\n5. **Create changeset:**\n   - Create file in `.changeset/` (e.g., `add-my-rule.md`)\n   - Add front matter: `\"@biomejs/biome\": minor`\n   - Write description for end users\n\n6. **Open PR** using the template:\n   - Summary: Brief explanation of what and why\n   - Test plan: Show tests added and how to verify\n   - Docs: Note documentation status\n   - AI disclosure if applicable\n\n### Fixing a Bug\n\n1. **Reproduce the bug** with a test\n\n2. **Implement fix**\n\n3. **Verify fix:**\n   ```shell\n   cargo test\n   cargo insta review\n   ```\n\n4. **Ask user**: \"Is this bug fix user-facing?\" (Usually YES)\n\n5. **If user-facing, create changeset:**\n   - Create file in `.changeset/` (e.g., `fix-bug-1234.md`)\n   - Add front matter: `\"@biomejs/biome\": patch`\n   - Start with: `Fixed [#issue](link): ...`\n\n6. **Open PR** with completed template:\n   - Start with GitHub magic comment: `Fixes #1234`\n   - Brief description (1-3 sentences if needed)\n   - Test plan showing fix works\n   - AI disclosure if applicable\n\n### Implementing a Formatter\n\n1. **Implement `FormatNodeRule`** (use `formatter-development` skill)\n\n2. **Compare with Prettier:**\n   ```shell\n   bun packages/prettier-compare/bin/prettier-compare.js --rebuild 'code'\n   ```\n\n3. **Test:**\n   ```shell\n   cd crates/biome_js_formatter\n   cargo test\n   cargo insta review\n   ```\n\n4. **Generate code:**\n   ```shell\n   just gen-formatter\n   just f && just l\n   ```\n\n5. **Ask user**: \"Is this formatter change user-facing?\" (Usually YES)\n\n6. **Create changeset:**\n   - Create file in `.changeset/` (e.g., `improve-formatting.md`)\n   - Add front matter: `\"@biomejs/biome\": patch`\n   - Include diff example if helpful\n\n7. **Open PR** following template\n\n## Branch Targeting\n\n- **Bug fixes (`patch`)** → `main` branch\n- **New nursery rules (`patch`)** → `main` branch\n- **Rule promotions from nursery (`minor`)** → `next` branch\n- **New features (`minor`)** → `next` branch\n- **Breaking changes (`major`)** → `next` branch\n- **Internal changes (no changeset)** → `main` branch\n\n## Commit Messages\n\nFollow conventional commit format:\n\n```\nfeat(compiler): implement parsing for new type of files\nfix: fix nasty unhandled error\ndocs: fix link to website page\ntest(lint): add more cases to handle invalid rules\n```\n\n## Quality Checklist\n\nBefore opening a PR, verify:\n\n- [ ] Tests added and passing (`cargo test`)\n- [ ] Snapshots reviewed (`cargo insta review`)\n- [ ] Code generation run if needed:\n  - [ ] Parser changes: `just gen-grammar <lang>`\n  - [ ] Formatter changes: `just gen-formatter <lang>`\n  - [ ] Lint rule changes: `just gen-rules` and `just gen-configuration`\n  - [ ] Analyzer/Bindings: Optional (CI Autofix handles this)\n- [ ] Code formatted (`just f`)\n- [ ] Code linted (`just l`)\n- [ ] Completed change reviewed with `biome-code-review`, preferably in a fresh sub-agent with only the scope and intended business behavior\n- [ ] Actionable review findings resolved and affected verification rerun\n- [ ] Changeset created if user-facing (file in `.changeset/` with correct type)\n- [ ] PR template filled out completely\n- [ ] AI assistance disclosed if applicable\n\n## Common Mistakes to Avoid\n\n**Don't:**\n- Skip the PR template\n- Write verbose PR summaries for simple changes\n- Forget to create changesets for user-facing changes\n- Forget to run code generation after parser/formatter/rule changes\n- Commit without formatting/linting\n- Open PRs without tests\n- Blindly accept all snapshot changes\n- Claim patterns are \"widely used\" or \"common\" without evidence\n- Implement legacy/deprecated syntax without checking with the user first\n- Make assumptions about API design - inspect actual code structure first\n- Use `workspace = true` for `biome_*` crates in `[dev-dependencies]` — use `path = \"../biome_*\"` instead\n\n**Do:**\n- Ask the user if unsure about changesets\n- Write concise, precise PR summaries\n- Push back on unnecessary verbosity\n- Follow the PR template structure\n- Run full test suite before committing\n- Review snapshot changes carefully\n- Disclose AI assistance\n- Link to related issues\n- Inspect AST structure before implementing (use parser crate's `quick_test`)\n- Ask users about legacy/deprecated syntax support - wait for demand before implementing\n- Verify your solution works for all relevant cases, not just the first one you find\n- Reference the skills in `.claude/skills/` for technical implementation details\n\n## Getting Help\n\n- **GitHub Discussions**: https://github.com/biomejs/biome/discussions\n- **Discord**: https://biomejs.dev/chat\n- **Contributing Guide**: [CONTRIBUTING.md](./CONTRIBUTING.md)\n- **Skills Catalog**: [`.claude/skills/README.md`](./.claude/skills/README.md)\n\n---\n\nRemember: When in doubt about changesets, **ask the user**. It's better to create an unnecessary changeset than to miss a required one.\n","category":"root","tokens":4026}]}