Skip to content

Add README best practices rule #183

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
ofershap wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Add README best practices rule #183

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 @@ -274,6 +274,7 @@ By creating a `.cursorrules` file in your project's root directory, you can leve
- [Graphical Apps Development](./rules/graphical-apps-development-cursorrules-prompt-file/.cursorrules) - Cursor rules for graphical apps development with integration.
- [Meta-Prompt](./rules/meta-prompt-cursorrules-prompt-file/.cursorrules) - Cursor rules for meta-prompt development with integration.
- [Next.js (Type LLM)](./rules/next-type-llm/.cursorrules) - Cursor rules for Next.js development with Type LLM integration.
- [README Best Practices](./rules/readme-best-practices-cursorrules-prompt-file/.cursorrules) - Cursor rules for README documentation with best practices integration.
Copy link
Contributor

@coderabbitai coderabbitai bot Mar 2, 2026

Choose a reason for hiding this comment

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

⚠️ Potential issue | 🟡 Minor

Move this rule to the Documentation category.

README Best Practices is documentation-centric and should be listed under ### Documentation, not ### Other, to keep category semantics accurate.

♻️ Proposed fix 
@@
-- [README Best Practices](./rules/readme-best-practices-cursorrules-prompt-file/.cursorrules) - Cursor rules for README documentation with best practices integration.
@@
 ### Documentation
 
 - [Gherkin Style Testing](./rules/gherkin-style-testing-cursorrules-prompt-file/.cursorrules) - Cursor rules for Gherkin style testing development with integration.
 - [How-To Documentation](./rules/how-to-documentation-cursorrules-prompt-file/.cursorrules) - Cursor rules for how-to documentation development with integration.
+- [README Best Practices](./rules/readme-best-practices-cursorrules-prompt-file/.cursorrules) - Cursor rules for README documentation with best practices integration.

As per coding guidelines: "Update the README.md file when adding new .cursorrules files, placing them in the correct category."
Based on learnings: "Update the README.md file when adding new .cursorrules files, placing them in the correct category."

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@README.md` at line 277, Move the README rule entry "[README Best
Practices](./rules/readme-best-practices-cursorrules-prompt-file/.cursorrules)"
out of the "### Other" section and add it under the "### Documentation" section
in README.md; specifically, remove the line currently listed under Other and
insert the same markdown list item into the Documentation category so the rule
is documented under the correct heading.

- [Unity (C#)](./rules/unity-cursor-ai-c-cursorrules-prompt-file/.cursorrules) - Cursor rules for Unity development with C# integration.
- [Web App Optimization](./rules/web-app-optimization-cursorrules-prompt-file/.cursorrules) - Cursor rules for web app development with optimization integration.
- [Code Pair Interviews](./rules/code-pair-interviews/.cursorrules) - Cursor rules for code pair interviews development with integration.
Expand Down
11 changes: 11 additions & 0 deletions rules/readme-best-practices-cursorrules-prompt-file/.cursorrules
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
Write READMEs like landing pages, not API docs. The reader decides in 3-5 seconds.

Start with a bold one-liner saying what it does and why someone should care. Not "A tool that..." - a punchline.
Put a working code example in the first 5 lines. Show the value prop immediately.
Use feature tables (two columns) instead of **Feature:** bullet lists. Tables scan faster.
Quick Start must be copy-paste ready. No $ prefix on bash commands. Zero to running in 30 seconds.
Vary sentence lengths and structure. Mix one-liners with short paragraphs and tables. Not walls of same-length bullets.
Never use "seamless", "robust", "comprehensive", "cutting-edge", or other AI marketing words.
Never open with "In today's..." or close with "Happy coding!"
Check that referenced assets (demo.gif, screenshots) actually exist on disk before adding image links.
Author section should include a visual card or badge, not just plain text "Made by username".