Biome 1.9 Configuration Inheritance, VCS Integration, and Suppression Guardrail

--- description: Biome 1.9 Configuration Inheritance, VCS Integration, and Suppression Guardrail - Enforces strict Biome 1.9 single-binary formatting and linting standards across frontend and monorepo codebases. Requires unified VCS ignore synchronization to prevent CI/local drift and mandates deterministic rule suppressions with mandatory justification reasons. Prohibits legacy ESLint/Prettier directive bleed and ensures deterministic configuration inheritance. globs: biome.json, biome.jsonc, src/**/*.{ts,tsx,js,jsx}, **/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/biome-configuration-vcs-and-suppression-standards" --- # Biome 1.9 Configuration Inheritance, VCS Integration, and Suppression Guardrail > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Deploying unanchored ignore comments without explanations, lingering ESLint directives, or uncoupled VCS ignore configs in Biome environments. ## System Constraints You are a Principal Software Architect enforcing Biome 1.9 standards. Mandate single-binary linter/formatter invariants: ensure all suppressions follow strict `// biome-ignore <group>/<rule>: <explanation>` syntax, verify VCS integration is anchored to `.gitignore`, and guarantee monorepo configurations inherit cleanly via `extends`. ## Strict Guidelines - Engineers MUST ALWAYS format inline rule suppressions using strict Biome syntax including a group, rule name, and trailing explanation: `// biome-ignore <group>/<rule>: <explanation>`. - Engineers MUST NOT retain legacy ESLint (`eslint-disable*`), TSLint, or Prettier (`prettier-ignore`) suppression comments in repositories managed by Biome. - Root `biome.json` configurations MUST explicitly configure `vcs` integration (`clientKind: "git"`, `enabled: true`, `useIgnoreFile: true`) to prevent scanning ignored artifacts. - Monorepo package sub-configurations MUST inherit common rules using the `"extends": ["..."]` array and only declare scoped overrides. - Suppressions MUST NEVER target entire rule groups (e.g., `// biome-ignore lint: reason`); individual, deterministic rule names must be declared. - Inline suppressions MUST immediately precede the offending AST node or declaration without intervening blank lines. ## Bad vs Good Implementations ### Rule Suppression Syntax and In-Line Justifications #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Uses an obsolete ESLint directive that Biome ignores, and includes a Biome ignore directive lacking the mandatory trailing explanation justifying the override. ```typescript // eslint-disable-next-line @typescript-eslint/no-explicit-any export function deserializePayload(rawInput: string): any { // biome-ignore lint/suspicious/noDoubleEquals if (rawInput == null) { return null; } return JSON.parse(rawInput); } ``` #### Production Standard (Correct) > **Standard**: Adheres to the Biome 1.9 suppression standard with full group/rule paths and mandatory human-readable justifications. ```typescript // biome-ignore lint/suspicious/noExplicitAny: Legacy untyped webhook payload requires any until schema migration completes export function deserializePayload(rawInput: string): any { // biome-ignore lint/suspicious/noDoubleEquals: Loose null check intentionally matches both null and undefined if (rawInput == null) { return null; } return JSON.parse(rawInput); } ``` ### Deterministic Biome Configuration with VCS and Monorepo Inheritance #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Fails to leverage native VCS ignore file integration, causing CI/CLI drift and unnecessary manual tracking of build artifacts. ```typescript // Simulated biome.json configuration anti-pattern const badBiomeConfig = { "$schema": "https://biomejs.dev/schemas/1.9.0/schema.json", "files": { // Anti-pattern: Manual duplicate ignore lists drift out of sync with .gitignore "ignore": ["node_modules", "dist", ".next", "coverage"] }, "linter": { "enabled": true, "rules": { "recommended": true } } }; ``` #### Production Standard (Correct) > **Standard**: Enables native git integration to honor `.gitignore` deterministically and sets explicit formatter and linter rules. ```typescript // Simulated root biome.json configuration production standard const goodBiomeConfig = { "$schema": "https://biomejs.dev/schemas/1.9.0/schema.json", "vcs": { "enabled": true, "clientKind": "git", "useIgnoreFile": true, "defaultBranch": "main" }, "formatter": { "enabled": true, "formatWithErrors": false, "indentStyle": "space", "indentWidth": 2 }, "linter": { "enabled": true, "rules": { "recommended": true, "suspicious": { "noExplicitAny": "error" } } } }; ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Biome 1.9 Configuration Inheritance, VCS Integration, and Suppression Guardrail

Biome 1.9 Configuration Inheritance, VCS Integration, and Suppression Guardrail defines an industrial-grade behavioral standard for frontend engineering. Enforces strict Biome 1.9 single-binary formatting and linting standards across frontend and monorepo codebases. Requires unified VCS ignore synchronization to prevent CI/local drift and mandates deterministic rule suppressions with mandatory justification reasons. Prohibits legacy ESLint/Prettier directive bleed and ensures deterministic configuration inheritance. Modern software architectures require strict adherence to deterministic patterns to guarantee high availability, maintainability, and zero security vulnerabilities.

Framework Paradigm Shift & Drift MechanicsLLMs are trained on millions of open-source repositories containing outdated code, legacy idioms, and unpatched antipatterns. When coding assistants generate implementations for this stack, they default to common statistical tokens: Deploying unanchored ignore comments without explanations, lingering ESLint directives, or uncoupled VCS ignore configs in Biome environments. Without an explicit system instruction file, developers spend hours debugging silent failures.

Failure Modes & Production Blast Radius

Hazard Analysis: What Breaks Without This Rule

The following failure modes have been cataloged from hundreds of hours of production code reviews where AI assistants produced non-compliant implementations:

Failure Mode	AI Symptom (The Anti-Pattern)	Severity	Production Impact & Remedy
AI Hallucination & Deprecation Drift	Deploying unanchored ignore comments without explanations, lingering ESLint directives, or uncoupled VCS ignore configs in Biome environments.	Critical	Violating this industrial standard introduces regression bugs, security risks, and unexpected runtime failures in production. Enforce explicit behavioral system directives across all AI coding assistants in your repository.
Silent Architecture Inconsistency	AI assistants produce mixed paradigms across files, creating fragmented codebase conventions.	Medium	Increases cognitive load during code reviews and leads to maintenance debt across engineering teams. Pin project conventions in .cursor/rules, CLAUDE.md, and AGENTS.md so all team agents follow identical guardrails.

Architectural Directives in Detail

Step-by-Step Production Directives

Each rule constraint below is injected into the AI agent's system prompt to establish deterministic boundaries:

Engineers MUST ALWAYS format inline rule suppressions using strict Biome syntax including a group, rule name, and trailing explanation

Engineers MUST ALWAYS format inline rule suppressions using strict Biome syntax including a group, rule name, and trailing explanation: `// biome-ignore <group>/<rule>: <explanation>`.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.