[2026-10-15] eagle: work/projects/vscode-migration/tech-design-xcode-build-server.md

work/projects/vscode-migration/tech-design-xcode-build-server.md

@@ -63,7 +63,8 @@ Add an opt-in VS Code setup to the repository: a workspace file and a few script
 - **A young third-party tool** (version 0.1.0, "early-stage" by its authors) that we fork and maintain ourselves.
 - **Some rough edges:**
   - one platform per worktree at a time;
-  - the first index of a new worktree takes ~5 minutes.
+  - a new worktree has to be prepared and indexed once, ~5 minutes on an M4 Max. Xcode does the same work on a new worktree (not measured side by side), and since the index is shared, whichever tool does it first saves the other from doing it.
+- **Each build or test from VS Code starts xcodebuild from scratch.** Every call loads the workspace and resolves the package graph before building: a build with nothing to do takes ~25 s, and up to ~1 min when xcodebuild checks remote packages. Xcode keeps the workspace loaded between builds and avoids this. It may need its own treatment later, for example skipping package resolution when `Package.resolved` hasn't changed, or keeping a build service running between calls.
 - **Someone has to own it.** I will; the setup is small (a workspace file and ~6 scripts), and it's documented. Breaking changes can be handled by a single AI agent run that can fully fix and validate the setup.
 
 ### Risks
@@ -75,6 +76,10 @@ Add an opt-in VS Code setup to the repository: a workspace file and a few script
   - its dependencies come from Apple/swiftlang (swift-build, swift-tools-protocols, swift-argument-parser) and are pinned too.
 - **Upstream doesn't accept the changes** or the project is abandoned. Mitigation: the fork already carries our changes, so nothing breaks; we keep it, or drop the setup.
 - **Xcode and the editor share the index.** Both write to Xcode's index store; deleting the DerivedData folder resets it, as today.
+- **The setup breaks Xcode builds or the Xcode setup.** Mitigation: it changes nothing Xcode uses. The projects, schemes, xcconfigs, `Package.resolved` files and CI stay as they are. The setup only adds a workspace file and scripts, and VS Code builds run `xcodebuild` on the same projects with Xcode's settings.
+- **A file added from VS Code works there but is missing in Xcode.** New files have to be added to the Xcode project, which is easy to forget outside Xcode. Mitigations:
+  - VS Code builds use the same projects and `xcodebuild` configuration as Xcode, so a file missing from a target fails the VS Code build too; the editor also shows no code intelligence for it;
+  - adopting buildable folders, which is already in progress, removes the need to edit `project.pbxproj` for new files.
 
 ## Testing