Evolution & Outlook
Design Evolution History
Phase 0: Rule Collection Stage (Initial)
The project initially operated in "awesome-list" style: a README file listing links to all rule files, users manually copying file content.
Problems:
- Uneven rule quality, no validation mechanism
- Poor rule discovery experience (just a text list)
- Inconsistent rule format, frontmatter fields added arbitrarily
Phase 1: Engineering Stage
Introduced validation scripts and structured catalog:
- Added
validate-rules.mjs, established frontmatter specification - Added
build-rule-catalog.mjs, generates structuredrules.json - VitePress site dynamically renders rule catalog from
rules.json
Key Decisions: Rule files remain in root directory (ADR-001), generated catalog not manually edited (ADR-002).
Phase 2: Presentation Layer Upgrade (Current Stage)
Evolved from a single "rule browser" to "technical whitepaper + learning center":
- Added four documentation sections: Getting Started, Architecture, Reference, Advanced Topics
- Fixed SVG icon light/dark mode compatibility issues (inline Vue components replacing
<img>tags) - Added Mermaid architecture diagrams, making system structure visual
- Added academic references and evolution documentation
Current Limitations
To be honest, the current version still has several areas worth improving:
Uneven Rule Content Quality
Some rule files have insufficient content depth, with overly generic conventions (like "use best practices" without guidance). Rule content quality assurance currently relies entirely on manual review.
Potential Improvement: Introduce LLM-assisted rule content evaluation, detecting vague expressions and providing improvement suggestions.
Lack of Rule Effectiveness Validation
Currently there's no mechanism to validate "whether rules actually changed AI behavior". Rule effectiveness relies entirely on empirical judgment.
Potential Improvement: Build benchmark test sets ("given rule + task, AI output should satisfy X conditions"), quantitatively evaluate rules.
Tool Binding
.mdc format is Cursor-specific. If developers switch to Continue.dev or GitHub Copilot, they need to manually convert rule formats.
Potential Improvement: Add format conversion scripts, supporting export of .mdc rules to .cursorrules, copilot-instructions.md and other formats.
Future Direction Thinking
Direction 1: Semantic Search for Rules
When the rule library grows to 100+ rules, keyword-based filtering will hit bottlenecks. Natural language semantic search ("find a rule suitable for my React + TypeScript project") can significantly improve discovery experience.
This requires:
- Vector embedding of rules
- Similarity search interface
- Or direct integration with RAG-capable AI interfaces
Direction 2: Automatic Rule Generation
Based on analysis of existing codebases (lint reports, PR review history, code style statistics), automatically suggest which rules should be added. This is the transition from "AI using rules" to "AI helping generate rules".
Direction 3: Community Rating Mechanism for Rules
Similar to npm download statistics, track usage frequency and community feedback for each rule, helping users identify "most recognized" rules.
Direction 4: Cross-Tool Rule Format Standardization
As mentioned earlier, AI coding rules field currently lacks cross-tool standards. If multiple tools (Cursor, Continue.dev, Copilot) can agree on a basic format, rules can be reused across tools, multiplying the value of rule libraries.
Archive-Grade Stability Principle
cursor-rules design philosophy has an important theme: Archive-Grade Stability.
This principle means:
- Choose technologies that don't rapidly depreciate over time (static sites over SPAs, standard HTML/CSS over frameworks)
- Avoid introducing high-maintenance dependencies
- Prioritize "will this repo still work in 10 years?"
This isn't conservatism, but a pragmatic judgment about "long-term benefits". A rule library's value lies in the rule content itself, not in how novel the tech stack displaying it is.
The best outcome of technology selection is "boring but reliable", not "exciting but requiring continuous maintenance".
Acknowledgments
cursor-rules design was inspired by the following open source projects:
- PatrickJS/awesome-cursorrules — Pioneer of the rules community
- VitePress — Elegant static documentation framework
- Mermaid — Making architecture diagrams code
Further Reading
- Related Work — Horizontal comparison of competitive approaches
- References — Theoretical foundation literature