Best Practices

Working with the Template

This section outlines best practices for working with the Cursor Python Template to get the most out of its features.

Development Workflow

Using Cursor Effectively

To leverage the power of Cursor’s AI with this template:

1. Ask the AI for help: Cursor’s AI is aware of the project structure and rules - ask it questions about implementation approaches, code organization, or best practices.

2. Reference rules explicitly: When asking the AI for help, you can explicitly mention rule files:

   • “Following the Python rules, how should I handle exceptions in this function?”

   • “Based on the core rules, which design pattern would be appropriate here?”

   • “According to the testing rules, how should I test this component?”

3. Let the AI help with boilerplate: Use the AI to generate repetitive code patterns that follow the template’s rules.

4. Request rule-compliant reviews: Ask the AI to review your code for compliance with the rule files.

Project Organization

Following the Template Structure

1. Keep the directory structure clean:

   • Place all Python package code in src/your_package/

   • Put all tests in tests/ with similar structure to your package

   • Keep documentation in docs/

   • Use scripts/ for utility scripts and tools

2. Use proper packaging:

   • Maintain pyproject.toml as the central configuration

   • Define dependencies properly in pyproject.toml

   • Use __init__.py files appropriately

3. Maintain separation of concerns:

   • Keep UI separate from business logic

   • Separate data access from processing

   • Place utilities in appropriate modules

Code Quality

Maintaining High-Quality Code

1. Follow language-specific rules:

   • Python code should follow the guidelines in python-rules.mdc

   • PowerShell scripts should follow powershell-rules.mdc

2. Use consistent code formatting:

   • Consider using Black for Python code formatting

   • Use consistent indentation and naming conventions

   • Follow the style guidelines in the rule files

3. Write comprehensive tests:

   • Follow testing-rules.mdc guidelines

   • Maintain high test coverage

   • Test both happy paths and edge cases

   • Use fixtures and parameterized tests when appropriate

Documentation Practices

Keeping Documentation Current

1. Document as you code:

   • Add docstrings to all public functions, classes, and methods

   • Keep README up-to-date with current project status

   • Update Sphinx documentation with new features

2. Follow documentation standards:

   • Use Google-style docstrings for Python code

   • Include type annotations

   • Document parameters, return values, and exceptions

   • Provide usage examples for complex functions

3. Maintain living documentation:

   • Update documentation when code changes

   • Remove outdated documentation

   • Keep examples current with the latest API

Version Control

Git Best Practices

1. Follow commit message guidelines:

   • Use descriptive commit messages

   • Reference issue numbers when applicable

   • Follow the conventions in github-rules.mdc

2. Branch management:

   • Use feature branches for new features

   • Use bugfix branches for bug fixes

   • Keep main/master branch stable

   • Delete branches after merging

3. Pull request process:

   • Create descriptive PR titles and descriptions

   • Reference issues being addressed

   • Request appropriate reviewers

   • Address review comments promptly

Project Management

Tracking Project Progress

1. Use GitHub issues effectively:

   • Follow guidelines in github-issues-rules.mdc

   • Create appropriate issue types (epics, stories, tasks)

   • Use labels to categorize issues

   • Maintain issue relationships

2. Track progress in the project plan:

   • Follow project-plan-management-rules.mdc

   • Update status as tasks are completed

   • Document blockers and dependencies

   • Keep timelines current

3. Regular reviews:

   • Conduct code reviews for all changes

   • Review project plan regularly

   • Update documentation with each release

   • Refine rules based on project learnings

Getting Help

When you encounter issues with the template:

1. Consult the rules: Check the relevant rule files in .cursor/rules/ for guidance

2. Ask Cursor AI: The AI is familiar with the template and can help resolve issues

3. Check project documentation: This documentation may provide insights

4. Contribute improvements: If you find ways to improve the template, consider contributing back