copilot-instructions.md in dotnet/roslyn runs 1,473 words across 16 headings.
The Roslyn .NET compiler provides C# and Visual Basic languages with rich code analysis APIs.
C#Covers
8 of the 20 section tags
In the order a file is read inHeadings
16 headings, in the order the file writes them
01Roslyn (.NET Compiler Platform) — Copilot Instructions
02Project Overview
03Project Structure
04Build & Test
05Build specific projects during development (preferred)
06Run tests for modified code
07Full build/test (final validation only)
08Code Style
09Agent Orientation
10Memory
11Doc Update Obligation
12Skills
13Working Loop (plan first)
14Plan: <short title>
15Keep changes reviewable
16Definition of Done
Commands
9 commands this file writes down
Extracted from the file, verbatimdotnet build Compilers.slnf
dotnet build Ide.slnf
dotnet build Razor.slnf
dotnet build <path/to/Project.csproj>
dotnet test <path/to/Specific.UnitTests.csproj>
dotnet test <proj> --filter "FullyQualifiedName~MyTestClass"
dotnet build
dotnet run --file eng/generate-compiler-code.cs
dotnet msbuild <proj> /t:UpdateXlf
The file
.github/copilot-instructions.md
152 lines1# Roslyn (.NET Compiler Platform) — Copilot Instructions
2
3> This is the **canonical** repo-wide agent entry point. `AGENTS.md` at the repo root points here. Path-scoped rules in `.github/instructions/{Compiler,IDE,Razor}.instructions.md` apply automatically by area and supplement this file. This file establishes the memory-first orientation protocol and doc-maintenance obligation.
4
5## Project Overview
6
7Roslyn is the open-source C# and Visual Basic compilers plus the language services and IDE features built on their APIs. Built around **immutable** syntax trees, semantic models, symbols, and workspace snapshots. Major components:
8- **Compilers** (`src/Compilers/`) — C#/VB compilers (syntax, semantics, emit).
9- **Workspaces** (`src/Workspaces/`) — Solution/Project/Document model + MEF host.
10- **Features / EditorFeatures** (`src/Features/`, `src/EditorFeatures/`) — IDE features.
11- **Analyzers / CodeStyle** (`src/Analyzers/`, `src/CodeStyle/`) — IDE0xxx diagnostics & fixes.
12- **LanguageServer** (`src/LanguageServer/`) — LSP server.
13- **VisualStudio** (`src/VisualStudio/`) — VS integration.
14- **Razor** (`src/Razor/src/`) — Razor compiler & tooling (merged sub-tree).
15
16## Project Structure
17
18```
19src/
20 Compilers/ # C#/VB compilers (Core, CSharp, VisualBasic, Server)
21 Workspaces/ # Solution model, MSBuild loading, Remote (OOP)
22 Features/ # Language-agnostic IDE feature logic
23 EditorFeatures/ # Editor/text-buffer integration
24 Analyzers/ # IDE0xxx code-style analyzers & fixes
25 LanguageServer/ # LSP server
26 VisualStudio/ # VS language services & UI
27 Razor/src/ # Razor compiler + tooling (own layout)
28 ExpressionEvaluator/ Scripting/ Interactive/ RoslynAnalyzers/
29eng/ # Arcade build engineering (eng/common is DARC-synced)
30docs/ # Contributor & design docs
31```
32
33## Build & Test
34
35### Build specific projects during development (preferred)
36```bash
37dotnet build Compilers.slnf # compilers only
38dotnet build Ide.slnf # IDE only
39dotnet build Razor.slnf # Razor compiler & tooling only
40dotnet build <path/to/Project.csproj>
41```
42
43- In this repository, local `dotnet build` will not run analyzers by default. To include analyzers in the build, use the `-p:RunAnalyzersDuringBuild=true` flag to run them. Consider using this when searching for diagnostics you need to fix, or when you're doing a final build before creating a pull request.
44
45### Run tests for modified code
46```bash
47dotnet test <path/to/Specific.UnitTests.csproj>
48dotnet test <proj> --filter "FullyQualifiedName~MyTestClass"
49```
50
51Tests can take a while to build and run — monitor output and wait for completion unless you're confident a run is hung.
52
53### Full build/test (final validation only)
54```bash
55./build.sh # Build.cmd on Windows
56./test.sh # Test.cmd on Windows
57```
58
59- If you need build.sh to run analyzers, pass `--runAnalyzers`. If you need build.cmd to run analyzers, pass `-runAnalyzers`.
60
61Other entry points: `dotnet run --file eng/generate-compiler-code.cs` (regenerate Syntax/BoundNodes code), `dotnet msbuild <proj> /t:UpdateXlf` (refresh `.xlf` after `.resx` edits).
62
63## Code Style
64
65- 4-space indent for code; 2-space for project/XML/JSON. Never tabs. UTF-8-BOM, final newline for `*.cs`/`*.vb`.
66- **Blank lines must be completely empty** (no spaces/tabs); no trailing whitespace — both are hard lint failures.
67- Private fields `_camelCase`; namespaces `Microsoft.CodeAnalysis.[Language].[Area]`.
68- Always thread `CancellationToken` through async operations. (Null-checking style is layer-specific — see the area's instruction file: `Contract.ThrowIfNull` in IDE, `Debug.Assert` in the compiler.)
69- Language services are exported **per-language** (`[ExportLanguageService(..., LanguageNames.CSharp), Shared]`), never shared across C#/VB.
70- No `TODO`/`TODO2` comments — track follow-ups as linked GitHub issues in code; existing `TODO2`s are only a frozen enforcement baseline. No `PROTOTYPE` comments in PRs to `main`.
71- Update `PublicAPI.Unshipped.txt` for public API changes. Never hand-edit generated code or `eng/common`.
72- It is acceptable to have async methods with no awaits. CS1998 is not active for this repository.
73
74Full conventions: `.github/memory/CONVENTIONS.md` and `.github/instructions/{Compiler,IDE,Razor}.instructions.md`.
75
76## Agent Orientation
77
78When starting any task or answering any question about this repo:
791. **Read `.github/memory/INDEX.md` first** — it's the loading map for the knowledge base. Use it to find authoritative answers before searching the file system.
802. **For any non-trivial task, also read `.github/memory/ARCHITECTURE.md` and `.github/memory/CONVENTIONS.md`** as your baseline.
813. **Read the path-scoped instruction file for the area you're editing** — `.github/instructions/Compiler.instructions.md`, `IDE.instructions.md`, or `Razor.instructions.md` (these auto-apply to `.cs`/`.vb` under their glob and carry the layer's directory detail, conventions, and key files/APIs). For that layer's **test conventions**, load `.github/memory/testing/<area>.md` on demand (see the INDEX loading map).
824. After completing work, run the `update-agent-docs` skill.
83
84### Memory
85
86`.github/memory/` is your persistent knowledge base. You may freely create new focused files, update existing ones when you find corrections, and reorganize when structure no longer fits. Use descriptive filenames.
87
88**Memory freshness is your responsibility.** Files can drift from the code:
89- **Always cross-check memory claims against actual code** before relying on them.
90- **If a memory file is stale, fix it immediately.** If you learn something worth keeping, write it to `.github/memory/` immediately.
91
92### Doc Update Obligation
93
94Every task that changes code must end with a doc pass:
95- Changed a public interface, diagnostic ID, or API? → Update the relevant `.github/instructions/<area>.instructions.md` and `PublicAPI.Unshipped.txt`.
96- Hit something surprising or undocumented? → Ask the user how they want it documented.
97- Established a new pattern? → Repo-wide → `.github/memory/CONVENTIONS.md`; layer-specific → the matching `.github/instructions/<area>.instructions.md`.
98- Changed test base classes or conventions? → Repo-wide layout → `.github/memory/TESTING_STRATEGY.md`; layer-specific → `.github/memory/testing/<area>.md`.
99- Added/removed/renamed a memory file? → Update `.github/memory/INDEX.md`.
100
101### Skills
102
103Skills live in `.github/skills/<skill-name>/SKILL.md` and are auto-discovered by their YAML `description`. Useful ones here include `code-review`, `ci-analysis`, `analyzer-codefix`, `merge-into-branch`, `snap`, and `update-agent-docs`.
104
105## Working Loop (plan first)
106
107For any **non-trivial** change, start with a short plan **before** writing the implementing diff — and surface it so it can be reviewed before a large diff appears. "Non-trivial" means anything that is cross-file or cross-area, touches a public API / diagnostic ID / analyzer, changes behavior (not just a typo/comment/formatting fix), or where the approach isn't obvious. When in doubt, write the plan — it's cheap.
108
109Write the plan to `plan.md` in your session folder (see the session context) and keep it updated at milestones. A plan is a working artifact, not a deliverable: keep it lean.
110
111**Plan template** (drop unneeded fields):
112
113```markdown
114## Plan: <short title>
115
116- **Scope:** what this change will do.
117- **Non-goals:** what this change explicitly will NOT do.
118- **Affected areas:** projects/files/layers touched (e.g. `src/Compilers/CSharp`, matching `.instructions.md`).
119- **Approach:** the intended implementation, and any alternatives considered/rejected.
120- **Acceptance:** observable done-state — the behavior/tests that prove it works.
121- **Validation:** exact build + targeted test commands you'll run (see Build & Test).
122```
123
124**Post the plan and wait for approval before writing the implementing diff** — the plan is meant to be reviewed now, not after a large diff already exists.
125
126If a pull request already exists when work pauses for plan approval, update its description or add a comment that clearly states the implementation is **not complete**, summarizes what remains, and links to the Copilot session containing the plan and approval request so the user can provide further instructions.
127
128Then implement, keeping the diff **scoped and reviewable** — prefer the smallest change that fully addresses the task over a broad refactor. If the plan changes materially while implementing, update it rather than silently diverging. Only after the plan's **Acceptance** and **Validation** are satisfied (and the Definition of Done below passes) is the work "done."
129
130Trivial changes don't need a written plan — go straight to the Definition of Done.
131
132### Keep changes reviewable
133
134- Keep each change focused on one coherent concern. Do not mix behavior changes with unrelated cleanup, broad renames, or opportunistic refactoring.
135- Split work when parts can be reviewed, validated, merged, or reverted independently; when they affect unrelated areas or owners; or when a preparatory refactoring can land before the behavior change.
136- Checkpoint after each independently valid slice rather than accumulating one large unreviewed diff. Each checkpoint must build on the previous one and leave the branch in a coherent state.
137- Do not optimize for an arbitrary line-count limit: generated files and mechanical updates can be large. Optimize for reviewer cognitive load, clear intent, and independent validation.
138- If a change cannot be split without making it less correct or harder to validate, explain that constraint in the plan and keep the commits logically separated.
139
140## Definition of Done
141
142Work is done only when every applicable step below is complete:
143
1441. **Format:** Run the repository's existing formatter for changed files when applicable.
1452. **Lint/analyzers:** Run the smallest existing lint or analyzer command that covers the changed files when applicable.
1463. **Build:** Build the specific affected project or solution filter (`Compilers.slnf`, `Ide.slnf`, `Razor.slnf`, or the project). Documentation-only changes do not require a product build.
1474. **Targeted tests:** Run the affected test project or focused test filter. Add or update tests when behavior changes; explain when no relevant automated test exists.
1485. **Generated/resource/API updates:** Regenerate Syntax/BoundNodes outputs when their XML changes, run `/t:UpdateXlf` after `.resx` edits, and update `PublicAPI.Unshipped.txt` for public API changes.
1496. **Diff review:** Review the final diff and confirm it matches the approved plan, contains no unrelated edits, and follows nearby patterns.
1507. **Docs:** Run the `update-agent-docs` skill and apply the Doc Update Obligation above.
1518. **Final evidence:** Inspect repository status and the final diff, then report the exact validation performed. Do not claim completion while required validation is failing or was silently skipped.
152
The rest of the repository
dotnet/roslyn ships 5 other instruction files
.github/instructions/Compiler.instructions.md.github/instructions/IDE.instructions.md.github/instructions/Razor.instructions.mdAGENTS.mdeng/common/AGENTS.md
A row that is not a link is a file this repository ships that this app did not freeze a sheet for. It is listed because the corpus knows it exists, and it is not linked because there is nothing here to open.
This listing
Whoever runs dotnet/roslyn can claim it
This is yours? Claim this config and we will write to you when the measurement moves. The check is one token placed where only you can place it, and there is no account and no password.