Merge pull request #277 from pangerlkr/docs/rule-priority-conflict-resolution

docs(rules): define rule priority for language-specific vs common rule conflicts (fixes #236)

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 <Language> 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.