agentleFS
Sign inStart free
Microsoft AzureKnown publisherAzure/CosmosDBShell/.github/copilot-instructions.md

CosmosDBShell

Copilot instructions4 starsChanged 9 days agoMITView on GitHub

  • Where files are headingNew Copilot instructions files have more rules about branches and pull requests, and fewer about code style.

    Of the Copilot instructions files we read, the 2,336 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.

The file

Show its rules and text

We split this copilot-instructions.md into the rules it gives an agent

19 rules. About 0 are common, 14 are distinctive, and 5 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈14

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 5

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Keep changes minimal and targeted.

    line 12
  2. Distinctive:

    Prefer clear names over abbreviations unless the command surface already established the shorthand.

    line 14
  3. Distinctive:

    Avoid adding comments unless they explain a non-obvious constraint or lifecycle detail.

    line 15
  4. Distinctive:

    When renaming a command, update all of the following together:

    line 25
  5. Distinctive:

    Keep help text aligned with the real CLI behavior.

    line 36
  6. Distinctive:

    If a CLI option changes, update both the localized help strings and the user documentation.

    line 37
  7. Distinctive:

    Keep README.md focused on end-user information: installation, quick start, capabilities, command usage, configuration, compatibility, and …

    line 41
  8. Distinctive:

    Do not add implementation details, internal lifecycle or cleanup behavior, SDK plumbing, or test details to README.md.

    line 42
  9. Distinctive:

    Before adding README text, identify what users can do differently or what they need to know because of it.

    line 43
  10. Very specific:

    Update the relevant docs in docs/, especially:

    line 44
  11. Very specific:

    Do not edit CHANGELOG.md in routine bugfix, feature, refactoring, or documentation PRs, including under ## Unreleased.

    line 51
  12. Very specific:

    Always retain ## Unreleased at the top of CHANGELOG.md and its permanent categories in this order: ### Breaking changes, ### New features, …

    line 54
  13. Distinctive:

    Put entries in the appropriate category.

    line 55
  14. Very specific:

    Add or update tests in CosmosDBShell.Tests/ when changing behavior.

    line 60
  15. Distinctive:

    Prefer focused command tests for command behavior changes.

    line 61
  16. Distinctive:

    If behavior changes, update tests and docs in the same change.

    line 76
  17. Very specific:

    When creating Git commits, do not add Copilot or AI Co-authored-by trailers.

    line 80
  18. Distinctive:

    Ensure commit messages are clear, concise, and follow the project's existing style.

    line 81
  19. Distinctive:

    Use the imperative mood in commit messages (e.g., "Add feature" instead of "Added feature").

    line 82

≈ “Common” is an estimate: at least 1 in 5 of the 3,779 Copilot instructions files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
copilot-instructions.md

GitHub Copilot Instructions

Project Overview

  • This repository is a C#/.NET CLI for Azure Cosmos DB shell workflows.
  • The main app lives in CosmosDBShell/.
  • Tests live in CosmosDBShell.Tests/.
  • Docs live in docs/ and the root README.md.

Coding Guidelines

  • Keep changes minimal and targeted. Do not refactor unrelated code while fixing a focused issue.
  • Match the existing C# style and file structure used in the surrounding code.
  • Prefer clear names over abbreviations unless the command surface already established the shorthand.
  • Avoid adding comments unless they explain a non-obvious constraint or lifecycle detail.

Commands

  • Shell commands live in CosmosDBShell/Azure.Data.Cosmos.Shell.Commands/.
  • New or changed commands should use the existing metadata attributes:
    • CosmosCommand
    • CosmosExample
    • CosmosOption
    • CosmosParameter
  • When renaming a command, update all of the following together:
    • command attribute name
    • examples
    • help/localization strings
    • docs
    • tests
    • class and file names when appropriate

Localization And Help Text

  • User-facing command descriptions and option descriptions are stored in CosmosDBShell/lang/en.ftl.
  • Keep help text aligned with the real CLI behavior.
  • If a CLI option changes, update both the localized help strings and the user documentation.

Documentation

  • Keep README.md focused on end-user information: installation, quick start, capabilities, command usage, configuration, compatibility, and actionable limitations. Update it only when a change affects information users need to understand or use the shell; not every user-visible bugfix requires a README edit.
  • Do not add implementation details, internal lifecycle or cleanup behavior, SDK plumbing, or test details to README.md. Put implementation rationale in the PR description or a necessary code comment.
  • Before adding README text, identify what users can do differently or what they need to know because of it. If neither applies, leave the README unchanged. Keep detailed usage and troubleshooting guidance in the relevant docs/ page and link from the README only when useful.
  • Update the relevant docs in docs/, especially:
    • docs/commands.md for command usage
    • docs/navigation.md for CLI arguments and shell navigation
    • docs/mcp.md for MCP behavior

Changelog And Release Preparation

  • Do not edit CHANGELOG.md in routine bugfix, feature, refactoring, or documentation PRs, including under ## Unreleased. Update it only when the user explicitly requests release preparation or a changelog update. This avoids conflicts between parallel PRs.
  • Record user-visible changes, breaking changes, migration guidance, and relevant issue links in the PR description instead. Continue updating directly relevant usage documentation and tests in the same PR; do not create per-change changelog fragments.
  • During release preparation, consolidate merged PRs since the previous release into user-facing changelog entries, reconciling any existing Unreleased entries without duplicates. Do not include unmerged changes.
  • Always retain ## Unreleased at the top of CHANGELOG.md and its permanent categories in this order: ### Breaking changes, ### New features, ### Fixes, ### Improvements, even when empty. Move the prepared entries into a dated version section below it.
  • Put entries in the appropriate category. Do not duplicate or reorder headings, reorder existing entries, or rewrite unrelated release history. Keep a blank line between sections.
  • See CONTRIBUTING.md for the contributor workflow.

Tests And Validation

  • Add or update tests in CosmosDBShell.Tests/ when changing behavior.
  • Prefer focused command tests for command behavior changes.
  • Validate changes with build at minimum:
    • dotnet build CosmosDBShell/CosmosDBShell.csproj
    • dotnet build CosmosDBShell.Tests/CosmosDBShell.Tests.csproj

Project-Specific Pitfalls

  • Be careful with state transitions in the shell. Some states share the same CosmosClient, so disposing the old state during navigation can break the new state.
  • Be careful with iterator lifetimes when returning IAsyncEnumerable<T>; do not dispose iterators before enumeration completes.
  • MCP in this repo is HTTP-only. The --mcp option optionally accepts a port and defaults to 6128.

Preferred Change Pattern

  • Fix root causes instead of patching symptoms.
  • Preserve public behavior unless the task explicitly changes the CLI or output contract.
  • If behavior changes, update tests and docs in the same change.

Commits

  • When creating Git commits, do not add Copilot or AI Co-authored-by trailers.
  • Ensure commit messages are clear, concise, and follow the project's existing style.
  • Use the imperative mood in commit messages (e.g., "Add feature" instead of "Added feature").
  • Reference relevant issues or pull requests in the commit message when applicable.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free