Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
affaan-m merged 1 commit into from
Feb 24, 2026
Merged

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

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 19 additions & 1 deletion rules/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,4 @@
# Rules
Copy link

Copilot AI Feb 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Suggested change
# Rules
# Rules

Copilot uses AI. Check for mistakes.

## Structure

Rules are organized into a **common** layer plus **language-specific** directories:
Expand Down Expand Up @@ -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:

Copy link

Copilot AI Feb 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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:

  1. Using a different, real example from existing language-specific files, or
  2. Clearly marking this as a hypothetical example by adding "For example, a language-specific file could include:" before the quoted text.
Suggested change
For example, a language-specific file could include:

Copilot uses AI. Check for mistakes.
> 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.
Comment on lines +92 to +94
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai Bot Feb 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

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.

Suggested change
`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.
Comment on lines +98 to +100
Copy link

Copilot AI Feb 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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:

  1. Adding these language notes to the relevant common rule files (e.g., adding one to the immutability section in common/coding-style.md), or
  2. Rephrasing this section to indicate that this is a recommended convention for future additions, not an existing pattern.
Suggested change
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.

Copilot uses AI. Check for mistakes.
Comment on lines +96 to +100
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai Bot Feb 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

🧩 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 -l

Repository: 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.

Loading