Text of code.visualstudio.com › docs › agents › guides › context-engineering-guide as Styx crawled it on Oct 9, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

Set up a context engineering flow in VS Code

AI agents: See llms.txt for documentation discovery and navigation. Documentation articles are also available as Markdown by appending .md to the article URL. 🎬 Watch The Story of VS Code! VS Code is now on Instagram, follow @vscode.ig for updates, tips, and more. Rewatch GitHub Copilot Day. Set up a context engineering flow in VS Code View as Markdown Ask in VS Code Ask in VS Code Insiders This guide shows you how to set up a context engineering workflow in VS Code using custom instructions, custom agents, and prompt files.

Context engineering is a systematic approach to providing AI agents with targeted project information to improve the quality and accuracy of generated code. By curating essential project context through custom instructions, implementation plans, and coding guidelines, you enable AI to make better decisions, improve accuracy, and maintain persistent knowledge across interactions. Tip VS Code chat provides a built-in plan agent to help you create detailed implementation plans before starting complex coding tasks.

If you don't want to create a custom planning workflow, you can use the plan agent to generate implementation plans quickly. Context engineering workflow The high-level workflow for context engineering in VS Code consists of the following steps: Curate project-wide context: use custom instructions to include relevant documentation (for example, architecture, design, contributor guidelines) as context to all agent interactions.

Generate implementation plan: create a planning persona by using a custom agent and a prompt to generate a detailed feature implementation plan. Generate implementation code: use custom instructions to generate code based on the implementation plan that adheres to your coding guidelines. As you work through the steps, you can iterate and refine the output with follow-up prompts in the chat. The following diagram illustrates a context engineering workflow in VS Code: Step 1: Curate project-wide context To ground the AI agent in the specifics of the project, collect key project information like product vision, architecture, and other relevant documentation and add it as chat context via custom instructions.

By using custom instructions, you ensure that the agent consistently has access to this context and doesn't have to re-learn it for each chat interaction Why this helps: The agent could find this information in the codebase, but it might be buried in comments or scattered across multiple files. By providing a concise summary of the most important information, you help the agent to always have critical context available for decision-making.

Describe relevant project documentation in Markdown files in the repository, for example create PRODUCT.md , ARCHITECTURE.md , and CONTRIBUTING.md files. Tip If you have an existing codebase, you can use AI to generate these project documentation files. Make sure to review and refine the generated documentation files to ensure accuracy and completeness. Generate an ARCHITECTURE.md (max 2 page) file that describes the overall architecture of the project.

Generate a PRODUCT.md (max 2 page) file that describes the product functionality of the project. Generate a CONTRIBUTING.md (max 1 page) file that describes developer guidelines and best practices for contributing to the project. Create a .github/copilot-instructions.md instructions file at the root of your repository. The instructions in this file are automatically included in all chat interactions as context for the AI agent.

Provide a high-level overview for the agent with the project context and guidelines. Reference relevant supporting documentation files by using Markdown links. The following example .github/copilot-instructions.md file provides a starting point: # [Project Name] Guidelines * [ Product Vision and Goals ]( ../PRODUCT.md ): Understand the high-level vision and objectives of the product to ensure alignment with business goals. * [ System Architecture and Design Principles ]( ../ARCHITECTURE.md ): Overall system architecture, design patterns, and design principles that guide the development process. * [ Contributing Guidelines ]( ../CONTRIBUTING.md ): Overview of the project's contributing guidelines and collaboration practices.

Suggest to update these documents if you find any incomplete or conflicting information during your work. Tip Start small, keeping the initial project-wide context concise and focused on the most critical information. If uncertain, focus on high-level architecture and only add new rules to address errors or incorrect behavior the agent makes repeatedly (for example, using the wrong shell command, ignoring certain files).

Step 2: Create implementation plan Once you have the project-specific context in place, you can use AI to prompt the creation of an implementation plan for a new feature or bug fix. Generating an implementation plan is an iterative process that might require multiple rounds of refinement to ensure it's complete and accurate. With a custom agent for planning, you can create a dedicated persona with planning-specific guidelines and tools (for example, read-only access to the codebase).

They can also capture specific workflows for brainstorming, researching, and collaborating for your project and team. For deep research that produces a thorough, well-cited report on a topic, use the built-in research agent in Copilot sessions. Tip Once you create custom agents, treat them as living documents. Refine and improve them over time based on any mistakes or shortcomings you observe in the agent's behavior. Create a planning document template plan-template.md that defines the structure and sections of the implementation plan document.

By using a template, you ensure that the agent collects all necessary information and presents it in a consistent format. This also helps improve the quality of the code that is generated from the plan. The following plan-template.md file provides sample structure for an implementation plan template: --- title : [ Short descriptive title of the feature ] version : [ optional version number ] date_created : [ YYYY-MM-DD ] last_updated : [ YYYY-MM-DD ] --- # Implementation Plan: < feature > [Brief description of the requirements and goals of the feature] ## Architecture and design Describe the high-level architecture and design considerations. ## Tasks Break down the implementation into smaller, manageable tasks using a Markdown checklist format. ## Open questions Outline 1-3 open questions or uncertainties that need to be clarified.

Create a planning agent .github/agents/plan.agent.md The planning agent defines a planning persona and instructs the agent not to perform implementation tasks, but to focus on creating the implementation plan. You can specify handoffs to transition to an implementation agent after the plan is complete. To create a custom agent, run the Chat: New Custom Agent command in the Command Palette. If you want to access GitHub issues for context, make sure to install the GitHub MCP server .

You might want to configure the model metadata property to use a language model that is optimized for reasoning and deep understanding. The following plan.agent.md file provides a starting point for a planning custom agent and handoff to a TDD implementation agent: --- description : 'Architect and planner to create detailed implementation plans.' tools : [ 'web/fetch' , 'read/problems' , 'search/codebase' , 'search/usages' , 'todo' , 'agent' , 'github/github-mcp-server/get_issue' , 'github/github-mcp-server/get_issue_comments' , 'github/github-mcp-server/list_issues' ] handoffs : - label : Start Implementation agent : tdd prompt : Now implement the plan outlined above using TDD principles. send : true --- # Planning Agent You are an architect focused on creating detailed and comprehensive implementation plans for new features and bug fixes.

Your goal is to break down complex requirements into clear, actionable tasks that can

The rest of this page is on the live site.