Imported from pamagister/Photo-Composition-Designer (AGENTS.md). Install upstream with npx skills add pamagister/Photo-Composition-Designer. Copyright stays with the author.

Agent Guidelines for Python Code Quality

This document provides guidelines for maintaining high-quality Python code. These rules MUST be followed by all AI coding agents and contributors.

Your Core Principles

All code you write MUST be fully optimized.

"Fully optimized" includes:

• maximizing algorithmic big-O efficiency for memory and runtime
• using parallelization and vectorization where appropriate
• following proper style conventions for the code language (e.g. maximizing code reuse (DRY))

Preferred Tools

• Use uv for Python package management and to create a .venv if it is not present.

Code Style and Formatting

• MUST use meaningful, descriptive variable and function names
• MUST follow PEP 8 style guidelines
• MUST use 4 spaces for indentation (never tabs)
• NEVER use emoji, or unicode that emulates emoji (e.g. ✓, ✗). The only exception is when writing tests and testing the impact of multibyte characters.
• Use snake_case for functions/variables, PascalCase for classes, UPPER_CASE for constants
• Limit line length to 100 characters (ruff formatter standard)
• MUST avoid including redundant comments which are tautological or self-demonstating (e.g. cases where it is easily parsable what the code does at a glance so the comment does)
• MUST avoid including comments which leak what this file contains, or leak the original user prompt, ESPECIALLY if it's irrelevant to the output code.

Documentation

• MUST include docstrings for all public functions, classes, and methods
• MUST document function parameters, return values, and exceptions raised
• Keep comments up-to-date with code changes

Type Hints

• MUST use type hints for all function signatures (parameters and return values)
• NEVER use Any type unless absolutely necessary
• MUST run mypy and resolve all type errors
• Use Optional[T] or T | None for nullable types

Error Handling

• NEVER silently swallow exceptions without logging
• MUST never use bare except: clauses
• MUST catch specific exceptions rather than broad exception types
• MUST use context managers (with statements) for resource cleanup
• Provide meaningful error messages

Function Design

• MUST keep functions focused on a single responsibility
• NEVER use mutable objects (lists, dicts) as default argument values
• Limit function parameters to 5 or fewer
• Return early to reduce nesting

Class Design

• MUST keep classes focused on a single responsibility
• MUST keep __init__ simple; avoid complex logic
• Use dataclasses for simple data containers
• Prefer composition over inheritance

Testing

• MUST write unit tests for all new functions and classes
• MUST mock external dependencies (APIs, databases, file systems)
• MUST use pytest as the testing framework

Imports and Dependencies

• MUST avoid wildcard imports (from module import *)
• MUST document dependencies in pyproject.toml
• Use uv for fast package management and dependency resolution

Python Best Practices

• NEVER use mutable default arguments
• MUST use context managers (with statement) for file/resource management
• MUST use is for comparing with None, True, False
• MUST use f-strings for string formatting
• Use list comprehensions and generator expressions
• Use enumerate() instead of manual counter variables

Before Committing

• Code formatter pass: >> make format
• Linter pass: >> make lint
• All tests pass: >> make test

Remember: Prioritize clarity and maintainability over cleverness. This is your core directive.