## Build & Development Commands

    Self-review generated code before presenting it
    Highlight potential edge cases or failure modes
    Suggest appropriate tests for new functionality
    Propose debugging strategies when issues arise
    Acknowledge limitations when you're uncertain about implementation details


## Testing Guidelines
Testing Philosophy

    Prioritize test-driven development (TDD) when appropriate - write tests before implementation
    Create tests for all new functionality before considering it complete
    Focus on testing behavior, not implementation details
    Suggest both unit and integration tests with appropriate balance
    Default to pytest as the primary testing framework

Test Structure and Organization

    Organize test files to mirror project structure:

Text Only

myproject/
├── module/
│   └── file.py
└── tests/
    └── module/
        └── test_file.py

Name test functions descriptively:
Python

def test_user_creation_with_valid_data_succeeds():
    # test code here

Group related tests into classes for larger modules:

    Python

    class TestUserAuthentication:
        def test_login_with_valid_credentials(self):
            # test code here

        def test_login_with_invalid_password(self):
            # test code here

Test Content Guidelines

    Follow the Arrange-Act-Assert pattern:

Python

# Arrange
user = User(name="Test User")

# Act
result = user.validate()

# Assert
assert result is True

Use fixtures for common test setup:
Python

@pytest.fixture
def valid_user():
    return User(name="Test User", email="test@example.com")

Implement appropriate mocking:

    Python

    @patch('module.requests.get')
    def test_api_call(mock_get):
        mock_get.return_value.status_code = 200
        mock_get.return_value.json.return_value = {'key': 'value'}
        # test code here

    Test edge cases and failure modes systematically

Documentation and Maintenance

    Include docstrings in test files explaining test purpose

    Comment non-obvious test scenarios:

    Python

    # Testing race condition that occurs when two users update simultaneously

    Create a tests/README.md explaining testing philosophy and structure
    Maintain a test coverage report in the project documentation

Quality Metrics

    Aim for 80%+ code coverage for critical paths

    Use parameterized tests for exhaustive test cases:

    Python

    @pytest.mark.parametrize("input,expected", [
        ("valid@email.com", True),
        ("invalid-email", False),
        ("", False)
    ])
    def test_email_validation(input, expected):
        assert validate_email(input) == expected

    Run tests frequently during development, not just at completion
    Implement test debugging strategies when tests fail unexpectedly

CI Integration

    Configure tests to run automatically on git commits
    Generate and archive test reports
    Fail builds when tests fail to maintain quality standards

Remember: Tests serve as both documentation and quality assurance. They should be maintained with the same care as production code. 

## Code Style & Guidelines 
General Principles

    Follow PEP 8 as the foundation of all code style
    Value readability over cleverness
    Maintain consistency within the codebase
    Write self-documenting code where possible
    Keep functions and methods small (aim for ≤30 lines)

Formatting Standards

    Use 4 spaces for indentation (no tabs)
    Maximum line length: 88 characters (Black default)

    Use proper whitespace:

    Python

    # Good
    def function(param1, param2):
        result = param1 + param2
        return result

    # Bad
    def function(param1,param2):
        result=param1+param2
        return result

    Use Black and isort for automatic formatting

Naming Conventions

    Use descriptive names that reveal intent:

Python

# Good
user_accounts = get_active_accounts()

# Bad
ua = get_accounts()

Follow standard Python naming patterns:

    Python

    snake_case_for_variables_and_functions
    UPPER_CASE_WITH_UNDERSCORES_FOR_CONSTANTS
    PascalCaseForClassNames
    _leading_underscore_for_private_attributes

    Avoid single-letter variables except in limited contexts (e.g., loop indices)

Code Organization

    Import order (enforced by isort):

Python

# Standard library
import os
import sys

# Third-party
import numpy as np

# Local application
from myproject import utils

Class organization:

    Python

    class MyClass:
        """Class docstring."""

        # Class variables
        DEFAULT_VALUE = 100

        def __init__(self):
            # Instance variables
            self.value = None

        # Public methods

        # Protected methods

        # Private methods

    Keep related code together (high cohesion)

Documentation Standards

    Use docstrings for all public modules, functions, classes, and methods:

Python

def calculate_total(items, tax_rate=0.0):
    """
    Calculate the total price of items with tax.

    Args:
        items (list): List of (price, quantity) tuples
        tax_rate (float, optional): Tax rate as a decimal. Defaults to 0.0.

    Returns:
        float: Total price including tax

    Raises:
        ValueError: If tax_rate is negative
    """

Choose a consistent docstring style (Google, NumPy, or reStructuredText)

Include doctest examples for non-trivial functions:

    Python

    def add_one(number):
        """
        Add one to the input number.

        Args:
            number (int): The number to add to

        Returns:
            int: Input plus one

        Examples:
            >>> add_one(5)
            6
        """
        return number + 1

Error Handling

    Use specific exception types rather than generic exceptions:

Python

# Good
try:
    value = json.loads(data)
except json.JSONDecodeError:
    handle_invalid_json()

# Bad
try:
    value = json.loads(data)
except Exception:
    handle_error()

Include error context in exception messages:

    Python

    if value < 0:
        raise ValueError(f"Expected positive value, got {value}")

Comments and Code Clarity

    Comment why, not what:

Python

# Bad
x += 1  # Increment x

# Good
x += 1  # Adjust for zero-indexing

Use meaningful variable names instead of comments when possible
Mark TODO and FIXME items with username and date:

    Python

    # TODO(username, 2025-05-01): Replace with more efficient algorithm

Type Annotations

    Use type hints for function signatures:

Python

def process_data(items: list[str], max_items: int = 10) -> dict[str, int]:
    """Process a list of string items."""
    result: dict[str, int] = {}
    return result

Add inline type annotations for complex variables:

    Python

    # Complex data structure
    config: dict[str, Union[str, list[int]]] = {}

Testing-Related Style

    Write test function names as descriptive phrases:

Python

def test_user_login_fails_with_invalid_credentials():
    # test code

Keep test assertions simple and descriptive:

    Python

    # Good
    assert user.is_authenticated is True

    # Better (with pytest)
    assert user.is_authenticated

By following these guidelines, the AI code agent will produce consistent, readable, and maintainable Python code.

## Documentation Guidelines 

    Create and maintain planning documents in /project-plans/
    Document all significant changes in CHANGELOG.md
    Reference and update PROJECT_DESCRIPTION.md for project context
    Include docstrings and comments that explain "why" not just "what"
    Suggest relevant updates to documentation when code changes