Turborepo 2+ Monorepo Pipeline & Strict Boundary Architecture

--- description: Turborepo 2+ Monorepo Pipeline & Strict Boundary Architecture - Production guidelines for Turborepo 2+ monorepos. Mandates strict package.json exports, hermetic task inputs/outputs caching declarations, boundary linting, and forbids implicit sibling workspace imports. globs: turbo.json, **/package.json, pnpm-workspace.yaml alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/turborepo-monorepo-best-practices" --- # Turborepo 2+ Monorepo Pipeline & Strict Boundary Architecture > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: AI scaffolds circular workspace imports, omits turbo.json hash boundaries, and causes cache misses across build pipelines. ## System Constraints You are a monorepo platform engineer. In Turborepo projects, never import internal packages via relative path traversal (../../packages/foo). Always declare workspace:* dependencies with explicit export maps in package.json and hermetic inputs/outputs globs in turbo.json. ## Strict Guidelines - Never cross package boundaries with relative directory traversal; all internal packages must be referenced via declared workspace packages (e.g. '@repo/ui'). - Specify explicit 'inputs' and 'outputs' in turbo.json tasks; never rely on default coarse caching that triggers false cache hits. - Declare task dependency chains with '^build' so upstream packages build strictly before downstream consumers. - Enforce strict 'exports' maps in shared package.json files to encapsulate internal implementation details and prevent accidental private leaks. ## Bad vs Good Implementations ### Hermetic turbo.json Pipeline vs Flaky Coarse Caching #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Missing dependsOn: ['^build'] causes race conditions where apps compile before shared UI packages build. Missing inputs invalidates cache on unrelated markdown or test edits. ```json // ANTI-PATTERN: No task dependencies, no inputs, and outputs set to whole directory { "$schema": "https://turbo.build/schema.json", "tasks": { "build": { "outputs": [".next/**", "dist/**"] } } } ``` #### Production Standard (Correct) > **Standard**: Declares clean topological dependencies with ^build, excludes uncacheable Next.js build cache, and enables instant remote build artifact re-use. ```json // PRODUCTION STANDARD: Turborepo 2+ Strict Pipeline with Granular Hashing { "$schema": "https://turbo.build/schema.json", "ui": "tui", "tasks": { "build": { "dependsOn": ["^build"], "inputs": ["$TURBO_DEFAULT$", ".env*"], "outputs": [".next/**", "!.next/cache/**", "dist/**"] }, "lint": { "dependsOn": ["^lint"], "inputs": ["$TURBO_DEFAULT$"] }, "check-types": { "dependsOn": ["^check-types"] } } } ``` ### Encapsulated Package Exports Map vs Direct Deep Path Imports #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Bypasses build systems and exposes uncompiled TypeScript files, breaking bundling optimizations and package isolation. ```json // ANTI-PATTERN: Consumer app imports private internal file directly // import { helper } from '@repo/ui/src/internal/helper.ts'; { "name": "@repo/ui", "main": "src/index.ts" } ``` #### Production Standard (Correct) > **Standard**: Package consumers can only import designated public entrypoints; internal components remain safely private. ```json // PRODUCTION STANDARD: Explicit Modern exports Map with Subpath Protection { "name": "@repo/ui", "version": "0.1.0", "type": "module", "exports": { ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" }, "./button": { "types": "./dist/button.d.ts", "import": "./dist/button.js" } }, "scripts": { "build": "tsup src/index.ts src/button.tsx --format esm --dts" } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Turborepo 2+ Monorepo Pipeline & Strict Boundary Architecture

Turborepo 2+ Monorepo Pipeline & Strict Boundary Architecture defines an industrial-grade behavioral standard for frontend engineering. Production guidelines for Turborepo 2+ monorepos. Mandates strict package.json exports, hermetic task inputs/outputs caching declarations, boundary linting, and forbids implicit sibling workspace imports. 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: AI scaffolds circular workspace imports, omits turbo.json hash boundaries, and causes cache misses across build pipelines. 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	AI scaffolds circular workspace imports, omits turbo.json hash boundaries, and causes cache misses across build pipelines.	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:

Never cross package boundaries with relative directory traversal

Never cross package boundaries with relative directory traversal; all internal packages must be referenced via declared workspace packages (e.g. '@repo/ui').

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.

Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.

Specify explicit 'inputs' and 'outputs' in turbo.json tasks

Specify explicit 'inputs' and 'outputs' in turbo.json tasks; never rely on default coarse caching that triggers false cache hits.

Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.

Declare task dependency chains with '^build' so upstream packages build strictly before downstream consumers.

Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.

Enforce strict 'exports' maps in shared package.json files to encapsulate internal implementation details and prevent accidental private leaks.

Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.

Technical Questions & Answers

Frequently Asked Technical Questions

Common questions developers face when configuring AI coding assistants for this stack:

Q:Why is Turborepo 2+ Monorepo Pipeline & Strict Boundary Architecture critical for AI coding assistants?

Production guidelines for Turborepo 2+ monorepos. Mandates strict package.json exports, hermetic task inputs/outputs caching declarations, boundary linting, and forbids implicit sibling workspace imports. Without explicit behavioral boundaries, AI coding assistants (Cursor, Claude Code, Windsurf, Codex) rely on training data averages, which frequently produce deprecated, inefficient, or vulnerable code patterns.

Q:How does adopting this rule prevent AI hallucinations?

This rule explicitly declares what the AI must avoid (AI scaffolds circular workspace imports, omits turbo.json hash boundaries, and causes cache misses across build pipelines.) and prescribes verified positive examples. Grounding the LLM with negative and positive pairs eliminates guesswork.

Q:Which AI coding environments are supported?

This specification is multi-platform compatible: Cursor (.cursor/rules/*.mdc & .cursorrules), Anthropic Claude Code (CLAUDE.md), Windsurf (.windsurfrules), Codex / Cline (AGENTS.md), and GitHub Copilot (.github/copilot-instructions.md).

Q:Can I combine this rule with other technology stacks?

Yes. Use the Interactive Stack Builder or download an Agent Pack to merge this rule with other frontend, backend, database, security, and DevOps rules without syntax collision.