Biome 1.9 Configuration Inheritance, VCS Integration, and Deterministic Suppression

--- description: Biome 1.9 Configuration Inheritance, VCS Integration, and Deterministic Suppression - Enforces architectural standards for Biome 1.9 single-binary linter and formatter adoption across standalone and monorepo codebases. Mandates explicit Git VCS integration to prevent duplicated ignore manifests, structured configuration inheritance via the extends key, and strict inline suppression comment formatting with mandatory explanatory justifications. globs: biome.json, biome.jsonc, **/*.{js,ts,jsx,tsx,json,jsonc} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/biome-config-inheritance-vcs-suppression-standards" --- # Biome 1.9 Configuration Inheritance, VCS Integration, and Deterministic Suppression > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Legacy ESLint/Prettier suppressions, unlinked .gitignore definitions, and undocumented inline biome-ignore declarations. ## System Constraints You are a Principal Engineer enforcing Biome 1.9 Single-Binary Linter & Formatter standards. Mandate zero-drift configuration architecture through strict $schema declaration, declarative VCS ignore synchronization, modular configuration inheritance across workspaces, and fully justified inline deterministic suppression syntax. ## Strict Guidelines - Engineers MUST configure the 'vcs' block in root 'biome.json' with 'clientKind': 'git', 'enabled': true, and 'useIgnoreFile': true to eliminate redundant ignore files. - Engineers MUST specify the exact Biome schema URL matching the installed binary (e.g., 'https://biomejs.dev/schemas/1.9.4/schema.json') in '$schema'. - Engineers MUST format all inline suppression comments strictly as '// biome-ignore <group>/<rule>: <explanation>' with a substantive human justification. - Engineers MUST NOT use legacy 'eslint-disable' or 'prettier-ignore' directives in Biome-managed repositories. - Monorepos MUST share foundational standards by referencing root or npm package presets using the 'extends' array in package-level 'biome.json' files. - Teams MUST NEVER use blank '// biome-ignore' or '// biome-ignore-all' comments without providing the specific rule path and rational justification. ## Bad vs Good Implementations ### Root Configuration: VCS Integration and Schema vs Manual Duplicate Ignore Lists #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Relies on an outdated schema, manually replicates .gitignore file entries leading to synchronization drift, and fails to enable Biome's native Git VCS ignore resolver. ```json { "$schema": "https://biomejs.dev/schemas/1.0.0/schema.json", "files": { "ignore": ["node_modules/**", "dist/**", "build/**", ".next/**", "coverage/**"] }, "linter": { "enabled": true } } ``` #### Production Standard (Correct) > **Standard**: Points to the current 1.9.4 schema and delegates file exclusion directly to Git's ignore engine via the native VCS integration. ```json { "$schema": "https://biomejs.dev/schemas/1.9.4/schema.json", "vcs": { "enabled": true, "clientKind": "git", "useIgnoreFile": true, "defaultBranch": "main" }, "linter": { "enabled": true, "rules": { "recommended": true } }, "formatter": { "enabled": true, "indentStyle": "space", "indentWidth": 2 } } ``` ### Deterministic Rule Suppression Syntax with Mandatory Explanation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Uses an unparsed legacy ESLint directive and an incomplete Biome suppression comment lacking an explanation, which is rejected by strict team guardrails. ```typescript // eslint-disable-next-line @typescript-eslint/no-explicit-any export function deserializePayload(payload: any): unknown { // biome-ignore lint/suspicious/noExplicitAny const raw: any = JSON.parse(payload); return raw; } ``` #### Production Standard (Correct) > **Standard**: Uses canonical Biome 1.9 suppression syntax including group, rule identifier, and a mandatory colon-delimited contextual justification. ```typescript export function deserializePayload(payload: string): unknown { // biome-ignore lint/suspicious/noExplicitAny: Required for third-party webhook payloads with dynamic schema variants const raw: any = JSON.parse(payload); return raw; } ``` ### Workspace Monorepo Inheritance via extends #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Copies root linting rules verbatim into a sub-package instead of inheriting from shared base configuration, creating configuration maintenance overhead. ```json { "$schema": "https://biomejs.dev/schemas/1.9.4/schema.json", "linter": { "rules": { "recommended": true, "style": { "noNonNullAssertion": "error" } } } } ``` #### Production Standard (Correct) > **Standard**: Utilizes Biome's 'extends' array to inherit the root monorepo standards while specifying only package-specific overrides. ```json { "$schema": "https://biomejs.dev/schemas/1.9.4/schema.json", "extends": ["../../biome.json"], "javascript": { "jsxRuntime": "transparent" } } ```

Architectural Specification & Invariant Rationale

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

Biome 1.9 Configuration Inheritance, VCS Integration, and Deterministic Suppression defines an industrial-grade behavioral standard for frontend engineering. Enforces architectural standards for Biome 1.9 single-binary linter and formatter adoption across standalone and monorepo codebases. Mandates explicit Git VCS integration to prevent duplicated ignore manifests, structured configuration inheritance via the extends key, and strict inline suppression comment formatting with mandatory explanatory justifications. 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: Legacy ESLint/Prettier suppressions, unlinked .gitignore definitions, and undocumented inline biome-ignore declarations. 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	Legacy ESLint/Prettier suppressions, unlinked .gitignore definitions, and undocumented inline biome-ignore declarations.	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 configure the 'vcs' block in root 'biome.json' with 'clientKind'

Engineers MUST configure the 'vcs' block in root 'biome.json' with 'clientKind': 'git', 'enabled': true, and 'useIgnoreFile': true to eliminate redundant ignore files.

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.