Biome 1.9 Configuration Inheritance, VCS Integration, and Suppression Standards

--- description: Biome 1.9 Configuration Inheritance, VCS Integration, and Suppression Standards - Enforces strict configuration architecture in Biome 1.9 setups, ensuring deterministic monorepo inheritance via 'extends', native VCS-aware formatting and linting, and exact suppression comment syntax with explicit justifications. Prevents configuration drift, unformatted git diff pollution, and non-actionable suppression debt across polyrepo and monorepo environments. globs: biome.json, biome.jsonc, **/.biome.json, package.json, src/**/*.{ts,tsx,js,jsx,json,css} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/biome-vcs-deterministic-suppression-guardrail" --- # Biome 1.9 Configuration Inheritance, VCS Integration, and Suppression Standards > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Ad-Hoc Suppressions Without Explanation, Git-Unaware Lint Runs, and Fragmented Non-Inherited Biome Configurations ## System Constraints You are a Principal Engineer enforcing strict adherence to Biome 1.9 single-binary linter and formatter architecture. Mandate absolute invariants around configuration inheritance, native git/vcs integration to avoid uncommitted file scans, and deterministic suppression syntax containing explicit human-readable justifications. ## Strict Guidelines - Projects MUST define root configuration within 'biome.json' or 'biome.jsonc' and mandate package-level overrides use the 'extends' array with relative POSIX paths. - Root 'biome.json' MUST configure the 'vcs' block enabling git integration ('vcs.enabled: true', 'vcs.clientKind: "git"', 'vcs.useIgnoreFile: true') to natively honor .gitignore and avoid formatting build artifacts. - Engineers MUST NOT use generic or comment-less suppression annotations; suppressions MUST strictly use the canonical format: '// biome-ignore <category>/<ruleName>: <mandatory justification explanation>'. - Engineers MUST NEVER use ESLint, Prettier, or legacy lint comments (e.g., '// eslint-disable-next-line') in repositories governed by Biome 1.9. - CI/CD and pre-commit checks MUST execute 'biome check --write' with '--staged' or '--changed' flags to leverage VCS integration deterministically. - Suppression directives MUST NEVER disable entire categories (e.g., '// biome-ignore lint'); each suppression MUST target exactly one explicit leaf rule per occurrence. ## Bad vs Good Implementations ### Biome Configuration Hierarchy and VCS Integration #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Fails to configure native VCS integration, forcing redundant and brittle manual file-ignore lists that drift from .gitignore, and omits formatter and organizeImports configurations. ```json { "$schema": "https://biomejs.dev/schemas/1.9.4/schema.json", "files": { "ignore": ["dist", "node_modules", ".next"] }, "linter": { "enabled": true } } ``` #### Production Standard (Correct) > **Standard**: Correctly enables Biome's native VCS client to respect .gitignore, sets deterministic formatting and import organization, and establishes the baseline schema for inheritance. ```json { "$schema": "https://biomejs.dev/schemas/1.9.4/schema.json", "vcs": { "enabled": true, "clientKind": "git", "useIgnoreFile": true, "defaultBranch": "main" }, "organizeImports": { "enabled": true }, "linter": { "enabled": true, "rules": { "recommended": true } }, "formatter": { "enabled": true, "indentStyle": "space", "indentWidth": 2 } } ``` ### Deterministic Rule Suppression Syntax #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Mixes obsolete ESLint suppressions into a Biome codebase and uses a broad category-level suppression ('biome-ignore lint') without targeting the specific rule and lacking technical justification. ```typescript // eslint-disable-next-line @typescript-eslint/no-explicit-any export function deserializePayload(input: string): any { // biome-ignore lint: needed for dynamic parse return JSON.parse(input); } ``` #### Production Standard (Correct) > **Standard**: Uses canonical Biome 1.9 suppression syntax targeting the exact leaf rule ('lint/suspicious/noExplicitAny') accompanied by an mandatory, clear explanation for why the invariant is bypassed. ```typescript export function deserializePayload(input: string): unknown { // biome-ignore lint/suspicious/noExplicitAny: external third-party boundary lacks guaranteed schema const raw: any = JSON.parse(input); return raw; } ```

Architectural Specification & Invariant Rationale

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

Biome 1.9 Configuration Inheritance, VCS Integration, and Suppression Standards defines an industrial-grade behavioral standard for frontend engineering. Enforces strict configuration architecture in Biome 1.9 setups, ensuring deterministic monorepo inheritance via 'extends', native VCS-aware formatting and linting, and exact suppression comment syntax with explicit justifications. Prevents configuration drift, unformatted git diff pollution, and non-actionable suppression debt across polyrepo and monorepo environments. 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: Ad-Hoc Suppressions Without Explanation, Git-Unaware Lint Runs, and Fragmented Non-Inherited Biome Configurations 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	Ad-Hoc Suppressions Without Explanation, Git-Unaware Lint Runs, and Fragmented Non-Inherited Biome Configurations	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:

Projects MUST define root configuration within 'biome.json' or 'biome.jsonc' and mandate package-level overrides use the 'extends' array with relative POSIX paths.

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.