Aider TDD Python Development

A comprehensive Test-Driven Development workflow using Aider AI pair programmer for Python projects. Enforces quality gates including automated testing, type checking, linting, and 80% minimum test coverage.

Overview

This skill configures Aider to follow strict TDD principles with mandatory session management, automated quality checks, and comprehensive testing standards. Based on a modern Python template with production-ready tooling.

Workflow

1. MANDATORY: Start Every Session

**CRITICAL**: Before doing ANYTHING, you MUST run:

```bash

uv run ai-start-task "Your task description"

```

This is NOT optional. Every Aider session MUST begin with `ai-start-task`.

2. During Development

Track your progress with these commands:

```bash

Log progress updates

uv run ai-log "Progress message"

Mark tasks as complete

uv run ai-update-plan "Completed item"

Customize your plan for the specific task

uv run ai-update-plan --add "Specific feature step" --phase "Phase 2"

uv run ai-update-plan --remove "Irrelevant generic item"

uv run ai-update-plan --rename "Generic item" --to "Detailed specific item"

```

3. Follow TDD Cycle

**ALWAYS write tests BEFORE implementation:**

1. **Red**: Write failing test first

```bash

/add tests/test_feature.py

# Write test for new functionality

/test # Should fail

```

2. **Green**: Implement minimal code to pass

```bash

/add src/package/feature.py

# Implement functionality

/test # Should pass

```

3. **Refactor**: Clean up while keeping tests green

```bash

/run make check # Run all quality gates

```

4. **Commit**: Only if all checks pass

```bash

/commit # Auto-generated conventional commit message

```

4. Quality Gates (All Must Pass)

Before committing, ensure:

Run quality check:

```bash

/run make check

```

5. Finish Session

When completing work:

```bash

uv run ai-finish-task --summary="What you accomplished"

```

Core Principles

Test-Driven Development

When to Mock

**DO mock these:**

**DON'T mock these:**

Code Quality Standards

**Type hints required** (mypy strict mode):

```python

def func(param: str) -> int:

"""Brief description.

Args:

param: Description

Returns:

Description

"""

return len(param)

```

**Import pattern** (use package name, not src prefix):

```python

from package_name import function_name

```

**Docstring style** (Google format):

Aider Commands

File Management

```bash

/add src/package/feature.py tests/test_feature.py # Add files to context

/read README.md # Add read-only context

```

Testing & Quality

```bash

/test # Run make test

/lint # Run make lint

/run make check # Run complete quality check

/run make coverage # Check test coverage report

```

Git Operations

```bash

/commit # Commit with auto-generated message

/diff # Show current changes

```

Help

```bash

/help # Show all Aider commands

```

Example TDD Session

**User**: "Add a function to parse JSON safely"

**Aider workflow**:

```bash

1. Add files to context

/add tests/test_utils.py src/package/utils.py

2. Write test first

Edit tests/test_utils.py - add test_parse_json_safe

3. Run test (should fail)

/test

4. Implement function

Edit src/package/utils.py - add parse_json_safe

5. Run test (should pass)

/test

6. Run all quality checks

/run make check

7. Commit if all pass

/commit

Result: "feat: add safe JSON parsing with error handling"

```

Configuration Files

Aider automatically reads these files for context:

**Session management** (MANDATORY):

**Development guidelines**:

**Project files**:

Coverage Requirements

Check coverage:

```bash

/run make coverage

```

View HTML report: `htmlcov/index.html`

Constraints

Success Criteria

A task is complete when:

1. All tests written before implementation

2. All tests pass

3. Coverage ≥ 80%

4. All linters pass (Black, isort, Ruff, mypy, Pylint)

5. `make check` passes

6. Changes committed with conventional commit message

7. Session closed with `ai-finish-task`