The problem
Take the monorepo of an online shop. The Symfony APIs
order and stock export their
OpenAPI spec, from which
TypeScript SDKs
are generated for the Vue front end shop.
Coding agents work in it in parallel, each in a worktree
under .claude/worktrees/.
Four flaws get in the way of the human and the agent alike.
-
Search lands on generated files.
Searching for
Reservationfirst returns the exported spec and the SDK; searching for a package, the lockfiles. A fix made in the SDK disappears with the next generation. -
The root tsconfig takes in everything.
With neither
filesnorinclude, TypeScript uses**/*, andallowJsadds the.jsfiles. It loads the APIs' public assets, the builds, and every project a second time. - The editor watches the worktrees. Opened on the main checkout, it follows every worktree, a full copy of the repository per agent.
- Formatting differs from the CI. PHP formatted on save does not follow the CI configuration. Pull requests then mix formatting diffs with the change.
The solution
The root tsconfig becomes a "solution" file: it compiles nothing and lists the projects.
// tsconfig.json
{
"extends": "./tsconfig.options.json",
"files": [],
"references": [
{ "path": "fronts/shop" },
{ "path": "libs/typescript/order-api-sdk" },
{ "path": "libs/typescript/stock-api-sdk" }
]
}
Without files: [], the TypeScript documentation
warns that this file compiles the sources twice. Since
TypeScript 3.9, the language server looks for a file's
project among the references; tsc -b builds
them in order. moon keeps the list up to date
(typescript.syncProjectReferences); the APIs
and app-contracts, written in PHP, stay out of
scope.
The editor then gets its settings, versioned with the code:
// .vscode/settings.json (excerpt)
{
// Generated files and lockfiles: out of search and Quick Open.
"search.exclude": {
"**/*.lock": true,
"**/openapi.json": true,
"**/generated": true
},
// Relative pattern, tied to the opened folder (see the pitfall).
"files.watcherExclude": {
".claude/worktrees/**": true
},
// Written by yarn and composer, never by hand.
"files.readonlyInclude": {
"**/yarn.lock": true,
"**/composer.lock": true
},
"editor.formatOnSave": true,
"[php]": {
"editor.defaultFormatter": "junstyle.php-cs-fixer"
},
// The script and the configuration of the moon `format` task.
"php-cs-fixer.executablePath": "${workspaceFolder}/tools/php-cs-fixer.sh",
"php-cs-fixer.config": ".php-cs-fixer.dist.php"
}
The "Use Exclude Settings and Ignore Files" button of the search view brings these files back when needed. "Go to Definition" still leads into the SDK.
tools/php-cs-fixer.sh runs the official PHP CS
Fixer Docker image, at a pinned version. The editor, the
moon task
and the
CI
thus share one binary and one configuration.
An outdated setting also misleads whoever reads the file.
Since VS Code 1.110 (March 4, 2026), the
typescript.* settings are deprecated in favour
of the js/ts.* prefix: we migrate them.
What the agent sees
The agent built into VS Code searches with the editor's
engine: by default, the Copilot search tool applies
search.exclude. An agent in a terminal,
however, does not read .vscode/settings.json.
Claude Code's searches respect .gitignore, and
the committed SDK stays readable. An Edit rule
in permissions.deny forbids it to modify
generated/ and the lockfiles, without blocking
yarn install. A PostToolUse hook
on Edit|Write runs the formatter again on each
modified file: that is its format on save.
Libraries take the same path. Since version 9 (August 4,
2026), @tanstack/vue-table ships its migration
guide in the package, as a skill
(skills/migrate-v8-to-v9/SKILL.md). The agent
reads the guide for the installed version, and so can the
human.
The pitfall
To exclude the worktrees, the reflex is to write
**/.claude/worktrees/**. This pattern does not
say where it starts, and it has two readings.
@parcel/watcher, which watches the opened folder, matches it
against the relative path. VS Code's own code matches any
pattern starting with ** against the absolute
path.
Now .vscode/settings.json is versioned: each
worktree carries a copy. Opened on its own, a worktree lives
under .claude/worktrees/<name>/: in the
second reading, all its files are excluded from watching.
The relative pattern .claude/worktrees/** has a
single reading, tied to the opened folder. It excludes the
worktrees from the main checkout, and nothing from a
worktree opened on its own.
Sources
-
TypeScript,
TSConfig reference
(default
include,allowJs), Project References (solution file,tsc -b) and 3.9 release notes. -
moon,
TypeScript project references:
syncProjectReferences. -
VS Code,
glob patterns,
files.*andsearch.excludesettings, version 1.110. -
VS Code,
normalizeWatcherPatternand Copilot search; file watching and @parcel/watcher,ignoreoption. - vscode-php-cs-fixer and PHP CS Fixer installation.
- Claude Code, worktrees, monorepos, permissions and hooks.
- TanStack, Intent and migration skill of @tanstack/vue-table 9.3.1.
- Lychen, pull requests 257, 268, 250 and 240: an open-source implementation of what this note describes, in a moon monorepo.