development-guidelines

Instruction file imported from Jianxun/yaml2plot (.cursor/rules/development-guidelines.mdc). Copyright stays with the author.

Python Project Development Guidelines

These guidelines establish a consistent approach for Python development using test-driven practices across multiple chat sessions. AI agents should reference these guidelines when:

• Planning work for new features or tasks
• Implementing test-driven development
• Maintaining cross-session continuity
• Performing code refactoring
• Troubleshooting failed tests
• Completing tasks and updating project context

This project follows a task-based and test-driven development approach across multiple chat sessions.

Development Workflow

1. Task Selection and Planning

• Start each session by reviewing the context/todo.md file
• Select a specific task from the Current Sprint section
• Break down complex tasks into smaller subtasks as needed

2. Test-Driven Development Cycle

• Write tests first that define the expected behavior
• Implement the minimum code needed to pass tests
• Run tests to verify functionality
• Refactor while maintaining test coverage

3. Focused Feature Development

CRITICAL RULE: When making modifications to existing code, follow these principles:

• Single Feature Focus: Edit only ONE focused feature at a time
• Immediate Test Verification: Run specific test cases for each feature to verify correctness
• Test-First Development: If no test case exists for the feature, create one before implementing
• Atomic Changes: Complete one feature entirely (code + tests + verification) before moving to the next
• Fail Fast: If any test fails, fix it immediately before proceeding to other features
• Progressive Development: Build features incrementally rather than making large bulk changes

Implementation Process:

1. Identify the specific feature to implement or fix
2. Create or locate the relevant test case
3. Run the test to establish baseline (should fail for new features)
4. Implement the minimal code to make the test pass
5. Run the test again to verify success
6. Only then move to the next feature

4. Python-Specific Practices

• Follow PEP 8 style guidelines
• Use type hints to improve code readability and IDE support
• Organize imports alphabetically with standard library first
• Prefer explicit over implicit code
• Document functions and classes with docstrings

Version Control Guidelines

Basic Commit Practices

• Make frequent, atomic commits with descriptive messages
• Use conventional commit format: type(scope): description
• For multi-line commit messages, write a git_commit_message file and use git commit -F git_commit_message
• Ensure git_commit_message is in .gitignore to avoid tracking temporary commit files
• Ensure all tests pass before committing
• Tag releases with semantic versioning (major.minor.patch)

Branching Strategy

CRITICAL RULE: Separate different types of work into different branches:

Branch Types and Naming

• Feature branches: feature_name or api_improvements - New functionality or enhancements
• Test infrastructure: test_suite_development - Testing framework, test organization, TDD setup
• Bug fixes: fix_issue_description - Bug fixes and corrections
• Documentation: docs_update_description - Documentation-only changes
• Repository maintenance: repo_cleanup or dependency_updates - Housekeeping tasks

Branch Management Rules

1. Single Purpose: Each branch should have ONE clear purpose (testing OR features OR docs, not mixed)
2. Descriptive Names: Branch names should clearly indicate their scope and purpose
3. Foundation First: Merge infrastructure/testing branches before feature branches that depend on them
4. Clean History: Keep branch history focused - avoid mixing unrelated commits
5. Prompt Cleanup: Delete merged branches immediately after successful merge

Pull Request Strategy

Systematic Approach to PRs:

PR Sequencing

1. Infrastructure First: Test frameworks, development guidelines, repository organization
2. Core Features Second: Main functionality that other features depend on
3. Enhancement Features Third: Additional features that build on core functionality
4. Documentation Last: Comprehensive documentation after features are stable

PR Best Practices

• Single Responsibility: Each PR should address one logical area of work
• Complete Testing: Include all necessary tests in the same PR as the feature
• Clear Description: Explain what the PR does, why it's needed, and what testing was done
• Breaking Changes: Clearly document any breaking changes in PR description
• Review Ready: Ensure all tests pass and code is ready for production

Repository Hygiene

Maintaining Clean Repository State:

Branch Cleanup Process

1. After Merge: Immediately delete the merged branch locally: git branch -d branch_name
2. Remote Cleanup: Use git remote prune origin to clean stale remote tracking branches
3. Verification: Regularly check git branch -a to ensure clean state
4. Archive Only: Keep branches only if they contain unmerged work

Repository Maintenance

