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
Reservationrenvoie 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
filesniinclude, TypeScript prend**/*, etallowJsy 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
-
TypeScript,
référence TSConfig
(
includepar défaut,allowJs), Project References (fichier solution,tsc -b) et notes de version 3.9. -
moon,
TypeScript project references :
syncProjectReferences. -
VS Code,
motifs glob, réglages
files.*etsearch.exclude, version 1.110. -
VS Code,
normalizeWatcherPatternet recherche de Copilot ; surveillance des fichiers et @parcel/watcher, optionignore. - vscode-php-cs-fixer et installation de PHP CS Fixer.
- Claude Code, worktrees, monorepos, permissions et hooks.
- TanStack, Intent et skill de migration de @tanstack/vue-table 9.3.1.
- Lychen, pull requests 257, 268, 250 et 240 : une mise en œuvre open source de ce que décrit cette note, dans un monorepo moon.