L'odyssée du contexte

Exemple du kernel (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.

Exemple de DCL :

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

# Définit le contexte global du domaine
@context[domain:auth]:
  # Contraintes strictes (l'IA ne doit JAMAIS faire cela)
  !constraints:
    - never: [commit_secrets, raw_sql_queries]
    - enforce: [use_orm, secure_password_hashing]

  # Dépendances nécessaires pour ce contexte
  ^dependencies:
    - lib: [bcrypt, jsonwebtoken]
    - service: [user_service, email_service]

  # Procédures et patterns à suivre
  ~procedures:
    # Pattern pour l'inscription d'un utilisateur
    user_signup:
      - step: validate_input
        desc: "Vérifier la complexité du mot de passe et le format de l'email."
      - step: hash_password
        desc: "Utiliser bcrypt pour le hachage. Ne jamais stocker en clair."
      - step: create_user
        desc: "Appeler le user_service pour la création en base."
      - step: generate_token
        desc: "Générer un JWT pour la session."
      - step: send_welcome_email
        desc: "Appeler l'email_service."

    # Pattern pour la connexion
    user_login:
      - step: find_user
        desc: "Rechercher l'utilisateur par email."
      - step: verify_password
        desc: "Comparer le hachage avec bcrypt."
      - step: generate_token
        desc: "Générer un nouveau JWT."

  # Modèles de données attendus
  #schema:
    User:
      - id: [uuid, pk]
      - email: [string, unique]
      - password_hash: [string]
      - created_at: [datetime]

Exemple de fichier avec tags de contexte :

// ==========================================
// 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";
// ... autres imports

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

  async execute(command: CreateUserCommand): Promise<Result<User>> {
    // Logique métier...
    // L'IA sait qu'elle doit respecter les règles "auth" et "database"
    // car elles ont été déclarées dans le header.
  }
}

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

Exemple de fichier de contexte (context.ai) :

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

# Métadonnées pour l'agent
meta:
  domain: payment
  description: "Règles critiques pour le traitement des paiements."

# Règles de chargement conditionnel
# L'agent évalue ces règles avant de décider de charger ce contexte.
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."

# Le contexte lui-même, chargé uniquement si une règle est remplie.
context:
  # Contraintes critiques
  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."

  # Patterns d'implémentation
  patterns:
    - name: "Idempotency"
      description: "Ensure payment requests are idempotent using a unique key."

Simulation : l’agent avec MCP custom en action

Utilisateur : “J’ai besoin de rembourser un paiement. C’est sensible.”

IA (Pensée) : “Tâche critique dans le domaine payment. Je ne code rien sans vérifier les règles.” IA (Action MCP) : fs_scanner.scan("src/modules/payment", look_for=["context.ai"]) IA (Résultat) : “Fichier context.ai trouvé.” IA (Action MCP) : context_loader.load("src/modules/payment/context.ai") IA (Pensée) : “Contexte chargé. Règles critiques : utiliser PaymentGatewayPort, wrapper dans une transaction DB. Ok, je peux commencer le plan.”

# Retour aux bases : Simplicité
$ ls -l .ai/
-rw-r--r--  1 user  staff  4096 Nov 21 AI.md       # La constitution (source unique)
# Les alias pour la compatibilité des outils. Ils pointent tous vers le même fichier.
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

Extrait de la constitution (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_...
   ...