Configure AI for your codebase

AI agents can produce better results when they understand how your codebase is structured, which commands to run, and which conventions to follow. Configure this information once as repository customizations instead of repeating it in every prompt.

This guide helps you configure the GitHub Copilot, Anthropic Claude, or OpenAI Codex harness in Visual Studio Code. Start with an observed project problem and a representative task. Make the smallest useful customization, confirm that it applies, repeat the task, and compare the results before you share the configuration. The workflow is shared, with tabs for harness-specific formats and behavior.

To understand how the customization types differ and work together, see Agent customization.

Prerequisites

For this walkthrough, work in the current folder. If you're using the Agents window, leave New Worktree unselected so new sessions can access your uncommitted customization files.

Choose the tabs for your harness, not your language model. For example, a Claude model in a Copilot session still uses the Copilot harness.

Note

The Local harness also supports the Copilot file layout shown in this guide, but tool names and some activation behavior differ. For Local-specific configuration, see custom instructions, agent skills, and custom agents.

Establish a baseline

Choose one project-specific problem that occurs repeatedly, such as using the wrong test command, placing files in the wrong directory, or selecting a library that your project doesn't use. A one-time requirement belongs in the current request rather than in shared project configuration.

Define a small representative task with a clear success criterion. Record the current result or use evidence from a recent task:

  • Which files the agent creates or changes.
  • Which project patterns and libraries it follows.
  • Which commands and tests it runs, including failures or skipped checks.
  • Which corrections you have to provide.

If the result already meets your success criterion, stop. You don't need a customization for that behavior. For a coding task, see the add a feature guide for guidance on establishing baseline tests and verifying the outcome.

Step 1: Create project instructions

Start with a project instructions file for information that applies across your codebase. Focus the initial change on the observed problem and decisions the agent can't reliably infer from the repository. Each harness has its own discovery rules, so use its expected file name and location.

  1. Open the Agent Customizations editor for the selected harness. In the Chat view, run Chat: Open Customizations from the Command Palette (⇧⌘P (Windows, Linux Ctrl+Shift+P)).

  2. In the Overview section, enter the prompt for your harness below and press Enter to submit it.

  3. Continue in the chat that opens. Confirm that it uses the intended harness and repository, and answer any clarifying questions.

  4. Review the changes and save the instructions in the expected location. If the file already exists, review the update rather than replacing existing guidance without checking it.

Use .github/copilot-instructions.md at the repository root for project-wide instructions.

Analyze this codebase and create or update .github/copilot-instructions.md with project-wide instructions. Cover architecture, important directories, build and test commands, coding conventions, and requirements for completing a change. Preserve useful existing guidance, avoid duplication, and ask about anything you cannot determine from the repository.
Tip

Project instructions are most useful when they document decisions the agent cannot reliably infer from the code alone. Avoid generic advice that applies to any project.

Step 2: Review the generated instructions

Treat generated instructions as a starting point. Check that they contain accurate, project-specific information:

  • Observed problem: include only the guidance needed to improve the baseline behavior.
  • Architecture: describe important directories, component boundaries, and where to add different types of code.
  • Commands: include the correct build, test, lint, and formatting commands.
  • Technology choices: identify preferred frameworks, libraries, and patterns.
  • Conventions: capture naming, error-handling, testing, security, and documentation requirements.
  • Definition of done: state which validations the agent should run before completing a task.

Remove information that is generic, obsolete, or duplicated elsewhere in the file. Resolve conflicting instructions and keep each rule concise.

For example, project-specific instructions might include:

## Project structure

* Add API routes under `src/api/routes`.
* Put shared validation schemas in `src/schemas`.
* Keep database access in the repository layer.

## Validation

* Run the unit tests for the changed package.
* Run the linter before completing a code change.
* Add or update tests for every behavior change.

Learn more about writing effective custom instructions.

Step 3: Verify the improvement

Confirm that the instructions apply, and then repeat the representative task from your baseline. Keep the harness, model, tools, task, and relevant context the same where practical so that the customization is the main change.

  1. In the Agent Customizations editor, select Instructions for your harness and confirm that the project instructions file is listed. This checks discovery, not whether the agent follows every instruction.
  2. Start a new chat with the same harness and repository so the comparison doesn't rely on guidance from the creation conversation.
  3. Expand References in the response and confirm that the expected instructions were included.
  4. Repeat the representative task with the same success criterion.
  5. Compare the result with the baseline. Review file placement, project patterns, libraries, tool activity, commands, tests, and errors rather than relying on the agent's summary.

If the file is missing, invalid, or included but not followed, use the agent customization troubleshooting guide to identify the failure before adding more instructions.

If the instructions are included but the result still misses the success criterion, clarify one relevant rule and repeat the task in another new chat. Stop when the task meets the criterion. More instructions consume context and can introduce conflicts without improving the result.

