Skip to content

Add Reference First rule to Build Tools and Development #334

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

Open
southyang99 wants to merge 1 commit into
base: main
Choose a base branch
from
+26 −0
Open

Add Reference First rule to Build Tools and Development #334

Show file tree
Hide file tree
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
1 change: 1 addition & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -258,6 +258,7 @@ By adding selected `.mdc` files to `.cursor/rules/`, you can use these rules dir
- [Project Epic Template](https://github.com/PatrickJS/awesome-cursorrules/blob/main/rules/project-epic-template-cursorrules-prompt-file.mdc) - Project development with epic template integration.
- [Python Containerization](https://github.com/PatrickJS/awesome-cursorrules/blob/main/rules/python-containerization-cursorrules-prompt-file.mdc) - Python development with containerization integration.
- [Python (GitHub Setup)](https://github.com/PatrickJS/awesome-cursorrules/blob/main/rules/python-github-setup-cursorrules-prompt-file.mdc) - Python development with GitHub setup integration.
- [Reference First](https://github.com/PatrickJS/awesome-cursorrules/blob/main/rules/reference-first.mdc) - Scout a near- and far-domain reference and extract transferable structure before building anything new.
- [ROS / ROS2](https://github.com/PatrickJS/awesome-cursorrules/blob/main/rules/ros-ros2.mdc) - ROS and ROS2 packages, nodes, launch files, messages, services, actions, simulation, and testing.
- [Tauri (Svelte, TypeScript Guide)](https://github.com/PatrickJS/awesome-cursorrules/blob/main/rules/tauri-svelte-typescript-guide-cursorrules-prompt-f.mdc) - Tauri development with Svelte and TypeScript guide integration.
- [TypeScript Code Convention](https://github.com/PatrickJS/awesome-cursorrules/blob/main/rules/typescript-code-convention-cursorrules-prompt-file.mdc) - TypeScript development with code convention integration.
Expand Down
25 changes: 25 additions & 0 deletions rules/reference-first.mdc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
---
description: "Scout a pair of references (near-domain + far-domain) and extract transferable structure before building anything new"
globs: ["**/*"]
alwaysApply: false
---
# Reference First

Before building anything new, scout references first, then build. Force the step to happen and point the search in a useful direction; which references to pick and what to conclude stays with the user.

## When to trigger

Output a short "Reference Scouting Brief" BEFORE proposing a solution or writing code when: starting a new project or product, adding a new feature, interaction paradigm, or page type, or entering an unfamiliar domain (new algorithm, category, or platform convention).

Do NOT trigger for bug fixes, changes that follow an existing in-project pattern, or pure copy tweaks. When unsure, ask "should we run the reference step this time?" — do not trigger by default.
Comment on lines +8 to +14

@coderabbitai coderabbitai Bot Jul 17, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

Clarify the rule’s trigger precedence.

“Force the step to happen” conflicts with “do not trigger by default” and “the user can say skip references.” State one policy explicitly: trigger automatically only when the listed conditions match, ask when applicability is ambiguous, and always honor an explicit skip.

Also applies to: 23-25

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@rules/reference-first.mdc` around lines 8 - 14, Clarify the trigger policy in
the reference-scouting rule: run automatically only when a listed “When to
trigger” condition matches, ask whether to run it when applicability is
ambiguous, and always honor an explicit user request to skip references. Update
the introductory “Force the step to happen” wording and the corresponding
guidance in the later section so these precedence rules are consistent.


## The Reference Scouting Brief (5–8 lines, no longer)

1. What type to look for — pick 1–2 based on the core uncertainty: interaction pattern, information architecture, visual style, data structures and algorithms, copy tone, or pricing.
2. Where to look — comparable products, design libraries, open-source implementations, far-domain analogs.
3. Find a pair, not one: one near-domain reference plus one far-domain reference; state the analogy logic for the far one ("Y in domain X is structurally the same problem because…").
4. Comparison questions — what structure do both get right? which parts are transferable principle versus surface style? how have similar products actually fared?

## Discipline

Cap scouting at 2–3 searches; verify references with tools rather than memory; if nothing solid turns up, say so instead of padding. The user can say "skip references" at any time. Before building, compress the findings into 3–5 lines: what to steal, what to avoid, what to deliberately not copy.
Loading