File Editing Workflow and Validation

Relevant source files

• VSCode Agent/Prompt.txt

Purpose and Scope

This document details the VSCode Agent's file editing workflow, including the mandatory read-before-write rule, the use of insert_edit_into_file as the primary editing mechanism, code representation patterns using ellipsis markers, and the required validation pipeline. For information about the broader tool ecosystem, see Agent Architecture and Tool Categories. For context gathering before editing, see Context Discovery Strategy.

Mandatory Read-Before-Write Rule

The VSCode Agent enforces a strict read-before-write rule to ensure edits are contextually appropriate and correctly applied. This rule prevents blind modifications that could introduce errors or inconsistencies.

Core Principle: "Don't try to edit an existing file without reading it first, so you can make changes properly." VSCode Agent/Prompt.txt42

Read Operations

Files must be read using the read_file tool before any edits. The agent has access to three mechanisms for gathering file context:

Tool	Purpose	When to Use
read_file	Read specific file contents with line ranges	When you know the exact file to modify
semantic_search	Natural language search across workspace	When searching for concepts or functionality
grep_search	Exact text pattern matching	When searching for specific strings or patterns

The read_file tool requires explicit line ranges (startLineNumberBaseZero, endLineNumberBaseZero) and returns an outline for large files, allowing targeted retrieval of additional content as needed. VSCode Agent/Prompt.txt154-173

Exception: "You don't need to read a file if it's already provided in context." VSCode Agent/Prompt.txt25 This prevents redundant reads when the user has already shared file contents.

Sources: VSCode Agent/Prompt.txt42 VSCode Agent/Prompt.txt25 VSCode Agent/Prompt.txt154-173

The insert_edit_into_file Tool

The insert_edit_into_file tool is the VSCode Agent's primary file modification mechanism, described in the system prompt as "very smart" with the ability to understand how to apply edits with minimal hints. VSCode Agent/Prompt.txt49

Tool Parameters

The tool accepts three required parameters VSCode Agent/Prompt.txt326-345:

• explanation: A short description of the edit being made (generated first)
• filePath: Absolute path to the file to edit
• code: The code change to apply, using ellipsis markers for unchanged regions

Key Constraints

1. No User Display: "NEVER show the changes to the user, just call the tool, and the edits will be applied and shown to the user." VSCode Agent/Prompt.txt44
2. No Code Blocks: "NEVER print a codeblock that represents a change to a file, use insert_edit_into_file instead." VSCode Agent/Prompt.txt45
3. Grouped Edits: "When editing files, group your changes by file." VSCode Agent/Prompt.txt43
4. Multiple Uses: "You can use any tool multiple times in a response" VSCode Agent/Prompt.txt46

Sources: VSCode Agent/Prompt.txt49 VSCode Agent/Prompt.txt43-46 VSCode Agent/Prompt.txt326-345

Code Representation Patterns

The VSCode Agent uses a specific pattern for representing code changes: ellipsis comments mark unchanged regions, with only modified code shown explicitly. This approach minimizes redundancy and allows the intelligent tool to infer correct placement.

Ellipsis Marker Syntax

Standard Pattern VSCode Agent/Prompt.txt50-55:

// ...existing code...
changed code
// ...existing code...
changed code
// ...existing code...

