> AI agents: For documentation discovery and navigation, see [llms.txt](/llms.txt).


# 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](/docs/agents/concepts/customization.md).

## Prerequisites

* [Download and install Visual Studio Code](/download).
* Complete the [setup and authentication for your harness](/docs/agents/run/agent-harnesses.md#requirements-and-setup).
* Open the repository root that you want to configure.
* [Start a session](/docs/agents/run/agent-harnesses.md#select-a-harness) and select **Copilot**, **Claude**, or **Codex** from the **Session Target** UI control. Use the same harness when creating and testing its customizations.

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 harness-specific configuration, see [custom instructions](/docs/agent-customization/custom-instructions.md), [agent skills](/docs/agent-customization/agent-skills.md), and [custom agents](/docs/agent-customization/custom-agents.md).

## 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](/docs/agents/guides/add-a-feature.md) 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](/docs/agent-customization/overview.md#agent-customizations-editor) for the selected harness. In the Chat view, run **Chat: Open Customizations** from the Command Palette (`kb(workbench.action.showCommands)`).

1. In the **Overview** section, enter the prompt for your harness below and press `kbstyle(Enter)` to submit it.

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

1. 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.

{% tabs id="customization-harness" %}
{% tab label="Copilot" %}

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

```prompt
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.
```

{% /tab %}
{% tab label="Claude" %}

Use `CLAUDE.md` at the repository root for project-wide instructions.

```prompt
Analyze this codebase and create or update CLAUDE.md at the repository root 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.
```

{% /tab %}
{% tab label="Codex" %}

Use `AGENTS.md` at the repository root for project-wide instructions.

```prompt
Analyze this codebase and create or update AGENTS.md at the repository root 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.
```

{% /tab %}
{% /tabs %}

> [!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:

```markdown
## 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](/docs/agent-customization/custom-instructions.md).

<a name="step-3-verify-the-improvement"></a>

## 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.
1. Start a new chat with the same harness and repository so the comparison doesn't rely on guidance from the creation conversation.
1. Expand **References** in the response and confirm that the expected instructions were included.
1. Repeat the representative task with the same success criterion.
1. 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](/docs/agents/agent-troubleshooting/troubleshooting.md) 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](/docs/agents/guides/optimize-usage.md#inspect-token-usage-and-caching).

## 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.

<a name="step-5-add-targeted-instructions"></a>

## 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.

{% tabs id="customization-harness" %}
{% tab label="Copilot" %}

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

```yaml
---
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](/docs/agent-customization/custom-instructions.md#use-instructionsmd-files).

{% /tab %}
{% tab label="Claude" %}

Create `.claude/rules/frontend.md`. Claude uses `paths` rather than `applyTo` for path-scoped rules:

```yaml
---
paths:
  - "**/*.tsx"
---
```

Review the pattern and test the rules by asking the agent to make a small change to a specific matching file. Without `paths`, the rule file applies generally rather than only to matching files.

Learn more about [Claude path-specific rules](https://code.claude.com/docs/en/memory#path-specific-rules).

{% /tab %}
{% tab label="Codex" %}

Use an `AGENTS.md` file in the directory that needs its own guidance, such as `packages/frontend/AGENTS.md`. Codex discovers instructions from the repository root down to the session's working directory. This is directory-based guidance, not an `applyTo` or `paths` glob.

To test the nested instructions, start a new Codex harness session with that subdirectory as its working folder. Opening a file in the editor doesn't change the session's working directory.

Learn more about [Codex instruction discovery](https://developers.openai.com/codex/guides/agents-md).

{% /tab %}
{% /tabs %}

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.

<a name="step-6-package-a-recurring-workflow"></a>

## 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:

{% tabs id="customization-harness" %}
{% tab label="Copilot" %}

```prompt
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.
```

{% /tab %}
{% tab label="Claude" %}

```prompt
Create a workspace skill named validate-change at .claude/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.
```

{% /tab %}
{% tab label="Codex" %}

```prompt
Create a workspace skill named validate-change at .agents/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.
```

{% /tab %}
{% /tabs %}

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.
1. Review any scripts, templates, or other resources in the skill directory, and save your changes.
1. 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.
1. 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](/docs/agent-customization/agent-skills.md).

<a name="step-7-add-a-specialized-agent"></a>

## 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:

{% tabs id="customization-harness" %}
{% tab label="Copilot" %}

```prompt
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.

{% /tab %}
{% tab label="Claude" %}

```prompt
Create a workspace custom agent named researcher at .claude/agents/researcher.md. It should trace how features work and report findings with file locations, without changing the repository. Restrict its tools to Read, Grep, and Glob.
```

Review the generated agent's `tools` frontmatter to confirm that it limits the agent to those reading and search tools. Learn more about [Claude custom agents and tool access](https://code.claude.com/docs/en/sub-agents#available-tools).

{% /tab %}
{% tab label="Codex" %}

```prompt
Create a workspace custom agent named researcher at .github/agents/researcher.agent.md for Codex in VS Code. It should trace how features work and report findings with file locations. Instruct it not to edit files or run commands that change the repository.
```

The Codex integration in VS Code loads the role instructions from this file, but doesn't use its `tools` frontmatter as a tool allowlist. Treat the no-edit instruction as guidance, not enforcement. Review [Codex permissions](/docs/agents/run/agent-harnesses.md#codex) before using the agent.

{% /tab %}
{% /tabs %}

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.
1. Start a new chat with the same harness and repository, and select **researcher** from the agents dropdown.
1. Ask it to research how a feature works. Check that it identifies relevant files, supports findings with evidence, and follows its configured role.
1. Review any changes and tool activity rather than assuming the agent's name or instructions make it read-only.

Learn more about [custom agents](/docs/agent-customization/custom-agents.md).

## 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.

{% tabs id="customization-harness" %}
{% tab label="Copilot" %}

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

{% /tab %}
{% tab label="Claude" %}

```text
your-project/
  CLAUDE.md
  .claude/
    rules/
      frontend.md
    skills/
      validate-change/
        SKILL.md
    agents/
      researcher.md
```

{% /tab %}
{% tab label="Codex" %}

```text
your-project/
  AGENTS.md
  packages/
    frontend/
      AGENTS.md
  .agents/
    skills/
      validate-change/
        SKILL.md
  .github/
    agents/
      researcher.agent.md
```

{% /tab %}
{% /tabs %}

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

* [Create and manage customizations](/docs/agent-customization/overview.md) from the Agent Customizations editor.
* Add [MCP servers](/docs/agent-customization/mcp-servers.md) to connect the agent to external tools and services.
* Set up [hooks](/docs/agent-customization/hooks.md) when an action must run at a specific agent lifecycle event.