The context trap

Kernel example (L0.md):

# L0 KERNEL (ROOT CONTEXT)

## MISSION

Act as a senior software architect and lead developer. Your goal is to produce maintainable, scalable, and secure code following the project's established patterns. You must orchestrate the loading of specialized contexts (L1) based on the task at hand.

## CRITICAL RULES (THE "NEVER" LIST)

1.  **NEVER** commit secrets or credentials.
2.  **NEVER** bypass the established hexagonal architecture layers.
3.  **NEVER** introduce new dependencies without explicit approval (ADR required).
4.  **NEVER** write "spaghetti code" (high cyclomatic complexity).
5.  **NEVER** ignore linter or type-checker errors.

## L1 CONTEXT MAP (ROUTING TABLE)

| Priority | Pattern (Regex) | L1 Context File | Description | Load Strategy |
| :------- | :-------------- | :-------------- | :---------- | :------------ | --------------- | ------------------------------ | ----------------------------------- | ----------------------------------- | ---- |
| 1        | `/\b(auth       | login           | signup      | session       | jwt             | oauth)\b/i`                    | `L1/Auth.md`                        | Authentication & Security protocols | AUTO |
| 2        | `/\b(db         | database        | prisma      | drizzle       | sql             | migration)\b/i`                | `L1/Database.md`                    | Data persistence & schema rules     | AUTO |
| 3        | `/\b(api        | endpoint        | route       | controller    | trpc            | graphql)\b/i`                  | `L1/API.md`                         | API design & interface standards    | AUTO |
| 4        | `/\b(ui         | component       | tailwind    | css           | front)\b/i`     | `L1/UI.md`                     | User Interface components & styling | AUTO                                |
| 5        | `/\b(test       | spec            | e2e         | mock)\b/i`    | `L1/Testing.md` | Testing strategies & standards | AUTO                                |

## OPERATING PROCEDURE

1.  **Analyze Task:** Read the user's prompt.
2.  **Scan for Patterns:** Match prompt content against the `L1 CONTEXT MAP` regex patterns.
3.  **Load L1 Contexts:** For each match, load the corresponding `L1` file.
    - _NOTE:_ L1 contexts provide domain-specific constraints and patterns.
4.  **Execute:** Perform the task, adhering strictly to L0 rules AND the loaded L1 rules.
5.  **Consult L2 (Optional):** If deep clarification is needed on a specific decision, consult the referenced L2 specs (ADRs) mentioned in the L1 files.

DCL example:

# ==========================================
# DCL (Dynamic Context Language) - Example
# ==========================================
# Domain: Authentication Module
# ==========================================

# Defines the global context of the domain
@context[domain:auth]:
  # Strict constraints (the AI must NEVER do this)
  !constraints:
    - never: [commit_secrets, raw_sql_queries]
    - enforce: [use_orm, secure_password_hashing]

  # Necessary dependencies for this context
  ^dependencies:
    - lib: [bcrypt, jsonwebtoken]
    - service: [user_service, email_service]

  # Procedures and patterns to follow
  ~procedures:
    # Pattern for user signup
    user_signup:
      - step: validate_input
        desc: "Check password complexity and email format."
      - step: hash_password
        desc: "Use bcrypt for hashing. Never store in clear text."
      - step: create_user
        desc: "Call user_service for database creation."
      - step: generate_token
        desc: "Generate a JWT for the session."
      - step: send_welcome_email
        desc: "Call email_service."

    # Pattern for login
    user_login:
      - step: find_user
        desc: "Search user by email."
      - step: verify_password
        desc: "Compare hash with bcrypt."
      - step: generate_token
        desc: "Generate a new JWT."

  # Expected data models
  #schema:
    User:
      - id: [uuid, pk]
      - email: [string, unique]
      - password_hash: [string]
      - created_at: [datetime]

Example file with context tags:

// ==========================================
// FILE: src/modules/user/core/application/use-cases/CreateUser.ts
//
// @L1: auth, database, domain-events
// @architect: hexagonal/use-case
// ==========================================

import { User } from "../../domain/User";
import { IUserRepository } from "../../ports/IUserRepository";
// ... other imports

export class CreateUserUseCase {
  constructor(
    private readonly userRepo: IUserRepository,
    // ...
  ) {}

  async execute(command: CreateUserCommand): Promise<Result<User>> {
    // Business logic...
    // The AI knows it must respect "auth" and "database" rules
    // because they were declared in the header.
  }
}

// ==========================================
// @security: low-risk
// ==========================================

On paper, this is more flexible than the kernel, less rigid than DCL, less invasive than tags in every file. But each MCP tool ships with its description, parameters, and call schema. Those tool definitions (the tool instructions and call schema added to context before the request is even handled) enter the context window as soon as the session starts. Even if the agent never calls the tool, the budget is already spent. Once I start measuring that cost, I see the issue is not only the tool call, but the tool menu loaded upfront.

Context file example (context.ai):

# ==========================================
# LOCATION: src/modules/payment/context.ai
# ==========================================

# Metadata for the agent
meta:
  domain: payment
  description: "Critical rules for payment processing."

# Conditional loading rules
# The agent evaluates these rules before deciding to load this context.
load_if:
  - rule: "Task involves money, transactions, or stripe."
    reason: "High risk domain."
  - rule: "User explicitly mentions 'payment' or 'checkout'."
    reason: "Explicit request."
  - rule: "Files being edited are in 'src/modules/payment/'."
    reason: "Proximity."

# The context itself, loaded only if a rule is met.
context:
  # Critical constraints
  constraints:
    - "NEVER log full credit card numbers or CVV."
    - "MUST use the 'PaymentGatewayPort' for all external calls."
    - "All transactions MUST be wrapped in a database transaction."

  # Implementation patterns
  patterns:
    - name: "Idempotency"
      description: "Ensure payment requests are idempotent using a unique key."

Simulation: the agent with custom MCP in action

User: “I need to refund a payment. It’s sensitive.”

AI (Thought): “Critical task in payment domain. I won’t code anything without checking the rules.” AI (MCP Action): fs_scanner.scan("src/modules/payment", look_for=["context.ai"]) AI (Result): “File context.ai found.” AI (MCP Action): context_loader.load("src/modules/payment/context.ai") AI (Thought): “Context loaded. Critical rules: use PaymentGatewayPort, wrap in DB transaction. Ok, I can start the plan.”

# Back to basics: simplicity
$ ls -l .ai/
-rw-r--r--  1 user  staff  4096 Nov 21 AI.md       # The constitution (single source)
# Aliases for tool compatibility. They all point to the same file.
lrwxr-xr-x  1 user  staff     5 Nov 21 CLAUDE.md -> AI.md
lrwxr-xr-x  1 user  staff     5 Nov 21 CURSOR.md -> AI.md
lrwxr-xr-x  1 user  staff     5 Nov 21 GEMINI.md -> AI.md

Constitution extract (AI.md):

# Constitution

## TL;DR (The "NEVER" List)

**NEVER:**

- Mute lint/type errors (fix root causes)
- Violate layer boundaries (core→npm, application→infrastructure)
- Throw in domain/application (return `Result<T, E>`)

## Principles & Rationale (Drift Prevention)

**Why these rules exist:**

1. **Architecture**: We decouple the _core domain_ from _technology_...
   ...