The ellipsis marker (// ...existing code...) is a literal comment that signals to the tool: "this region remains unchanged." The tool understands where to insert the changed code relative to these markers.

Concrete Example

The system prompt provides a canonical example for modifying a Person class VSCode Agent/Prompt.txt57-65:

This pattern:

1. Shows only the class shell (class Person {)
2. Uses ellipsis markers to represent existing methods/properties
3. Inserts new age property
4. Uses another ellipsis marker
5. Inserts new getAge() method

Conciseness Principle

"The tool prefers that you are as concise as possible." VSCode Agent/Prompt.txt51 This means:

• Avoid repeating existing code VSCode Agent/Prompt.txt50
• Use comments for unchanged regions
• Show only what changes
• Trust the tool's intelligence to apply edits correctly

Sources: VSCode Agent/Prompt.txt50-65 VSCode Agent/Prompt.txt397-399

Mandatory Validation with get_errors

After every file edit, the VSCode Agent must call get_errors to validate changes. This is non-negotiable and applies regardless of the perceived simplicity of the edit.

Validation Requirement

"After editing a file, you MUST call get_errors to validate the change." VSCode Agent/Prompt.txt48

The get_errors tool retrieves compile or lint errors for specified files, showing the same diagnostics that the user sees in their IDE. VSCode Agent/Prompt.txt226-237

get_errors Tool Schema

Iterative Fixing Loop

Once errors are detected, the agent must:

1. Determine Relevance: "Fix the errors if they are relevant to your change or the prompt" VSCode Agent/Prompt.txt48
2. Apply Fixes: Use insert_edit_into_file to correct issues
3. Re-validate: "remember to validate that they were actually fixed" VSCode Agent/Prompt.txt48

This creates an iterative loop:

Error Context

The get_errors tool is also useful for understanding user-reported issues: "If the user mentions errors or problems in a file, they may be referring to these. Use the tool to see the same errors that the user is seeing." VSCode Agent/Prompt.txt227

Sources: VSCode Agent/Prompt.txt48 VSCode Agent/Prompt.txt226-237

Complete File Editing Workflow

The following diagram synthesizes the entire file editing workflow, from context gathering through validation:

Workflow Rules Summary

Phase	Rule	Source
Context	Read file before editing (unless already in context)	VSCode Agent/Prompt.txt42
Edit Format	Use ellipsis markers for unchanged code	VSCode Agent/Prompt.txt50-55
Edit Format	Be as concise as possible	VSCode Agent/Prompt.txt51
Edit Format	Group changes by file	VSCode Agent/Prompt.txt43
Edit Format	Generate explanation first	VSCode Agent/Prompt.txt331-333
User Display	NEVER show code blocks to user	VSCode Agent/Prompt.txt44-45
Tool Usage	Use insert_edit_into_file instead of printing	VSCode Agent/Prompt.txt23
Validation	MUST call get_errors after editing	VSCode Agent/Prompt.txt48
Validation	Fix relevant errors	VSCode Agent/Prompt.txt48
Validation	Validate fixes were applied	VSCode Agent/Prompt.txt48

Sources: VSCode Agent/Prompt.txt1-400

Tool Invocation vs User Display

A critical distinction in the VSCode Agent's behavior is the separation between tool invocation (which performs actions) and user display (which communicates to the user). The agent must never conflate these two channels.

Prohibition on Code Block Display

The system prompt contains multiple emphatic statements about this:

1. "NEVER print out a codeblock with file changes unless the user asked for it. Use the insert_edit_into_file tool instead." VSCode Agent/Prompt.txt23
2. "NEVER show the changes to the user, just call the tool, and the edits will be applied and shown to the user." VSCode Agent/Prompt.txt44
3. "NEVER print a codeblock that represents a change to a file, use insert_edit_into_file instead." VSCode Agent/Prompt.txt45

Rationale

This design enforces several principles:

1. Automation: Changes are applied automatically, not manually by the user
2. Accuracy: The tool applies changes precisely, avoiding copy-paste errors
3. Efficiency: User doesn't need to manually transfer code
4. Visibility: IDE shows actual applied changes, not proposed changes

Reminder System

The system includes a reminder section to reinforce this behavior: "When using the insert_edit_into_file tool, avoid repeating existing code, instead use a line comment with ...existing code... to represent regions of unchanged code." VSCode Agent/Prompt.txt397-399

Sources: VSCode Agent/Prompt.txt23-24 VSCode Agent/Prompt.txt44-45 VSCode Agent/Prompt.txt397-399

Best Practices and Guidelines

Beyond the mandatory rules, the VSCode Agent follows several best practices when editing files:

External Libraries

"Follow best practices when editing files. If a popular external library exists to solve a problem, use it and properly install the package e.g. with 'npm install' or creating a 'requirements.txt'." VSCode Agent/Prompt.txt47

This means:

• Prefer established solutions over custom implementations
• Use run_in_terminal to install dependencies
• Create requirements files for reproducibility

Contextual Awareness

"If you can infer the project type (languages, frameworks, and libraries) from the user's query or the context that you have, make sure to keep them in mind when making changes." VSCode Agent/Prompt.txt16

The agent should:

• Identify the tech stack from context
• Apply framework-specific conventions
• Use appropriate language idioms

Creative Problem Solving

"Think creatively and explore the workspace in order to make a complete fix." VSCode Agent/Prompt.txt21

This encourages:

• Thorough exploration of the codebase
• Considering multiple files that may need changes
• Understanding the broader impact of modifications

Responsibility for Context

"It's YOUR RESPONSIBILITY to make sure that you have done all you can to collect necessary context." VSCode Agent/Prompt.txt18

The agent must:

• Gather sufficient context before acting
• Use multiple tools if needed
• Call tools repeatedly until the task is complete
• Not give up unless certain the task cannot be fulfilled

Sources: VSCode Agent/Prompt.txt16-21 VSCode Agent/Prompt.txt47