Le problème

Prenons le monorepo d'une boutique en ligne. Les API Symfony order et stock exportent leur spec OpenAPI, dont sont générés des SDK TypeScript que consomme le front Vue shop. Des agents de code y travaillent en parallèle, chacun dans un worktree sous .claude/worktrees/.

Quatre défauts gênent autant l'humain que l'agent.

  • La recherche tombe sur du généré. Chercher Reservation renvoie d'abord la spec exportée et le SDK ; chercher un paquet, les lockfiles. Une correction faite dans le SDK disparaît à la génération suivante.
  • Le tsconfig racine englobe tout. Sans files ni include, TypeScript prend **/*, et allowJs y ajoute les .js. Il charge les assets publics des API, les builds, et chaque projet une seconde fois.
  • L'éditeur surveille les worktrees. Ouvert sur le checkout principal, il suit chaque worktree, soit une copie complète du dépôt par agent.
  • Le formatage diffère de la CI. Le PHP formaté à l'enregistrement ne suit pas la configuration de la CI. Les pull requests mêlent alors des diffs de format au changement.

La solution

Le tsconfig racine devient un fichier « solution » : il ne compile rien et liste les projets.

// tsconfig.json
{
  "extends": "./tsconfig.options.json",
  "files": [],
  "references": [
    { "path": "fronts/shop" },
    { "path": "libs/typescript/order-api-sdk" },
    { "path": "libs/typescript/stock-api-sdk" }
  ]
}

Sans files: [], la documentation de TypeScript prévient que ce fichier compile deux fois les sources. Depuis TypeScript 3.9, le serveur de langage cherche le projet d'un fichier parmi les références ; tsc -b, lui, les construit dans l'ordre. moon tient la liste à jour (typescript.syncProjectReferences) ; les API et app-contracts, en PHP, restent hors du périmètre.

L'éditeur reçoit ensuite ses réglages, versionnés avec le code :

// .vscode/settings.json (extrait)
{
  // Générés et lockfiles : hors de la recherche et de Quick Open.
  "search.exclude": {
    "**/*.lock": true,
    "**/openapi.json": true,
    "**/generated": true
  },
  // Motif relatif, rattaché au dossier ouvert (voir le piège).
  "files.watcherExclude": {
    ".claude/worktrees/**": true
  },
  // Écrits par yarn et composer, jamais à la main.
  "files.readonlyInclude": {
    "**/yarn.lock": true,
    "**/composer.lock": true
  },
  "editor.formatOnSave": true,
  "[php]": {
    "editor.defaultFormatter": "junstyle.php-cs-fixer"
  },
  // Le script et la configuration de la tâche moon `format`.
  "php-cs-fixer.executablePath": "${workspaceFolder}/tools/php-cs-fixer.sh",
  "php-cs-fixer.config": ".php-cs-fixer.dist.php"
}

Le bouton « Use Exclude Settings and Ignore Files » de la vue de recherche rend ces fichiers au besoin. « Aller à la définition » mène toujours au SDK.

tools/php-cs-fixer.sh lance l'image Docker officielle de PHP CS Fixer, à une version épinglée. L'éditeur, la tâche moon et la CI partagent ainsi un binaire et une configuration.

Un réglage obsolète trompe aussi celui qui lit le fichier. Depuis VS Code 1.110 (4 mars 2026), les réglages typescript.* sont dépréciés au profit du préfixe js/ts.* : nous les migrons.

Ce que voit l'agent

L'agent intégré à VS Code cherche avec le moteur de l'éditeur : par défaut, l'outil de recherche de Copilot applique search.exclude. Un agent en terminal, lui, ne lit pas .vscode/settings.json.

Les recherches de Claude Code respectent .gitignore, et le SDK versionné reste lisible. Une règle Edit dans permissions.deny lui interdit de modifier generated/ et les lockfiles, sans bloquer yarn install. Un hook PostToolUse sur Edit|Write relance le formateur sur chaque fichier modifié : c'est son formatage à l'enregistrement.

Les bibliothèques prennent le même chemin. Depuis sa version 9 (4 août 2026), @tanstack/vue-table livre son guide de migration dans le paquet, sous forme de skill (skills/migrate-v8-to-v9/SKILL.md). L'agent lit le guide de la version installée, et l'humain aussi.

Le piège

Pour exclure les worktrees, le réflexe est d'écrire **/.claude/worktrees/**. Ce motif ne dit pas d'où il part, et il a deux lectures.

@parcel/watcher, qui surveille le dossier ouvert, le compare au chemin relatif. Le code de VS Code compare au chemin absolu tout motif qui commence par **.

Or .vscode/settings.json est versionné : chaque worktree en porte une copie. Ouvert seul, un worktree vit sous .claude/worktrees/<nom>/ : dans la seconde lecture, tous ses fichiers sont exclus de la surveillance.

Le motif relatif .claude/worktrees/** n'a qu'une lecture, rattachée au dossier ouvert. Il exclut les worktrees depuis le checkout principal, et rien depuis un worktree ouvert seul.

Sources