Two files, one repository

dotnet/roslyn ships 2 formats across 5 indexed files. The question worth asking is whether the second one says anything the first does not.

CompareAGENTS.md ↔ Copilot instructions

A · AGENTS.md · 153 words B · .github/copilot-instructions.md · 1124 words

What each file covers, counted
Dimension	Shared	Only in A	Only in B	Overlap
Sections	0	3	15	0%
Commands	0	0	8	0%
Section tags	2	0	5	29%

What each file covers

Sections

0 shared · 3 only in A · 15 only in B

− Roslyn (.NET Compiler Platform) — AI Agent Instructions
− Where to find things
− Orientation protocol
+ Roslyn (.NET Compiler Platform) — Copilot Instructions
+ Project Overview
+ Project Structure
+ Build & Test
+ Build specific projects during development (preferred)
+ Run tests for modified code
+ Full build/test (final validation only)
+ Code Style
+ Agent Orientation
+ Memory
+ Doc Update Obligation
+ Skills
+ Working Loop (plan first)
+ Plan: <short title>
+ Validation Checklist

Commands

0 shared · 0 only in A · 8 only in B

+ dotnet 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 run --file eng/generate-compiler-code.cs
+ dotnet msbuild <proj> /t:UpdateXlf

Section tags

2 shared · 0 only in A · 5 only in B

+ test
+ code-style
+ architecture
+ performance
+ docs
build
agent-behaviour

Line diff

+130 added−18 removed6 unchanged4.4% identical

dotnet/roslyn · AGENTS.md

@@ −1 @@

1# Roslyn (.NET Compiler Platform) — AI Agent Instructions

3This file is intentionally thin. The canonical, repo-wide agent guidance lives in

4**[`.github/copilot-instructions.md`](.github/copilot-instructions.md)** — read it first.

5It covers the project overview, build/test entry points, global code style, the

6memory-first orientation protocol, and the doc-update obligation.

8## Where to find things

10- **Repo-wide rules & orientation:** [`.github/copilot-instructions.md`](.github/copilot-instructions.md)

11- **Knowledge base (load on demand):** [`.github/memory/INDEX.md`](.github/memory/INDEX.md) — the loading map; start here for architecture, conventions, file map, APIs, known issues, and testing.

12- **Area-specific rules (auto-applied by path):** [`.github/instructions/`](.github/instructions/)

13 - [`Compiler.instructions.md`](.github/instructions/Compiler.instructions.md) — `src/{Compilers,Dependencies,ExpressionEvaluator,Tools}`

14 - [`IDE.instructions.md`](.github/instructions/IDE.instructions.md) — `src/{Analyzers,CodeStyle,Features,Workspaces,EditorFeatures,VisualStudio,LanguageServer}`

15 - [`Razor.instructions.md`](.github/instructions/Razor.instructions.md) — `src/Razor`

16- **Task-specific skills:** [`.github/skills/`](.github/skills/) (auto-discovered; e.g. `code-review`, `ci-analysis`, `update-agent-docs`).

18## Orientation protocol

201. Read [`.github/copilot-instructions.md`](.github/copilot-instructions.md).

212. Read [`.github/memory/INDEX.md`](.github/memory/INDEX.md) and load only the memory files relevant to your task.

223. The path-scoped instruction file for the area you're editing applies automatically — follow it.

234. After changing code, run the `update-agent-docs` skill to keep `.github/memory/` fresh.

dotnet/roslyn · .github/copilot-instructions.md

@@ +1 @@

1# Roslyn (.NET Compiler Platform) — Copilot Instructions

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.

5## Project Overview

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

16## Project Structure

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

33## Build & Test

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

43### Run tests for modified code

44```bash

45dotnet test <path/to/Specific.UnitTests.csproj>

46dotnet test <proj> --filter "FullyQualifiedName~MyTestClass"

47```

49Tests can take a while to build and run — monitor output and wait for completion unless you're confident a run is hung.

51### Full build/test (final validation only)

52```bash

53./build.sh # Build.cmd on Windows

54./test.sh # Test.cmd on Windows

55```

