Cursor Agent .cursorrules: A set of guidelines for consistent, high-quality project development

.cursorrules

// Cursor Agent .cursorrules
// A set of guidelines for consistent, high-quality project development

// AI Assistant Implementation Principles
// -------------------------------------
// Guidelines for how AI assistants should approach implementation tasks

- Progressive Development:

  - Implement solutions in logical stages rather than all at once
  - Pause after completing each meaningful component to check user requirements
  - Confirm scope understanding before beginning implementation

- Scope Management:

  - Implement only what is explicitly requested
  - When requirements are ambiguous, choose the minimal viable interpretation
  - Identify when a request might require changes to multiple components or systems
  - Always ask permission before modifying components not specifically mentioned

- Communication Protocol:

  - After implementing each component, briefly summarize what's been completed
  - Classify proposed changes by impact level: Small (minor changes), Medium (moderate rework), or Large (significant restructuring)
  - For Large changes, outline implementation plan before proceeding
  - Explicitly note which features are completed and which remain to be implemented

- Quality Assurance:

  - Provide testable increments when possible
  - Include usage examples for implemented components
  - Identify potential edge cases or limitations in implementation
  - Suggest tests that would verify correct functionality

- Balancing Efficiency with Control:
  - For straightforward, low-risk tasks, implement the complete solution
  - For complex tasks, break implementation into logical chunks with review points
  - When uncertain about scope, pause and ask clarifying questions
  - Be responsive to user feedback about process - adjust granularity of control based on user preference

// Project Structure
.cursorrules // This file - project guidelines
.cursor/plans // Markdown planning documents
.git // Version control
.github/workflows // CI/CD configuration
.git/hooks // Git hooks for quality enforcement
.gitmessage // Commit message template
README.md // Project documentation (description, installation, usage, etc.)
.gitignore // Language/framework specific exclusions
.editorconfig // Code style enforcement
.prettierrc // Code formatting rules
LICENSE // Project license information

// Documentation Guidelines
// -----------------------
// Documentation is a first-class citizen in this project

- Always use Markdown for documentation files
- README.md must include: project description, installation steps, usage examples, and architecture overview
- Create and maintain documentation before implementing features
- Document public APIs, configuration options, and important design decisions
- Include diagrams when they help explain complex systems

// Code Organization Guidelines
// ---------------------------

- Follow the principle of separation of concerns
- Group related functionality together
- Use consistent naming conventions throughout the project
- Keep files and functions focused on a single responsibility
- Organize code in a logical directory structure that reflects the domain
- Limit file size and function length for better readability

// Git Guidelines
// -------------
// Version control is MANDATORY for this project

- Initialize Git at project start
- REQUIRED: Commit after each significant feature implementation or bug fix
- REQUIRED: Commit after implementing any new functionality that passes tests
- REQUIRED: Commit before and after major refactoring
- Commit early and often with meaningful messages
- Write descriptive commit messages in present tense that explain what and why
- Format code before committing
- Use feature branches for new development
- Review code before merging to main branches
- Tag significant releases with version numbers
- Never leave significant changes uncommitted at the end of a work session

// Git Hooks Guidelines
// ------------------
// Pre-commit hooks enforce quality standards

- Use pre-commit hooks to enforce code quality standards
- Hooks MUST check for:
  - Code formatting (go fmt)
  - Static analysis (go vet)
  - Large files (>10MB)
  - Debug print statements
- All pre-commit checks must pass before allowing commits
- Keep hooks in version control to ensure consistent enforcement across all developers

// CI/CD Guidelines
// --------------
// Continuous Integration ensures code quality

- Set up GitHub Actions for continuous integration
- CI pipeline MUST run on every push and pull request
- CI pipeline MUST include:
  - Code formatting check
  - Static analysis
  - Unit tests
  - Integration tests with real data
- All CI checks must pass before merging to main branch
- Use CI artifacts to store test results and build outputs

// Commit Message Guidelines
// ----------------------
// Standardized commit messages improve project history

- Use a commit message template for consistency
- Commit messages MUST follow this format:
  - First line: Short summary (50 chars max)
  - Second line: Blank
  - Body: Detailed explanation (wrap at 72 chars)
  - Footer: References to issues/tickets
- Use imperative mood in commit messages (e.g., "Add feature" not "Added feature")
- Categorize commits with prefixes:
  - feat: New feature
  - fix: Bug fix
  - docs: Documentation changes
  - style: Formatting changes
  - refactor: Code restructuring
  - test: Test additions or modifications
  - chore: Maintenance tasks

// Testing Guidelines
// ----------------

- Practice test-driven development when possible
- Write tests before implementing features
- Start with simple tests that establish the basic functionality
- Refine tests as the implementation evolves
- Aim for comprehensive test coverage of critical paths
- Include unit, integration, and end-to-end tests as appropriate
- Use realistic test data or well-designed mocks

// Code Quality Guidelines
// ---------------------

- Follow established best practices for your programming language
- Use static analysis tools to catch common issues
- Perform code reviews to maintain quality
- Refactor regularly to improve code clarity and maintainability
- Optimize for readability and maintainability over cleverness
- Document complex algorithms and non-obvious solutions
- Handle errors and edge cases appropriately

// Performance Guidelines
// --------------------

- Consider performance implications during design
- Optimize only after functionality is correct and code is clean
- Use profiling to identify actual bottlenecks
- Document performance considerations and trade-offs
- Test performance under realistic conditions