Biome 1.9 Configuration Inheritance, Native VCS Filtering, and Deterministic Rule Suppression

--- description: Biome 1.9 Configuration Inheritance, Native VCS Filtering, and Deterministic Rule Suppression - Enforces strict Biome 1.9+ architectural standards across monorepos and frontend targets. Mandates deterministic configuration inheritance via canonical extends paths, native Git ignore integration using the VCS engine to eliminate dual-maintenance ignore lists, and syntax-compliant inline suppressions requiring fully-qualified rule names with human-readable rationale. globs: biome.json, biome.jsonc, **/*.{ts,tsx,js,jsx,json,jsonc} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/biome-vcs-inheritance-suppression-guardrail-production-standard" --- # Biome 1.9 Configuration Inheritance, Native VCS Filtering, and Deterministic Rule Suppression > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Fragmented ignore arrays, missing VCS integration, and ambiguous or ESLint-legacy inline suppressions that cause CI drift. ## System Constraints You are a Principal Software Architect enforcing Biome 1.9 single-binary linter and formatter standards. You must ensure configuration files utilize strict Biome 1.9 JSON schema definitions, resolve shared configurations deterministically using the 'extends' array, defer filesystem exclusions strictly to Biome's native VCS engine (vcs.useIgnoreFile: true), and prohibit obsolete ESLint/Prettier suppression comments or unreasoned Biome suppressions. ## Strict Guidelines - Engineers MUST ALWAYS enable Biome native VCS integration ('vcs.enabled': true, 'vcs.clientKind': 'git', 'vcs.useIgnoreFile': true) instead of duplicating patterns in 'files.ignore'. - Engineers MUST ALWAYS provide a fully qualified rule name and an explicit rationale comment when suppressing a rule: '// biome-ignore <group>/<rule>: <explanation>'. - Engineers MUST NOT use legacy suppression comments (e.g., '// eslint-disable', '// @ts-ignore' for linting, or '/* prettier-ignore */') under Biome-managed toolchains. - Engineers MUST NOT specify bare '// biome-ignore' directives without specifying the explicit lint rule and a descriptive justification. - Configurations MUST extend shared packages via relative paths or package exports declared in 'extends' rather than replicating linting and formatting rules across subpackages. - Workspaces SHOULD anchor '$schema' to the exact minor version (e.g., 'https://biomejs.dev/schemas/1.9.4/schema.json') to ensure strict IDE validation and schema integrity. ## Bad vs Good Implementations ### Biome 1.9 Configuration Inheritance & VCS Integration #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Omits 'vcs' integration, requiring manual duplicate synchronization with .gitignore. Lacks configuration inheritance from root/shared presets, leading to fragmented linter rules across workspace packages. ```json { "$schema": "https://biomejs.dev/schemas/1.9.4/schema.json", "files": { "ignore": ["node_modules/**", "dist/**", "build/**", ".turbo/**"] }, "linter": { "enabled": true } } ``` #### Production Standard (Correct) > **Standard**: Extends shared corporate base configuration, delegates ignore filtering directly to the Git layer via 'vcs.useIgnoreFile', and uses 'ignoreUnknown' to prevent processing unsupported file extensions. ```json { "$schema": "https://biomejs.dev/schemas/1.9.4/schema.json", "extends": ["@acme/biome-config/base"], "vcs": { "enabled": true, "clientKind": "git", "useIgnoreFile": true, "defaultBranch": "main" }, "files": { "ignoreUnknown": true } } ``` ### Deterministic Rule Suppression Syntax #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Uses obsolete ESLint suppression comments which Biome ignores, and utilizes an illegal bare '// biome-ignore' directive missing both the target rule and mandatory explanation rationale. ```typescript // eslint-disable-next-line @typescript-eslint/no-explicit-any export function deserializePayload(input: string): any { // biome-ignore return JSON.parse(input); } ``` #### Production Standard (Correct) > **Standard**: Uses Biome 1.9 compliant suppression syntax specifying the full group ('lint/suspicious'), rule identifier ('noExplicitAny'), and a colon-separated mandatory rationale. ```typescript // biome-ignore lint/suspicious/noExplicitAny: Required for boundary deserialization before schema validation export function deserializePayload(input: string): any { return JSON.parse(input); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Biome 1.9 Configuration Inheritance, Native VCS Filtering, and Deterministic Rule Suppression

Biome 1.9 Configuration Inheritance, Native VCS Filtering, and Deterministic Rule Suppression defines an industrial-grade behavioral standard for frontend engineering. Enforces strict Biome 1.9+ architectural standards across monorepos and frontend targets. Mandates deterministic configuration inheritance via canonical extends paths, native Git ignore integration using the VCS engine to eliminate dual-maintenance ignore lists, and syntax-compliant inline suppressions requiring fully-qualified rule names with human-readable rationale. 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: Fragmented ignore arrays, missing VCS integration, and ambiguous or ESLint-legacy inline suppressions that cause CI drift. 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	Fragmented ignore arrays, missing VCS integration, and ambiguous or ESLint-legacy inline suppressions that cause CI drift.	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 enable Biome native VCS integration ('vcs.enabled'

Engineers MUST ALWAYS enable Biome native VCS integration ('vcs.enabled': true, 'vcs.clientKind': 'git', 'vcs.useIgnoreFile': true) instead of duplicating patterns in 'files.ignore'.

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.