57Other entry points: `dotnet run --file eng/generate-compiler-code.cs` (regenerate Syntax/BoundNodes code), `dotnet msbuild <proj> /t:UpdateXlf` (refresh `.xlf` after `.resx` edits).

59## Code Style

61- 4-space indent for code; 2-space for project/XML/JSON. Never tabs. UTF-8-BOM, final newline for `*.cs`/`*.vb`.

62- **Blank lines must be completely empty** (no spaces/tabs); no trailing whitespace — both are hard lint failures.

63- Private fields `_camelCase`; namespaces `Microsoft.CodeAnalysis.[Language].[Area]`.

64- 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.)

65- Language services are exported **per-language** (`[ExportLanguageService(..., LanguageNames.CSharp), Shared]`), never shared across C#/VB.

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

67- Update `PublicAPI.Unshipped.txt` for public API changes. Never hand-edit generated code or `eng/common`.

69Full conventions: `.github/memory/CONVENTIONS.md` and `.github/instructions/{Compiler,IDE,Razor}.instructions.md`.

71## Agent Orientation

73When starting any task or answering any question about this repo:

741. **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.

752. **For any non-trivial task, also read `.github/memory/ARCHITECTURE.md` and `.github/memory/CONVENTIONS.md`** as your baseline.

763. **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 **known issues** and **test conventions**, load `.github/memory/known-issues/<area>.md` and `.github/memory/testing/<area>.md` on demand (see the INDEX loading map).

774. After completing work, run the `update-agent-docs` skill.

79### Memory

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

83**Memory freshness is your responsibility.** Files can drift from the code:

84- **Always cross-check memory claims against actual code** before relying on them.

85- **If a memory file is stale, fix it immediately.** If you learn something worth keeping, write it to `.github/memory/` immediately.

87### Doc Update Obligation

89Every task that changes code must end with a doc pass:

90- Added or moved files? → Update `.github/memory/FILE_MAP.md` (top-level) and the matching `.github/instructions/<area>.instructions.md` (directory detail).

91- Changed a public interface, diagnostic ID, or API? → Update the relevant `.github/instructions/<area>.instructions.md` and `PublicAPI.Unshipped.txt`.

92- Hit something surprising or undocumented? → Repo-wide → `.github/memory/KNOWN_ISSUES.md`; layer-specific → `.github/memory/known-issues/<area>.md`.

93- Established a new pattern? → Repo-wide → `.github/memory/CONVENTIONS.md`; layer-specific → the matching `.github/instructions/<area>.instructions.md`.

94- Changed test base classes or conventions? → Repo-wide layout → `.github/memory/TESTING_STRATEGY.md`; layer-specific → `.github/memory/testing/<area>.md`.

95- Added/removed/renamed a memory file? → Update `.github/memory/INDEX.md`.

97### Skills

99Skills 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`.

100

101## Working Loop (plan first)

102

103For 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.

104

105Write 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.

106

107**Plan template** (drop unneeded fields):

108

109```markdown

110## Plan: <short title>

111

112- **Scope:** what this change will do.

113- **Non-goals:** what this change explicitly will NOT do.

114- **Affected areas:** projects/files/layers touched (e.g. `src/Compilers/CSharp`, matching `.instructions.md`).

115- **Approach:** the intended implementation, and any alternatives considered/rejected.

116- **Acceptance:** observable done-state — the behavior/tests that prove it works.

117- **Validation:** exact build + targeted test commands you'll run (see Build & Test).

