From e78b8f25605863194f37ab34cc8428d0d80c841c Mon Sep 17 00:00:00 2001 From: Pangerkumzuk Longkumer <73515951+pangerlkr@users.noreply.github.com> Date: Tue, 24 Feb 2026 13:38:00 +0530 Subject: [PATCH] docs(rules): add Rule Priority section to resolve language-specific vs common rule conflicts Added section on rule priority and examples of overrides. --- rules/README.md | 20 +++++++++++++++++++- 1 file changed, 19 insertions(+), 1 deletion(-) diff --git a/rules/README.md b/rules/README.md index 57de9d38..10d8ef23 100644 --- a/rules/README.md +++ b/rules/README.md @@ -1,5 +1,4 @@ # Rules - ## Structure Rules are organized into a **common** layer plus **language-specific** directories: @@ -80,3 +79,22 @@ To add support for a new language (e.g., `rust/`): > This file extends [common/xxx.md](../common/xxx.md) with specific content. ``` 4. Reference existing skills if available, or create new ones under `skills/`. + +## Rule Priority + +When language-specific rules and common rules conflict, **language-specific rules take precedence** (specific overrides general). This follows the standard layered configuration pattern (similar to CSS specificity or `.gitignore` precedence). + +- `rules/common/` defines universal defaults applicable to all projects. +- `rules/golang/`, `rules/python/`, `rules/typescript/`, etc. override those defaults where language idioms differ. + +### Example + +`common/coding-style.md` recommends immutability as a default principle. A language-specific `golang/coding-style.md` can override this: + +> Idiomatic Go uses pointer receivers for struct mutation — see [common/coding-style.md](../common/coding-style.md) for the general principle, but Go-idiomatic mutation is preferred here. + +### Common rules with override notes + +Rules in `rules/common/` that may be overridden by language-specific files are marked with: + +> **Language note**: This rule may be overridden by language-specific rules for languages where this pattern is not idiomatic.