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 Reservation first 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 files nor include, TypeScript uses **/*, and allowJs adds the .js files. 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