One Repository, Two AI Assistants: Structuring Guidance for GitHub Copilot and Claude Code

Many development teams no longer rely on a single AI coding assistant.

GitHub Copilot may be the primary tool, while Claude Code handles deeper analysis, larger refactoring work, or a different perspective on a difficult problem. Other tools may enter the workflow over time, too.

This creates a documentation problem. If every assistant has its own complete set of project instructions, those instructions will eventually disagree.

The answer is not to copy the same guidance into several vendor-specific files. A better approach is to create one shared source of truth, then add small product-specific layers only where needed.

Start With Information the Repository Cannot Explain by Itself

An AI assistant can inspect a solution and discover project names, package references, and many implementation patterns. It cannot reliably discover why the team made a particular architectural decision or which apparent pattern should no longer be copied.

The most useful guidance documents the information that would otherwise require a conversation with an experienced team member:

• Where new features should be implemented.
• Which architectural boundaries must be preserved.
• Which older patterns are still present but should not be repeated.
• How to build, test, format, and validate a change.
• Which generated files must not be edited manually.
• How authentication, authorization, logging, and error handling are expected to work.
• Which commands provide acceptable evidence that work is complete.

This is more valuable than restating every detail visible in the code. Good AI guidance reduces ambiguity. It should not become an alternate copy of the repository.

Use AGENTS.md as the Shared Foundation

GitHub Copilot and current versions of Claude Code both support AGENTS.md as project guidance. That makes it a practical location for the standards that should apply regardless of which assistant a developer chooses.

A root file might cover the solution at a high level:

# Project overview

This solution is a .NET 10 application using ASP.NET Core,
Blazor, Entity Framework Core, and Azure-hosted services.

## Architecture

- Domain projects must not reference infrastructure projects.
- Use cases belong in the application layer.
- Database access must remain behind the existing data services.
- Do not introduce a second dependency-injection container.

## Validation

Run these commands before considering a change complete:

1. `dotnet restore`
2. `dotnet build --configuration Release --no-restore`
3. `dotnet test --configuration Release --no-build`

Report any command that could not be run and explain why.

## Change discipline

- Keep changes limited to the requested behavior.
- Do not modify generated files.
- Preserve public API compatibility unless the task explicitly permits a breaking change.
- Follow the patterns in the nearest maintained feature, not code marked as legacy.
    

The exact content will differ by solution, but the purpose should remain consistent: explain how a capable developer is expected to work in this repository.

Large solutions can also place additional AGENTS.md files closer to individual applications or directories. This allows a mobile project, web application, test project, or infrastructure area to add local guidance without forcing every instruction into the root file.

Keep Product-Specific Files Thin

A shared foundation does not mean every capability is identical.

GitHub Copilot supports repository-wide instructions in .github/copilot-instructions.md and path-specific files under .github/instructions/. Claude Code supports CLAUDE.md and path-scoped rules under .claude/rules/.

Those files should contain guidance that genuinely belongs to the corresponding tool. They should not become competing copies of the architecture and coding standards already defined in AGENTS.md.

For example, a repository might use this structure:

/
├── AGENTS.md
├── CLAUDE.md
├── .github/
│   ├── copilot-instructions.md
│   └── instructions/
│       └── razor.instructions.md
└── .claude/
    ├── rules/
    │   └── database-migrations.md
    └── skills/
        ├── create-ef-migration/
        │   └── SKILL.md
        └── review-blazor-component/
            └── SKILL.md
    

In this structure, AGENTS.md owns the shared truth. The other files add product-specific capabilities or scoping behavior.

Be Careful When Adding CLAUDE.md

Claude Code can use AGENTS.md directly when a project does not have a project-level CLAUDE.md. However, when both exist, Claude's default behavior may load the Claude file instead of the shared agent file.

If a project needs CLAUDE.md, explicitly import the shared guidance:

@AGENTS.md

# Claude Code additions

- Use plan mode before changes spanning more than one application.
- Ask before enabling or modifying project hooks.
- Use the project skills for migrations and component reviews when relevant.
    

