docs(rules): define rule priority for language-specific vs common rule conflicts (fixes #236)#277
Conversation
…s common rule conflicts Added section on rule priority and examples of overrides.
📝 WalkthroughWalkthroughDocumentation update to Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
There was a problem hiding this comment.
Pull request overview
This PR resolves issue #236 by adding documentation that defines how language-specific rules interact with common rules when conflicts arise. The documentation establishes a clear precedence model where language-specific rules override common rules, following a "specific overrides general" principle.
Changes:
- Added a "Rule Priority" section clarifying that language-specific rules take precedence over common rules when they conflict
- Included an example demonstrating how language-specific rules can override immutability guidelines from common rules
- Documented a convention for marking common rules that may be overridden by language-specific implementations
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| @@ -1,5 +1,4 @@ | |||
| # Rules | |||
There was a problem hiding this comment.
The blank line after the main heading has been removed. This change appears unintentional and should be restored to maintain consistency with the original formatting. There should be a blank line between the main heading and the Structure section heading.
| # Rules | |
| # Rules |
| ### Example | ||
|
|
||
| `common/coding-style.md` recommends immutability as a default principle. A language-specific `golang/coding-style.md` can override this: | ||
|
|
There was a problem hiding this comment.
The example quote provided here is hypothetical and does not exist in the actual golang/coding-style.md file. The current golang/coding-style.md file does not contain any content about pointer receivers, mutation, or immutability overrides. Consider either:
- Using a different, real example from existing language-specific files, or
- Clearly marking this as a hypothetical example by adding "For example, a language-specific file could include:" before the quoted text.
| For example, a language-specific file could include: |
| 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. |
There was a problem hiding this comment.
The documentation describes a "Language note" pattern that should be used in common rules to indicate when they may be overridden. However, this pattern does not currently exist in any of the common rule files. This creates a discrepancy between the documented convention and the actual implementation. Consider either:
- Adding these language notes to the relevant common rule files (e.g., adding one to the immutability section in common/coding-style.md), or
- Rephrasing this section to indicate that this is a recommended convention for future additions, not an existing pattern.
| 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. | |
| When adding or updating rules in `rules/common/` that may need to be overridden by language-specific files, you should mark them with a note like: | |
| > **Language note**: This rule may be overridden by language-specific rules for languages where this pattern is not idiomatic. | |
| Existing common rules may not yet consistently use this pattern; treat it as a recommended convention for future additions and edits. |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (2)
rules/README.md (2)
85-85:.gitignoreanalogy is slightly imprecise.
.gitignoreprecedence is governed by directory proximity (a more local.gitignorewins), not by specificity in the CSS sense. Mentioning only CSS specificity would be cleaner and more accurate; alternatively, a layered config system (e.g.,~/.gitconfigvs repo-level.git/config) is a closer parallel.✏️ Suggested wording
-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). +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 layered Git config files).🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@rules/README.md` at line 85, Update the sentence that compares rule precedence to `.gitignore`/CSS: edit the line "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)." to remove the inaccurate `.gitignore` claim and instead either (A) keep the CSS specificity analogy only, or (B) replace `.gitignore` with a true layered-config example (e.g., `~/.gitconfig` vs repo-level `.git/config`) so the README accurately states that language-specific rules override common rules by layered precedence.
88-88: Hardcoded language list will become stale.Line 88 lists only
golang/,python/, andtypescript/. When a new language is added (as described in the "Adding a New Language" section), this bullet silently becomes incomplete. A generic reference avoids the maintenance burden.✏️ Suggested wording
-- `rules/golang/`, `rules/python/`, `rules/typescript/`, etc. override those defaults where language idioms differ. +- Language-specific directories (`rules/golang/`, `rules/python/`, `rules/typescript/`, etc.) override those defaults where language idioms differ.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@rules/README.md` at line 88, Replace the hardcoded language list phrase '`rules/golang/`, `rules/python/`, `rules/typescript/`' with a generic reference such as 'language-specific rule directories (e.g. `rules/<language>/`)' in the README; update the sentence that currently mentions those three directories so it uses a generic pattern to avoid becoming stale when new languages are added.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@rules/README.md`:
- Around line 92-94: The blockquote containing the example text starting with
"Idiomatic Go uses pointer receivers for struct mutation — see
[common/coding-style.md](../common/coding-style.md) ..." is being rendered as
live Markdown and producing a broken relative link; fix it by wrapping that
entire blockquote line in a fenced code block (add opening ``` before the
blockquote and closing ``` after) so the snippet is rendered verbatim like the
analogous example earlier, ensuring the link is not evaluated.
- Around line 96-100: The README claims rules in rules/common/ "are marked with"
a "**Language note**" override marker but none of the files (agents.md,
coding-style.md, git-workflow.md, hooks.md, patterns.md, performance.md,
security.md, testing.md) actually contain that marker; update either the files
to include the marker or change the README wording to a prescriptive form.
Specifically, either insert the "**Language note**: This rule may be
overridden..." marker into each of those common rule files (agents.md,
coding-style.md, git-workflow.md, hooks.md, patterns.md, performance.md,
security.md, testing.md) where applicable, or modify the README sentence that
currently reads "are marked with:" to "should be marked with:" so the README
accurately reflects the current state. Ensure consistency between README and the
content of rules/common/ and keep the exact marker text "**Language note**: This
rule may be overridden by language-specific rules..." when adding to files.
---
Nitpick comments:
In `@rules/README.md`:
- Line 85: Update the sentence that compares rule precedence to
`.gitignore`/CSS: edit the line "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)." to remove the inaccurate
`.gitignore` claim and instead either (A) keep the CSS specificity analogy only,
or (B) replace `.gitignore` with a true layered-config example (e.g.,
`~/.gitconfig` vs repo-level `.git/config`) so the README accurately states that
language-specific rules override common rules by layered precedence.
- Line 88: Replace the hardcoded language list phrase '`rules/golang/`,
`rules/python/`, `rules/typescript/`' with a generic reference such as
'language-specific rule directories (e.g. `rules/<language>/`)' in the README;
update the sentence that currently mentions those three directories so it uses a
generic pattern to avoid becoming stale when new languages are added.
| `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. |
There was a problem hiding this comment.
Broken relative link in the example blockquote.
The blockquote on line 94 is rendered as live Markdown. The link [common/coding-style.md](../common/coding-style.md) is evaluated relative to rules/README.md, resolving to common/coding-style.md at the repo root — a path that almost certainly does not exist. This will render as a broken link on GitHub.
The existing analogous example on line 79 correctly wraps the snippet in a fenced code block to prevent the relative link from being resolved. Apply the same treatment here:
✏️ Proposed fix
`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.
+```
+> 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.
+```📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| `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/coding-style.md` recommends immutability as a default principle. A language-specific `golang/coding-style.md` can override this: | |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@rules/README.md` around lines 92 - 94, The blockquote containing the example
text starting with "Idiomatic Go uses pointer receivers for struct mutation —
see [common/coding-style.md](../common/coding-style.md) ..." is being rendered
as live Markdown and producing a broken relative link; fix it by wrapping that
entire blockquote line in a fenced code block (add opening ``` before the
blockquote and closing ``` after) so the snippet is rendered verbatim like the
analogous example earlier, ensuring the link is not evaluated.
| ### 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. |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Check if any common rule files contain the "Language note" override marker
rg -n "Language note" rules/common/Repository: affaan-m/everything-claude-code
Length of output: 57
🏁 Script executed:
#!/bin/bash
# Verify the common directory exists and check what files are there
ls -la rules/common/ 2>/dev/null | head -20
# Also count the files
echo "---"
echo "Total files in rules/common/:"
find rules/common/ -type f -name "*.md" 2>/dev/null | wc -lRepository: affaan-m/everything-claude-code
Length of output: 715
README describes override marker convention as already implemented, but no common rule files contain it.
None of the 8 files in rules/common/ (agents.md, coding-style.md, git-workflow.md, hooks.md, patterns.md, performance.md, security.md, testing.md) contain the "Language note" override marker. Line 98's present tense ("are marked with") incorrectly implies the convention is already in place. Either update the common files to include the marker or revise the wording to "should be marked with" to reflect its prescriptive nature.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@rules/README.md` around lines 96 - 100, The README claims rules in
rules/common/ "are marked with" a "**Language note**" override marker but none
of the files (agents.md, coding-style.md, git-workflow.md, hooks.md,
patterns.md, performance.md, security.md, testing.md) actually contain that
marker; update either the files to include the marker or change the README
wording to a prescriptive form. Specifically, either insert the "**Language
note**: This rule may be overridden..." marker into each of those common rule
files (agents.md, coding-style.md, git-workflow.md, hooks.md, patterns.md,
performance.md, security.md, testing.md) where applicable, or modify the README
sentence that currently reads "are marked with:" to "should be marked with:" so
the README accurately reflects the current state. Ensure consistency between
README and the content of rules/common/ and keep the exact marker text
"**Language note**: This rule may be overridden by language-specific rules..."
when adding to files.
affaan-m
left a comment
affaan-m
left a comment
There was a problem hiding this comment.
Automated review: doc-only changes look good. Approving.
Description
Resolves #236
Adds a Rule Priority section to
rules/README.mdthat explicitly defines conflict resolution behavior betweenrules/common/and language-specific rule directories.Changes
## Rule Prioritysection torules/README.mdclarifying that language-specific rules take precedence over common rules (specific > general)golang/coding-style.mdcan override immutability rules fromcommon/coding-style.mdType of Change
docs:DocumentationSummary by CodeRabbit