Agent Rules

A collection of reusable rules and knowledge documents for AI coding assistants like Claude Code and Cursor.

Repository Structure

📁 project-rules/

Actionable rules for AI assistants to follow during development:

Development Workflows (Credit: @vincenthopf)

• commit.mdc - Standard commit with conventional format and emojis
• commit-fast.mdc - Fast commit workflow that auto-selects the first message
• add-to-changelog.mdc - Structured changelog updates following Keep a Changelog format
• pr-review.mdc - Multi-role pull request review checklist

Code Quality & Analysis

• check.mdc - Comprehensive code quality checks across different languages
• clean.mdc - Fix all formatting and linting issues
• code-analysis.mdc - Advanced multi-faceted code analysis options

Problem Solving & Implementation

• analyze-issue.mdc - GitHub issue analysis and implementation specification
• bug-fix.mdc - Complete bug-fixing workflow from issue to PR
• implement-task.mdc - Methodical task implementation approach
• five.mdc - Five Whys root cause analysis technique

Documentation & Visualization

• create-docs.mdc - Comprehensive documentation generation
• mermaid.mdc - Mermaid diagram generation for various visualizations

Project Setup & Meta

• context-prime.mdc - Load project context comprehensively
• create-command.mdc - Guide for creating new custom commands
• continuous-improvement.mdc - Systematic approach for improving AI assistant rules
• cursor-rules-meta-guide.mdc - Guidelines for creating and maintaining Cursor rules

Automation & Integration

• mcp-inspector-debugging.mdc - Debugging MCP servers with Inspector UI
• safari-automation.mdc - Advanced Safari browser automation techniques
• screenshot-automation.mdc - AppleScript patterns for automated screenshots

Language-Specific

• modern-swift.mdc - Modern SwiftUI architecture following Apple's latest best practices (Inspired by Dimillian's "Forget MVVM")

📁 docs/

Reference documentation and knowledge bases:

• Swift Development

  • swift-observable.mdc - Migration guide from ObservableObject to @Observable macro
  • swift-observation.mdc - Swift Observation framework documentation
  • swift-testing-api.mdc - Swift Testing framework API reference
  • swift-testing-playbook.mdc - Comprehensive guide for migrating to Swift Testing
  • swift-argument-parser.mdc - Swift Argument Parser framework documentation
  • swift6-migration.mdc - Guide for migrating to Swift 6 with concurrency

• MCP Development

  • mcp-best-practices.mdc - Best practices for building Model Context Protocol servers
  • mcp-releasing.mdc - Guide for releasing MCP servers as NPM packages

📁 global-rules/

Global Claude Code configuration and automation scripts (place in ~/.claude/CLAUDE.md):

• github-issue-creation.mdc - Creating well-structured GitHub issues (Credit: @nityeshaga)
• mcp-peekaboo-setup.mdc - Setup guide for Peekaboo vision-enabled MCP server
• terminal-title-wrapper.zsh - ZSH wrapper for dynamic terminal titles
• mcp-sync.sh - Script to sync MCP servers across Claude installations
• mcp-sync-rule.md - Documentation for MCP sync functionality

Usage

For Cursor Users

1. Copy any .mdc file from project-rules/ to your project's .cursor/rules/ directory
2. Cursor will automatically apply rules based on the glob patterns in the frontmatter
3. Rules with alwaysApply: true will be active for all files
4. Documentation from docs/ can be referenced or imported as needed

For Claude Code Users

1. Copy the content of any .mdc file (excluding the frontmatter) into your CLAUDE.md file
2. Or reference the entire file using the @import syntax in your CLAUDE.md
3. Place in your project root or ~/.claude/CLAUDE.md for global rules
4. Both project rules and documentation can be included

Global Claude Code Rules

These are powerful global rules that can be placed in ~/.claude/CLAUDE.md to enhance Claude Code's capabilities across all projects. Based on strategies from "Commanding Your Claude Code Army".

Available Global Rules

1. GitHub Issue Creation

Transforms feature descriptions into well-structured GitHub issues following best practices.

• Credit: @nityeshaga
• Features: Repository research, convention analysis, automatic gh issue create integration
• Usage: Provide a feature description and repository URL

2. MCP Server Setup - Peekaboo

Automated setup for the Peekaboo vision-enabled MCP server.

• Features: Screenshot capture with AI analysis, dual provider support (OpenAI/Ollama)
• Security: Secure API key extraction from ~/.zshrc
• Requirements: Node.js 20.0+, macOS 14.0+

3. Terminal Title Management

Dynamic terminal titles for better multi-instance organization.

• Features: Shows ~/path/to/project — Claude format
• Implementation: ZSH wrapper function (cly) with background title persistence
• Benefits: Easy identification of multiple Claude instances

Installation

1. Create Claude configuration directory:

2. Set up global rules:

   # Create or edit global CLAUDE.md
   nano ~/.claude/CLAUDE.md
   # Add desired rules from this repository

3. For terminal title management:

   # Copy wrapper script
   cp global-rules/terminal-title-wrapper.zsh ~/.config/zsh/claude-wrapper.zsh
   mkdir -p ~/.config/zsh
   # Add claude-wrapper.zsh content
   
   # Source in ~/.zshrc
   echo '[[ -f ~/.config/zsh/claude-wrapper.zsh ]] && source ~/.config/zsh/claude-wrapper.zsh' >> ~/.zshrc

Contributing

Feel free to contribute your own rules! Please ensure they:

1. Use the .mdc extension
2. Include proper YAML frontmatter with description, globs, and alwaysApply fields
3. Contain clear, actionable instructions
4. Are generic enough to be reused across projects
5. Are placed in the appropriate directory:
   • project-rules/ for actionable AI assistant rules
   • docs/ for reference documentation

Why This Format?

This repository uses the .mdc (Markdown with Configuration) format, which provides a unified approach that works seamlessly with both Claude Code and Cursor:

• Cursor natively supports .mdc files with YAML frontmatter for rule configuration
• Claude Code reads the markdown content, ignoring the frontmatter metadata
• The YAML frontmatter provides optional metadata (description, file globs, alwaysApply) that Cursor uses for intelligent rule application
• Standard markdown content ensures compatibility across different AI assistants

This unified format means you can use the same rule files in both tools without modification.

License

MIT License - See LICENSE for details