This avoids silently creating two independent instruction systems. The shared file remains authoritative, while CLAUDE.md contains only the Claude-specific additions.

Move Repeatable Procedures Into Skills

Not every instruction belongs in an always-loaded project file.

A coding standard such as “use nullable reference types” applies broadly and belongs in shared guidance. A twelve-step procedure for creating and validating an Entity Framework Core migration is relevant only when someone is performing that task.

That fits better as an Agent Skill.

Both GitHub Copilot and Claude Code can discover skills stored under .claude/skills/. Each skill has its own directory containing a required SKILL.md file and, when useful, scripts, examples, or reference material.

---
name: create-ef-migration
description: Create and validate an EF Core migration. Use when a task changes the database model or requests a new migration.
---

# Create an EF Core migration

1. Identify the DbContext and startup project used by this solution.
2. Confirm the model change builds before creating the migration.
3. Create the migration using the documented project arguments.
4. Review both the generated Up and Down methods.
5. Generate the idempotent SQL script.
6. Flag destructive operations for human review.
7. Run the database-related test suite.

Never apply a migration to a shared or production database without explicit approval.
    

The description deserves particular attention because it helps the assistant decide when the skill is relevant. A vague description such as “database helper” provides very little routing value.

Skills also keep detailed procedures out of the permanent instruction context. The assistant can load the procedure when needed instead of carrying every deployment, migration, accessibility, and review checklist into every interaction.

Separate Guidance From Enforcement

An instruction file influences an AI assistant. It is not a security boundary or a guaranteed policy engine.

If a rule must always be enforced, place the enforcement in the development process:

• Use analyzers and compiler settings for code rules.
• Use automated tests for application behavior.
• Use formatting and linting tools for style.
• Use branch protection and required workflows for change control.
• Use secret scanning and permissions to protect sensitive resources.
• Use hooks carefully when deterministic agent lifecycle behavior is required.

The AI documentation should tell the assistant how to comply with these controls and how to run them. The controls themselves should remain independently verifiable.

Avoid the Documentation Traps

The most common failure is not a missing instruction file. It is an instruction system that becomes too large, repetitive, or contradictory to trust, which is the same issue we have with humans too!

A few tips help keep it useful:

• Do not duplicate shared rules. If architecture guidance is in AGENTS.md, link or import it instead of rewriting it.
• Keep instructions concrete. “Run this command” is more useful than “test thoroughly.”
• Document exceptions. Explain which legacy patterns should not be copied.
• Scope guidance narrowly. Use nested files, path-specific rules, or skills when a rule does not apply everywhere.
• Review changes like code. Instruction files can alter how agents modify the repository and deserve pull-request review.
• Test with both tools. Ask each assistant to explain the architecture, locate a feature, and describe the validation process before trusting the configuration.

It is also worth asking the assistant to cite which instruction files affected its answer. That provides a practical way to detect a file that was not discovered or a rule that is being interpreted unexpectedly.

A Practical Starting Structure

For a team using GitHub Copilot and Claude Code, I would start small:

1. Create a concise root AGENTS.md covering architecture, important paths, coding expectations, and verified build and test commands.
2. Add nested AGENTS.md files only where a project has meaningfully different requirements.
3. Create CLAUDE.md only when Claude-specific behavior is required, and import AGENTS.md from it.
4. Use .github/copilot-instructions.md only for Copilot-specific additions.
5. Place repeatable, task-oriented procedures in .claude/skills/ so both tools can use the same skill definitions.
6. Keep enforcement in builds, tests, analyzers, workflows, and permissions.
7. Review and test the guidance whenever the architecture or development process changes.

The objective is not to document every possible decision before an AI assistant begins working. It is to give every assistant the same reliable starting point and a clear way to find deeper guidance when the task requires it.

Teams already invest in onboarding developers, documenting architecture, and defining repeatable engineering practices. AI guidance should become another view into that same engineering system, not a parallel system maintained for each new tool.

One shared foundation, small product-specific adapters, and focused skills provide a structure that can support GitHub Copilot and Claude Code today without making the repository dependent on either one.

What tips have you learned from trying to steer your own projects and AI?