CLAUDE.md vs Copilot Instructions: Sharing Project Rules
A practical comparison of CLAUDE.md and GitHub Copilot's custom instructions file: where each lives, its scope, how instructions are applied, and how to keep the decisions both tools need in one place.
Updated 5 min read
CLAUDE.md and GitHub Copilot's custom instructions file serve the same purpose — giving an AI coding assistant context about your project — but they live in different places, have different scope, and behave differently within each tool. If your team uses both Claude Code and GitHub Copilot, you need to maintain both, and keeping them consistent is the practical challenge.
Tools like fenbs can hold the project decisions and rules that both assistants need: the architectural choices, approved libraries, and standing rules that should apply regardless of which tool is doing the work. Each tool's instruction file then covers what is specific to it, while the shared facts live in one place both can read. This page explains the technical differences and how to structure both.
Quick comparison
| Feature | CLAUDE.md | Copilot instructions |
|---|---|---|
| Primary file path | Project root, parent directories, ~/.claude/CLAUDE.md (user-level) | .github/copilot-instructions.md in the repo root |
| Scope levels | User-level, project-level, folder-level (hierarchical) | Repository-level; also user-level custom instructions in VS Code settings |
| Read automatically | Yes — Claude Code reads all applicable files at session start | Yes — Copilot reads the file for requests in that repository |
| Versioned with code | Yes — the file is in the repository | Yes — the file is in .github/ in the repository |
| Format | Plain Markdown, any structure | Plain Markdown, any structure |
| Inheritance | Inherits from parent directories up to the user home | One file per repository; no cross-repo inheritance |
| Applies to | Claude Code sessions | GitHub Copilot suggestions, chat, and the Copilot cloud agent |
Where the files live
CLAUDE.md can exist at multiple levels. Claude Code reads a user-level file at ~/.claude/CLAUDE.md (personal instructions that apply everywhere), the project root file, and files in any parent directory between the current folder and the project root. This hierarchy lets you put shared workspace rules in a parent folder and project-specific rules in each project.
GitHub Copilot's repository instructions live at .github/copilot-instructions.md. There is no multi-level inheritance for repository instructions — one file covers the whole repository. Copilot also accepts user-level custom instructions in VS Code settings, which is similar to Claude Code's user-level CLAUDE.md. The GitHub Copilot documentation (opens in a new tab) covers the current options for each editor.
How instructions are applied
Claude Code reads CLAUDE.md files at the start of a session and treats them as instructions that apply throughout. You can include commands, rules, architectural constraints, and context about the project. The content is read as natural language; there is no schema or required format.
GitHub Copilot applies .github/copilot-instructions.md to suggestions, inline completions, and Copilot chat responses in that repository. The Copilot cloud agent (GitHub's coding agent, formerly Copilot Workspace) also reads the file when it works on issues and pull requests in the repository. The effect is similar — providing context that shapes the assistant's suggestions — but the surface is different. Copilot applies instructions to completions; Claude Code applies them to a full working session.
What to write in each file
The content that works in one file largely works in the other. Both tools respond to specific, concrete rules: naming conventions, banned patterns, test requirements, commands. The main difference is what each tool will act on.
In CLAUDE.md, you can include multi-step workflows, deployment procedures, and rules about which commands to run in sequence, because Claude Code handles full tasks across many files in a single session. In the Copilot instructions file, shorter and more targeted rules tend to work better, because Copilot applies them to individual completions and short chat answers rather than extended work sessions.
- Works well in both: naming conventions, preferred libraries, test framework, file structure rules.
- Better in CLAUDE.md: multi-step procedures, context about project history, rules about which commands to run and in what order.
- Better in Copilot instructions: short style preferences, completion-level guidance, specific language patterns to use or avoid.
Keep the rules both tools need in one place
Add your architectural decisions, approved libraries, and standing project rules to fenbs as Decisions and rules. Connect Claude Code and GitHub Copilot (where it supports MCP) to the same project, and both assistants read the same context. You update the rule once; both see the change.
Create a free accountFree for one person · No credit card · Works with Claude, ChatGPT, Cursor and more
Keeping the two files consistent
The practical problem with maintaining both files is drift. Your team updates CLAUDE.md when the test framework changes, but misses the Copilot instructions file. Or the naming convention in one file diverges from the other. An assistant working from stale instructions produces inconsistent code, and the inconsistency is hard to trace back to a mismatched instruction file.
One approach is to keep the shared rules in a common source — fenbs Decisions and rules — and treat each tool's instruction file as a view onto that source rather than the source itself. The instruction files cover tool-specific behavior (Claude Code commands, Copilot completion style), while fenbs holds the project rules that are authoritative regardless of which tool runs.
Another approach is to keep both files short and focused, with a comment in each pointing to where the full project rules live. A CLAUDE.md that starts with "See the fenbs project context for current decisions and rules" and a Copilot file that says the same gives each tool its tool-specific guidance without duplicating the full rule set.
Scope and team access
Both files are committed to the repository, so every team member who checks out the branch gets the same instructions. That is an advantage over tool-specific settings panels that exist only on one person's machine.
The user-level files — ~/.claude/CLAUDE.md and VS Code user settings for Copilot — are personal and not shared. They are the right place for preferences specific to one person's workflow, not for project rules the whole team should follow. Keep project rules in the repository files; keep personal preferences in the user-level files.
When one tool is enough
If your team uses only Claude Code, you only need CLAUDE.md. If you use only GitHub Copilot in your editor, you only need .github/copilot-instructions.md. Maintaining both files well requires effort; maintaining one well is better than maintaining both poorly.
The comparison in Claude Code vs Cursor vs Copilot covers the broader differences between the tools if you are still deciding which one fits your workflow best.
How to do this with fenbs
- Create a free account. Start a project and add the shared project rules — naming conventions, approved libraries, architectural constraints — as Decisions and rules.
- Write a lean CLAUDE.md that covers Claude Code-specific behavior: commands, multi-step procedures, and a pointer to fenbs for the current decisions.
- Write a lean
.github/copilot-instructions.mdthat covers Copilot-specific style preferences and a pointer to the same project decisions. - Connect Claude Code to fenbs from Integrations and ask it to read the project context at session start.
- When a project rule changes, update it in fenbs first, then update whichever instruction files reference it.
For examples of CLAUDE.md files from different project types, see CLAUDE.md examples. For Copilot instruction examples, see the Copilot instructions examples guide.