Skip to content

Using platform rules

Browse platform profiles, pin a version, apply updates, and include platform refs in your own profiles.

Updated on 2026-06-15

Platform rules are curator-managed rule profiles published by the CodeCharter team. They provide versioned, ready-to-use rule sets you can reference directly from your CI pipeline without managing individual rules yourself.

What platform rules are and who maintains them

Platform profiles are published and maintained centrally by the CodeCharter team. You cannot edit them, but you can pin any published version and reference it in your .codecharter/config.yml. Each profile has an immutable slug in the codecharter/ namespace, for example codecharter/csharp-all, the umbrella profile that includes the full C# rule set.

Profiles: adoption tiers and add-ons

The platform rule set is organised as three nested adoption tiers plus a few focused add-on profiles, so you can start small and ratchet up:

Slug Display name Coverage
codecharter/recommended Recommended Start here: a small, high-signal set of real correctness hazards plus the naming and encapsulation rules nearly every C# team already follows
codecharter/standard Standard Recommended plus the mainstream naming, async, complexity, and API-design rules
codecharter/strict Strict Standard plus the more demanding metric, design, and style rules
codecharter/aspnetcore ASP.NET Core Add-on: ASP.NET Core controller, action, and routing conventions
codecharter/documentation Documentation Add-on: XML documentation-comment coverage
codecharter/conventions Method & Role Conventions Opt-in: role- and verb-based naming and method-shape conventions (a deliberate house style)
codecharter/csharp-all C# All Rules Umbrella: every built-in rule

The tiers nest: recommended ⊂ standard ⊂ strict. The add-ons combine with any tier — pick a tier, then add codecharter/aspnetcore for web projects or codecharter/documentation for libraries. codecharter/conventions is an opinion-heavy house style and is not part of the tiers; enable it only if you want those conventions. codecharter/csharp-all remains the umbrella that contains every rule.

The exact rule list of each profile is shown on its detail page under Platform rules in the portal. You reference any profile in your .codecharter/config.yml the same way:

# .codecharter/config.yml
version: 1
profiles: ["codecharter/[email protected]"]

Browsing profiles

Navigate to Platform rules in the sidebar (/platform-rules) to see all available platform profiles. Each card shows the profile slug, the display name, the latest published version, and the number of rules it contains. The Details button opens the profile page with two tabs: Current version lists the rules included in the latest version, and Version history lists all versions with their publish date, rule count, and status.

Pinning a platform profile version

To use a platform profile in your CI, copy the ready-made CI snippet and add it to your .codecharter/config.yml:

  1. Click Copy CI snippet on the profile card. The copied snippet already contains the profile's slug and latest version.
  2. Paste the snippet into your .codecharter/config.yml:
# .codecharter/config.yml
version: 1
profiles: ["codecharter/[email protected]"]
  1. Run codecharter update locally to refresh the lockfile. The command requires the portal URL and an API key with the read:rules scope (create one on the portal's API keys page):
codecharter update --portal-url https://<your-portal> --api-key <your-api-key>
  1. Commit .codecharter/config.yml and .codecharter/codecharter.lock.json together in a PR.

Place .codecharter/config.yml in your repository so that codecharter analyze picks it up. In CI, codecharter restore then downloads the profile based on the lockfile without querying the portal for version resolution. restore needs no API key -- it authenticates with your installed license. When the cache is missing, codecharter analyze runs an implicit restore automatically.

Updates: when and how to update

Platform profiles follow semantic versioning. When the curator publishes a new version, nothing happens automatically in your CI -- your lockfile is frozen. To move to a new version:

  1. Change the version in .codecharter/config.yml to the desired new version.
  2. Run codecharter update locally.
  3. Review the diff of new rules and merge the PR.

Patch releases (x.y.Z) are non-breaking. Minor releases (x.Y.0) may add rules that were not checked before. Major releases (X.0.0) may include breaking changes, for example removed or renamed rules.

Yanked versions

When the CodeCharter team retracts a version as defective (yank), the CLI prints a warning on the next codecharter update run:

warning: Profile <slug>@<version> was yanked. Reason: <reason>. Consider running `codecharter update` to move to the next version.

The warning does not block the command, and your build remains functional. We recommend updating to a non-yanked version promptly.

Including platform refs in your own profiles

You can use a platform profile as the foundation for your own profile. Open your profile in the editor and find the Platform profile dependencies section. Click Add platform profile… to open a picker where you reference a platform profile at a pinned version. The dependency then appears as a row showing its slug and pinned version.

To adjust individual rules from a platform profile, use your .codecharter/config.yml: the overrides section changes a rule's severity, and the ignore section switches a rule off entirely. Rules are addressed by their slug, which is unique across profiles:

# .codecharter/config.yml
version: 1
overrides:
  <rule-slug>:
    severity: warning
ignore:
  - rule: <other-rule-slug>

This lets you adopt platform standards as a baseline and add project-specific rules on top. See Configuration file for the full set of sections.

Further reading