For a broader controlled comparison that includes quality, reliability, credits, tokens, duration, and tool calls, use the usage optimization loop.

Step 4: Share the configuration

Commit the project instructions file and share it through your repository's normal pull request or review process. Contributors who obtain the updated files and use a compatible harness can reuse the guidance without recreating it.

Review the instructions like other development configuration. Use your existing ownership and review process to make responsibility for the file clear. Update it when the architecture, commands, dependencies, or team practices change, and remove stale or duplicate rules.

If your team uses multiple harnesses, keep shared guidance consistent and avoid contradictory copies. A file supported by one harness isn't automatically supported by every other harness.

If the representative task now meets the success criterion, stop. Your repository has a useful baseline customization. The remaining steps are optional. Add them when different parts of the codebase need distinct guidance or when your team repeatedly performs the same workflow.

Step 5: Add targeted instructions (optional)

Add targeted instructions when different parts of your codebase need different guidance. For example, frontend code and infrastructure code might follow different conventions. Keep project-wide standards in the instructions file from step 1.

In the Agent Customizations editor's Overview section, submit a request to create the file for your harness below. Describe the conventions it should cover and use an existing file type or directory from your repository.

Create .github/instructions/frontend.instructions.md. For TypeScript React files, include this YAML frontmatter before the Markdown instructions:

---
applyTo: "**/*.tsx"
---

The pattern matches .tsx files throughout the repository. Review the pattern and test the instructions by asking the agent to make a small change to a specific matching file.

Learn more about file-based instructions.

Review and save the generated file, then test it in a new chat with the same harness. Confirm that the result follows the targeted conventions. If it doesn't, check discovery and scope before revising the instructions.

If you changed the session's working folder to test nested instructions, return to the repository root before continuing.

Step 6: Package a recurring workflow (optional)

Create an agent skill when your team repeatedly explains the same multi-step process. A skill can include instructions, scripts, templates, examples, and other resources that the agent loads when relevant.

For example, create a validate-change skill that selects and runs the relevant checks for a code change, then reports what passed, failed, or wasn't run. Submit the prompt for your harness in the Agent Customizations editor's Overview section:

Create a workspace skill named validate-change at .github/skills/validate-change/SKILL.md. It should inspect a code change, choose and run the relevant tests and lint checks using this repository's commands, and report what passed, failed, or was not run. Describe when to use it in its frontmatter.

After generating the skill:

  1. Review the SKILL.md file. Check that its name matches the directory name and its description explains what it does and when to use it.
  2. Review any scripts, templates, or other resources in the skill directory, and save your changes.
  3. Start a new chat with the same harness and repository. Type / in the chat input and select validate-change to invoke the skill explicitly. Identify the code change to validate.
  4. Review the tool activity and results. Check that the agent loads the skill, selects appropriate checks, and reports failures or skipped checks accurately.

You can also test automatic selection in a separate chat by asking the agent to validate a change without naming the skill. If it doesn't select the skill, review the description and invocation settings. Explicit invocation and model-selected use are separate checks.

Learn more about agent skills.

Step 7: Add a specialized agent (optional)

Create a custom agent when a role needs focused instructions. For example, a codebase researcher can investigate implementation details and report findings before you decide what to change. Tool restrictions depend on the harness, so don't assume a role description alone prevents edits.

In the Agent Customizations editor's Overview section, submit the prompt for your harness:

Create a workspace custom agent named researcher at .github/agents/researcher.agent.md. It should trace how features work and report findings with file locations, without changing the repository. Configure its tools to use only the Copilot harness's file-reading and code-search tools. Exclude tools that can edit files, run shell commands, or delegate to other agents.

Review the tools allowlist in the generated file. Confirm that it contains only the intended reading and search tools, rather than unrestricted tool access.

After generating the agent:

  1. Review and save the file. Check that the instructions define a clear role and don't conflict with your project guidance.
  2. Start a new chat with the same harness and repository, and select researcher from the agents dropdown.
  3. Ask it to research how a feature works. Check that it identifies relevant files, supports findings with evidence, and follows its configured role.
  4. Review any changes and tool activity rather than assuming the agent's name or instructions make it read-only.

Learn more about custom agents.

What you configured

If you completed the optional steps, your repository can contain the following files for your selected harness. The frontend directory is an example; use the structure of your repository.

your-project/
  .github/
    copilot-instructions.md
    instructions/
      frontend.instructions.md
    skills/
      validate-change/
        SKILL.md
    agents/
      researcher.agent.md

Project instructions provide the baseline. Targeted instructions focus guidance on part of the codebase. Skills package recurring workflows, and custom agents define specialized roles with harness-specific capabilities. You can adopt each layer independently as your repository's needs grow.

Review and share any optional customization files through the same process as the project instructions. Include a skill's supporting resources so other contributors can use it.

Next steps

9/30/2026