Custom rules are what turn CodeCharter from a static checker into a team tool. Where you start depends on how familiar you already are with the DSL.
Writing your first custom rule
First custom rule in the quick-start
walks you through the full workflow: create the file, validate it,
drop it into ./rules/, run the analyzer. If you just want a working
setup to experiment with, codecharter init creates the rules/
directory for you with two example .ccr files. Older .cgr files
from before the CodeCharter rename are still read for backward
compatibility.
Getting to know the DSL
Hello-world DSL is the smallest meaningful
rule, explained line by line. From there, File structure
covers how to lay out the rules/ directory and Syntax overview
is the compact language reference.
Testing your rules
codecharter test runs .spec.md spec files of
expected hits and misses against a rule, with CI-friendly exit codes.
codecharter test <rule>.ccr --scaffold generates a starter spec next
to the rule file.
Going deeper
Once you are comfortable with the DSL, the next four pages are where the interesting material lives:
- DSL grammar: grammar reference in near-EBNF notation for the exact shape the parser accepts.
- Predicate catalog: full list of every property available on each code-model entity.
- Rule examples: a gallery of ready-to-copy rules grouped by use case.
- AI-assisted rule authoring: how the AI assistant in the editor writes rules and specs and hardens them against spec runs.
Offline access to this documentation
The rule-writing reference is also built into the CLI, so you can read
it in the terminal without opening a browser. codecharter docs lists
the four available topics (getting-started, dsl-grammar,
predicates, rule-examples); codecharter docs <topic> prints the
topic. Topic names are matched loosely, so a unique prefix or a close
misspelling is enough:
codecharter docs predicates
codecharter docs dsl --format plain
--format controls the output: md (default, raw Markdown), plain
(Markdown formatting stripped), or json (topic and content as a JSON
object, handy for tooling).
Editor and AI support
The VS Code extension adds
syntax highlighting and auto-completion for .ccr files. If you write
rules with an AI assistant, MCP rule authoring
covers the MCP server and its authoring tools (validate_rule,
scaffold_rule, dry_run_rule, test_rule_spec).
Sharing rules with your team
Finished rules are distributed through platform profiles.
Importing local rules
shows how to upload your .ccr files with codecharter push.
What makes a good rule
Best practices covers what separates good custom rules from bad ones.