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