118```

119

120**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.

121

122Then 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 Validation Checklist below passes) is the work "done."

123

124Trivial changes don't need a written plan — go straight to the Validation Checklist.

125

126## Validation Checklist

127

128When making changes:

1291. **Read `.github/memory/INDEX.md` first.**

1302. For non-trivial tasks, read `ARCHITECTURE.md` and `CONVENTIONS.md`, and the `.github/instructions/<area>.instructions.md` for the area you're editing.

1313. **Build the specific project(s) modified** (`Compilers.slnf` / `Ide.slnf` / `Razor.slnf` / the project).

1324. **Run targeted tests** for affected test project(s).

1335. If you edited a `.resx`, run `/t:UpdateXlf`; if you edited Syntax/BoundNodes XML, regenerate code. Update `PublicAPI.Unshipped.txt` for public API changes.

1346. Follow existing patterns in similar files.

1357. **Doc pass** (mandatory) — run the `update-agent-docs` skill and apply the Doc Update Obligation above.

136

@@ −1 +1 @@

1−# Roslyn (.NET Compiler Platform) — AI Agent Instructions

1+# Roslyn (.NET Compiler Platform) — Copilot Instructions

3−This file is intentionally thin. The canonical, repo-wide agent guidance lives in

4−**[`.github/copilot-instructions.md`](.github/copilot-instructions.md)** — read it first.

5−It covers the project overview, build/test entry points, global code style, the

6−memory-first orientation protocol, and the doc-update obligation.

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.

8−## Where to find things

5+## Project Overview

10−- **Repo-wide rules & orientation:** [`.github/copilot-instructions.md`](.github/copilot-instructions.md)

11−- **Knowledge base (load on demand):** [`.github/memory/INDEX.md`](.github/memory/INDEX.md) — the loading map; start here for architecture, conventions, file map, APIs, known issues, and testing.

12−- **Area-specific rules (auto-applied by path):** [`.github/instructions/`](.github/instructions/)

13− - [`Compiler.instructions.md`](.github/instructions/Compiler.instructions.md) — `src/{Compilers,Dependencies,ExpressionEvaluator,Tools}`

14− - [`IDE.instructions.md`](.github/instructions/IDE.instructions.md) — `src/{Analyzers,CodeStyle,Features,Workspaces,EditorFeatures,VisualStudio,LanguageServer}`

15− - [`Razor.instructions.md`](.github/instructions/Razor.instructions.md) — `src/Razor`

16−- **Task-specific skills:** [`.github/skills/`](.github/skills/) (auto-discovered; e.g. `code-review`, `ci-analysis`, `update-agent-docs`).

7+Roslyn 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).

1715

18−## Orientation protocol

16+## Project Structure

1917

20−1. Read [`.github/copilot-instructions.md`](.github/copilot-instructions.md).

21−2. Read [`.github/memory/INDEX.md`](.github/memory/INDEX.md) and load only the memory files relevant to your task.

22−3. The path-scoped instruction file for the area you're editing applies automatically — follow it.

23−4. After changing code, run the `update-agent-docs` skill to keep `.github/memory/` fresh.

18+```

19+src/

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/

29+eng/ # Arcade build engineering (eng/common is DARC-synced)

30+docs/ # Contributor & design docs

31+```

32+

33+## Build & Test

34+

35+### Build specific projects during development (preferred)

36+```bash

37+dotnet build Compilers.slnf # compilers only

38+dotnet build Ide.slnf # IDE only

39+dotnet build Razor.slnf # Razor compiler & tooling only

40+dotnet build <path/to/Project.csproj>

41+```

42+

43+### Run tests for modified code

44+```bash

45+dotnet test <path/to/Specific.UnitTests.csproj>

46+dotnet test <proj> --filter "FullyQualifiedName~MyTestClass"

47+```

48+

49+Tests can take a while to build and run — monitor output and wait for completion unless you're confident a run is hung.

50+

51+### Full build/test (final validation only)

52+```bash

53+./build.sh # Build.cmd on Windows

54+./test.sh # Test.cmd on Windows

55+```

56+

57+Other entry points: `dotnet run --file eng/generate-compiler-code.cs` (regenerate Syntax/BoundNodes code), `dotnet msbuild <proj> /t:UpdateXlf` (refresh `.xlf` after `.resx` edits).

58+

59+## Code Style

60+

61+- 4-space indent for code; 2-space for project/XML/JSON. Never tabs. UTF-8-BOM, final newline for `*.cs`/`*.vb`.

62+- **Blank lines must be completely empty** (no spaces/tabs); no trailing whitespace — both are hard lint failures.

63+- Private fields `_camelCase`; namespaces `Microsoft.CodeAnalysis.[Language].[Area]`.

64+- 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.)

65+- Language services are exported **per-language** (`[ExportLanguageService(..., LanguageNames.CSharp), Shared]`), never shared across C#/VB.

66+- 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`.

