bcquality/custom/knowledge/architecture/new-file-requires-vscode-refresh.md

bc-version	domain	keywords	technologies	countries	application-area
all	architecture	workspace compile diagnostics refresh al-language multi-project new-file mcp alpackages cross-project	al	w1	all

Description

When Claude Code creates a new AL file in a multi-project workspace (e.g. AppName + AppName.Test), the AL Language Server in VS Code may temporarily assign the new file to the wrong project. This causes false compilation errors such as:

• Missing references to test codeunits (e.g. Library Assert)
• Object ID out of range for the main app
• Missing app.json dependencies

These errors are not real — they disappear after VS Code refreshes its project context. Claude Code must not attempt to fix them.

In MCP sessions, a parallel issue occurs: when a new object is added to a dependency project (e.g. the main app), the MCP AL server for the dependent project (e.g. the test app) cannot resolve the new object — even after al_addproject — because the MCP server resolves cross-project dependencies from .alpackages (compiled symbols), not from workspace source. The false errors persist until the dependency is rebuilt and re-linked.

Rule

VS Code context: After creating a new AL file, Claude Code must:

1. Stop all compilation and diagnostic activity immediately
2. Instruct the developer to refresh VS Code: Ctrl+Shift+P → AL: Reload Extension
3. Wait for explicit confirmation from the developer that the refresh is done
4. Only then run al_getdiagnostics or al_compile to check for real errors

MCP context: After adding a new object to a dependency project (main app), if the dependent project (test app) cannot resolve the new object, Claude Code must:

1. Run al_build on the dependency project to generate a fresh .app
2. Copy the generated .app to the dependent project's .alpackages/ folder
3. Run al_addproject on the dependent project to reload its symbol context
4. Only then run al_build or al_getdiagnostics on the dependent project

What NOT to do

• Do not investigate namespace errors that appear immediately after file creation
• Do not modify using statements based on errors seen before a refresh
• Do not move or rename the file based on pre-refresh diagnostics
• Do not run al_compile or al_build immediately after creating a new file (VS Code)
• Do not report "compilation failed" based on pre-refresh diagnostics
• Do not interpret AL0185 — object 'X' is missing in the test app as a code error before first rebuilding the dependency and updating .alpackages/

Signal to watch for

VS Code: If al_getdiagnostics returns errors referencing objects that clearly belong to the other project (e.g. Library Assert errors in a main app context, or ID range errors for a test codeunit), this is a pre-refresh false positive.

MCP: If al_getdiagnostics on the test app returns AL0185 — Codeunit 'X' is missing for a codeunit that was just created in the main app source, this is a stale symbol cache issue — not a missing implementation.

Message to developer (VS Code context)

When this situation occurs, output exactly this message before stopping:

WARNING: VS Code needs a refresh before I can check for real compilation errors.

Please run: Ctrl+Shift+P -> AL: Reload Extension

Let me know when the refresh is done and I will re-check diagnostics.

Do not continue with any other activity until the developer confirms the refresh.