Configure AI for your codebase
AI agents: See llms.txt for documentation discovery and navigation. Documentation articles are also available as Markdown by appending .md to the article URL. Join VS Code at Microsoft Ignite or catch the sessions online. A year of VS Code, wrapped. Explore the highlights. Configure AI for your codebase View as Markdown Ask in VS Code Ask in VS Code Insiders AI agents need reliable project context to follow your repository's structure and conventions.
Build on the documentation and automation you already maintain. Start with one repeated problem, reuse an existing customization when it fits, and add your repository's own guidance only where needed. This guide first helps you choose the right customization, then shows how the pieces fit together in a TypeScript API project. You'll apply what you need to your repository with focused project instructions and optional extensions.
Finally, you'll try a representative task and refine the guidance based on the results. The example uses the GitHub Copilot harness in Visual Studio Code, with alternatives for the Anthropic Claude and OpenAI Codex harnesses. A harness is the agent environment that provides tools and loads customizations. It is separate from the language model. Before you start Prepare your session Open your repository root. Complete the setup and authentication for your harness in VS Code.
Select your harness from Session Target and use it throughout setup. Choose the article's tabs for your harness, not your language model. For example, a Claude model in a Copilot session still uses the Copilot harness. Note Work in the current folder rather than a new worktree so new sessions can access your uncommitted customization files. In the Agents window, leave New Worktree unselected. Note Claude and Codex harnesses are disabled when Copilot enterprise-managed settings apply , unless your administrator explicitly permits them.
Contact the IT team that deployed the settings to discuss access. Review your existing setup Before adding another customization, check what the project already provides: Existing instruction files, skills, agents, and installed plugins for your harness. Setup, build, lint, and test commands documented in README.md , CONTRIBUTING.md , or other project documentation. Representative implementations, tests, and shared helpers that demonstrate the conventions you want followed.
Fix missing, stale, or unreliable documentation and commands that affect the task you want to improve. A customization should point to those shared sources rather than maintain a separate version solely for the agent. If you haven't used an agent on this repository yet, run a representative task and use its result as a baseline. Otherwise, choose one recurring problem and note what the agent currently does and what a better result would look like.
For example, generated API tests duplicate setup code, but should reuse the project's existing test helper. Choose the right customization Choose the customization that matches the need. A one-time requirement belongs in the current prompt, not shared project configuration. What you encounter Smallest useful response A published workflow already covers the capability you need Reuse an existing skill or plugin before building another The agent puts handlers in the wrong layer or uses the wrong project command Add project instructions pointing to the expected structure, examples, and commands Generated tests repeatedly duplicate shared setup Add scoped rules for the relevant test files You repeatedly need an API investigation with the same scope and output Define a custom agent for that role You repeat the same procedure to prepare a change for review Package the procedure as an agent skill A command needs to run at a supported workflow event without the model requesting it Configure a hook Example: Customize an API project Consider a TypeScript API project with existing application code and tests.
The .github entries below show the optional customizations discussed in this example, not files that every project needs: your-project/ CONTRIBUTING.md # Build, lint, and test commands src/ api/routes/ # HTTP handlers schemas/ # Request validation repositories/ # Data access tests/ api/ # Endpoint tests named *.test.ts helpers/createTestApp.ts # Shared application setup for tests .github/ copilot-instructions.md # Copilot project instructions instructions/ api-tests.instructions.md agents/ researcher.agent.md skills/ validate-change/ SKILL.md The team wants new handlers to follow this structure, API tests to reuse their existing setup, a researcher to explain request flows, and a repeatable procedure for checking an API change.
These are different needs, not reasons to keep adding rules to one instruction file. The four files below show one way to separate them for the Copilot harness. Their full paths are relative to the repository root. Adapt them to files that exist in your project, and merge useful guidance into existing customizations rather than replacing them wholesale. You don't need all four files to get started. .github/copilot-instructions.md # API project conventions * Put HTTP handlers in `src/api/routes` . * Put shared request-validation schemas in `src/schemas` . * Keep database access in `src/repositories` , not in HTTP handlers. * Read a nearby implementation before adding a new handler or schema. ## Project commands Use the build, lint, and test commands documented in `CONTRIBUTING.md` .
Select the code to copy it manually. .github/instructions/api-tests.instructions.md --- applyTo : 'tests/api/**/*.test.ts' --- # API tests * Reuse application setup from `tests/helpers/createTestApp.ts` . * Check the response status and body for the requested behavior. * Keep each test's data independent of other tests. Select the code to copy it manually. .github/agents/researcher.agent.md --- name : Researcher description : Trace API request handling and explain existing patterns without editing files tools : [ 'read' , 'search' ] --- Investigate the API behavior identified in the request.
Follow the handler through validation and data access. Read related tests to understand the expected behavior. Return: * Relevant files and symbols. * A concise explanation of the request flow. * Existing patterns to reuse for the proposed change. * Open questions that the available code does not answer. Do not edit files or run terminal commands. Select the code to copy it manually. .github/skills/validate-change/SKILL.md --- name : validate-change description : Check an API change using the project's tests and lint commands.
Use when preparing a change for review. --- # Validate an API change 1. Inspect the changed handlers, schemas, repositories, and related tests. 1. Read `CONTRIBUTING.md` for test, lint, and setup commands. 1. Choose the smallest set of checks that covers the changed behavior. If a command or required tool is unavailable, report the limitation. 1. Run those checks without changing application code or weakening tests. 1.
Summarize the commands, results, and remaining gaps. Select the code to copy it manually. .github/copilot-instructions.md: Lines 3-10 Keep repository knowledge shared Project instructions describe decisions that matter across tasks: where code belongs, how layers interact, and where to find project commands. Keep this knowledge in one place instead of repeating it in every prompt or custom agent. For your repository, replace the example paths and remove rules that don't address a recurring problem. .github/instructions/api-tests.instructions.md: Line 2 Narrow guidance to the files that need it The pattern targets API test files, such as tests/api/users.test.ts , rather than the handler in src/api/routes/users.ts .
It is relative to the repository root, not the instructions directory. Use a scoped file when a part of your codebase needs guidance that would be distracting in the project-wide file. .github/instructions/api-tests.instructions.md: Lin
The rest of this page is on the live site.