• Regular Audits: Periodically review and clean up old branches
• Stale Branch Detection: Identify branches with old commit dates that may be obsolete
• Dependency Updates: Separate PRs for dependency updates to avoid mixing with feature work
• Documentation Sync: Ensure documentation branches are kept in sync with feature development

Branch Recovery and Reorganization

When Things Go Wrong:

Common Scenarios

• Mixed Work Types: If infrastructure and feature work are mixed in one branch
• Wrong Base Branch: If feature branch was created from wrong starting point
• Commit Organization: If commits need to be reordered or separated

Recovery Strategies

1. Branch Extraction: Create new branch from specific commit: git checkout -b new_branch commit_hash
2. Reset and Rebuild: Reset branch to earlier state: git reset --hard commit_hash
3. Cherry-pick: Move specific commits: git cherry-pick commit_hash
4. Interactive Rebase: Reorder/squash commits: git rebase -i HEAD~n

Prevention Best Practices

• Plan Before Coding: Decide branch purpose before starting work
• Single Focus Sessions: Work on one type of task per development session
• Regular Commits: Commit frequently with clear messages to enable easier reorganization
• Context Documentation: Keep clear notes in context files about what each branch contains

Testing Organization

• Organize test files as test_*.py in the /tests/ directory
• Use pytest for test execution and assertions
• For complex components, create subdirectories: /tests/{component}/
• Save test fixtures in separate files or a fixtures directory

Incremental Test Development

CRITICAL RULE: Always develop tests incrementally, one test case at a time:

• Create ONE test case and run it to ensure it passes
• Only move to the next test case after the current one is verified
• Use fast and incremental iteration instead of bulk edits
• This approach enables easier troubleshooting and maintenance
• If a test fails, fix it immediately before adding more tests

Testing Strategies

• Unit Tests: Test individual functions/methods in isolation
• Integration Tests: Test component interactions
• End-to-End Tests: Test complete user workflows
• Aim for 90%+ coverage on core modules
• Test both happy path and error conditions
• Use descriptive test names that explain the scenario
• Mock external dependencies to ensure test reliability

Debugging and Error Handling

• Use systematic debugging: reproduce, isolate, identify root cause, fix, verify
• Add logging statements for complex logic flows
• Write descriptive error messages that guide users toward solutions
• Use appropriate exception types and handle edge cases gracefully
• Document known issues and their workarounds in context/memory.md
• Test error conditions as thoroughly as success conditions

API Design Guidelines

• Design APIs that are intuitive for first-time users
• Provide sensible defaults to minimize required parameters
• Use consistent parameter names across functions
• Support both simple and advanced use cases
• Maintain backward compatibility in minor version updates
• Provide clear examples in docstrings
• Return consistent data types and structures

Cross-Session Continuity

• Update context files at the end of each session:
  • context/memory.md: Record decisions, state changes, and knowledge
  • context/todo.md: Update task status and add new tasks
• Begin each new session with context review

Refactoring Guidelines

• Schedule regular refactoring sessions in the todo list
• Focus on one aspect per refactoring session (e.g., organization, performance)
• Maintain test coverage during refactoring
• Document architectural changes in context/memory.md

When Tests Fail

• Troubleshoot and fix all errors and warnings
• Record challenging bugs and their solutions in context/memory.md

When Tasks Are Completed

1. Verify Implementation: Ensure all tests pass and feature works as expected
2. Update Context: Update context/todo.md to mark task completion and context/memory.md to reflect current project state
3. Version Control:
   • Commit changes with descriptive message using git_commit_message file
   • Verify branch contains only related work (single purpose)
   • Consider if additional refactoring tasks should be added to backlog
4. Branch Management:
   • If work is complete and ready for merge, prepare for PR creation
   • If continuing work on same branch type, proceed to next task
   • If switching work types (e.g., from features to tests), switch branches
5. Clean Transition: End session with clear context or move to next logical task

Session Management

Starting New Sessions:

• Review context/memory.md and context/todo.md to understand current state
• Check current branch and recent commits: git branch && git log --oneline -5
• Verify clean working state: git status
• Plan session focus (feature work, testing, documentation, etc.)

Ending Sessions:

• Commit all work with clear messages
• Update context files with progress and decisions
• Note any pending tasks or blockers in todo list
• Leave repository in clean state for next session