Optimize Copilot instructions for clarity and maintainability#1578
Merged
waldekmastykarz merged 6 commits intodotnet:mainfrom Mar 2, 2026
Merged
Conversation
Contributor
There was a problem hiding this comment.
Pull request overview
Reorganizes .github/copilot-instructions.md to separate non-obvious repo knowledge from general reference material, aiming to make Copilot guidance clearer and easier to maintain.
Changes:
- Restructures the instructions into “Critical (Non-Obvious)”, “Best Practices”, “Plugin Development”, “Commits & Releases”, “Testing Code Changes”, and “Reference (Architecture)”.
- Adds specific operational/testing guidance (ports set to
0, avoiding system proxy changes) and links to MCP best practices. - Reintroduces architecture/reference pointers (entry point, proxy engine, commands, config locations).
garrytrinder
approved these changes
Mar 2, 2026
Contributor
garrytrinder
left a comment
There was a problem hiding this comment.
Docs-only change. Reviewed content for accuracy — IStdioPlugin reference confirmed, external best-practices link verified. Better structure, more practical. LGTM.
- Reorganize sections: Critical (non-obvious) vs Reference (architecture) - Add best practices link and key points from MCP server docs - Add testing guidelines: use --as-system-proxy false --port 0 --api-port 0 - Add plugin development guidance (interface selection) - Add commit message and release conventions - Add M365/Azure auth workaround notes - Add cleanup instructions for log files Architecture sections kept for cache efficiency (free after first turn) while clearly separating non-discoverable critical info.
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
b5e8c27 to
cc184a0
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Reorganizes and improves the Copilot instructions file to better serve AI assistants working on this codebase.
Changes
Structure
~appFoldertoken, MCP server)New Content
--as-system-proxy false --port 0 --api-port 0to avoid conflicts (port 0 lets OS assign random available ports)IProxyPluginvsIStdioPlugin)Rationale
34 lines) removing "obvious" architecture info. However, with prompt caching, verbose instructions are essentially free after the first while code exploration has real cost every session. Added architecture back as "Reference" section, clearly separated from critical non-discoverable info.request
Testing
Verified
--port 0 --api-port 0behavior: OS correctly assigns random available ports (tested locally, proxy bound to ports 49977/49978).