67+- Update `PublicAPI.Unshipped.txt` for public API changes. Never hand-edit generated code or `eng/common`.

68+

69+Full conventions: `.github/memory/CONVENTIONS.md` and `.github/instructions/{Compiler,IDE,Razor}.instructions.md`.

70+

71+## Agent Orientation

72+

73+When starting any task or answering any question about this repo:

74+1. **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.

75+2. **For any non-trivial task, also read `.github/memory/ARCHITECTURE.md` and `.github/memory/CONVENTIONS.md`** as your baseline.

76+3. **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 **known issues** and **test conventions**, load `.github/memory/known-issues/<area>.md` and `.github/memory/testing/<area>.md` on demand (see the INDEX loading map).

77+4. After completing work, run the `update-agent-docs` skill.

78+

79+### Memory

80+

81+`.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.

82+

83+**Memory freshness is your responsibility.** Files can drift from the code:

84+- **Always cross-check memory claims against actual code** before relying on them.

85+- **If a memory file is stale, fix it immediately.** If you learn something worth keeping, write it to `.github/memory/` immediately.

86+

87+### Doc Update Obligation

88+

89+Every task that changes code must end with a doc pass:

90+- Added or moved files? → Update `.github/memory/FILE_MAP.md` (top-level) and the matching `.github/instructions/<area>.instructions.md` (directory detail).

91+- Changed a public interface, diagnostic ID, or API? → Update the relevant `.github/instructions/<area>.instructions.md` and `PublicAPI.Unshipped.txt`.

92+- Hit something surprising or undocumented? → Repo-wide → `.github/memory/KNOWN_ISSUES.md`; layer-specific → `.github/memory/known-issues/<area>.md`.

93+- Established a new pattern? → Repo-wide → `.github/memory/CONVENTIONS.md`; layer-specific → the matching `.github/instructions/<area>.instructions.md`.

94+- Changed test base classes or conventions? → Repo-wide layout → `.github/memory/TESTING_STRATEGY.md`; layer-specific → `.github/memory/testing/<area>.md`.

95+- Added/removed/renamed a memory file? → Update `.github/memory/INDEX.md`.

96+

97+### Skills

98+

99+Skills 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`.

100+

101+## Working Loop (plan first)

102+

103+For 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.

104+

105+Write 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.

106+

107+**Plan template** (drop unneeded fields):

108+

109+```markdown

110+## Plan: <short title>

111+

112+- **Scope:** what this change will do.

113+- **Non-goals:** what this change explicitly will NOT do.

114+- **Affected areas:** projects/files/layers touched (e.g. `src/Compilers/CSharp`, matching `.instructions.md`).

115+- **Approach:** the intended implementation, and any alternatives considered/rejected.

116+- **Acceptance:** observable done-state — the behavior/tests that prove it works.

117+- **Validation:** exact build + targeted test commands you'll run (see Build & Test).

118+```

119+

120+**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.

121+

122+Then 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 Validation Checklist below passes) is the work "done."

123+

124+Trivial changes don't need a written plan — go straight to the Validation Checklist.

125+

126+## Validation Checklist

127+

128+When making changes:

129+1. **Read `.github/memory/INDEX.md` first.**

130+2. For non-trivial tasks, read `ARCHITECTURE.md` and `CONVENTIONS.md`, and the `.github/instructions/<area>.instructions.md` for the area you're editing.

131+3. **Build the specific project(s) modified** (`Compilers.slnf` / `Ide.slnf` / `Razor.slnf` / the project).

132+4. **Run targeted tests** for affected test project(s).

133+5. If you edited a `.resx`, run `/t:UpdateXlf`; if you edited Syntax/BoundNodes XML, regenerate code. Update `PublicAPI.Unshipped.txt` for public API changes.

134+6. Follow existing patterns in similar files.

135+7. **Doc pass** (mandatory) — run the `update-agent-docs` skill and apply the Doc Update Obligation above.

24136