Skip to content

File Structure

How your rule set is organized in the repo.

Updated on 2026-07-13

CodeCharter expects the rule set in a rules/ directory. Without --rules, the CLI first looks for rules/ in the current working directory and falls back to the rule set shipped alongside the CLI. Use the --rules <dir> option to point to any other directory.

rules/
├── architecture/
│   ├── domain-must-not-reference-web.ccr
│   └── repository-naming.ccr
├── naming/
│   ├── no-manager-suffix.ccr
│   ├── no-manager-suffix.spec.md
│   └── async-suffix.ccr
└── team-conventions/
    └── controller-action-limit.ccr
.codecharter/config.yml

Subdirectories under rules/ are freely chosen. CodeCharter reads all .ccr files recursively. Older .cgr files from before the rename from CodeGuard to CodeCharter are still read for backward compatibility, so existing repositories keep working without changes.

The rule ID is the file name without the .ccr extension; subdirectory names carry no meaning. These IDs are what .codecharter/config.yml entries and suppression comments reference, so avoid using the same file name in different folders.

Spec tests live as <rule-name>.spec.md next to the .ccr file and are discovered recursively by codecharter test.

Initializing rules/

codecharter init

Creates a rules/ directory with two example rules that you can grow from.

.codecharter/config.yml

The repository configuration lives at .codecharter/config.yml. Among other sections, ignore switches rules off (optionally limited to a namespace or matching entity names) and exclude removes whole paths from analysis:

version: 1
ignore:
  - rule: namespace-distance
    in: Acme.Generated
  - rule: async-suffix
exclude:
  - "**/tests/**"
  - "**/obj/**"

See Configuration file for all sections (profiles, parameters, severities, rule activation, and path scopes).

Inline Suppressions

Per location in code:

// codecharter-disable-next-line datetime-direct-usage
var migrationTimestamp = DateTime.UtcNow;

The rule ID in the comment must match the rule's file name exactly, including casing. See Suppressions for all variants.

Platform Profiles in the Repo

When you use platform profiles, you list them in .codecharter/config.yml, .codecharter/codecharter.lock.json lives in the .codecharter/ directory, and .codecharter/cache/ holds the downloaded rule bundles. With profiles configured, a local rules/ directory is optional.

Multi-Repo and Monorepo

In a monorepo you can have rules/ directories per sub-project and point to them with --rules. CodeCharter finds .codecharter/config.yml by walking up from the file being analysed, so a config at the repository root applies everywhere beneath it.