Aider Python TDD Project

A comprehensive skill for AI-assisted Python development using Aider with strict Test-Driven Development (TDD) workflow, quality enforcement, and session management.

Description

This skill configures Aider AI for modern Python projects with mandatory TDD practices, comprehensive quality gates, and structured session management. It enforces 80% minimum test coverage, strict type checking with mypy, and automated quality checks before every commit.

Key Features

Instructions

CRITICAL: Session Management (MANDATORY)

**BEFORE doing ANYTHING in this session:**

```bash

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

```

If you have NOT run this command yet, STOP NOW and run it. This is NOT optional. Every Aider session MUST start with `ai-start-task`.

**During work:**

```bash

uv run ai-log "Progress message"

uv run ai-update-plan "Completed item"

Customize your plan

uv run ai-update-plan --add "Specific task for this feature" --phase "Phase 2"

uv run ai-update-plan --remove "Generic irrelevant item"

uv run ai-update-plan --rename "Generic item" --to "Specific detailed item"

```

**When finishing:**

```bash

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

```

Core TDD Workflow

1. **Write Tests First** (ALWAYS)

- Create test file: `tests/test_feature.py`

- Write test cases that define expected behavior

- Tests will fail initially (red phase)

2. **Run Tests**

```bash

/test

```

Tests should fail - this is expected!

3. **Implement Code**

- Write minimal code to make tests pass

- Follow type hints and docstring standards

- Use real code, minimize mocks

4. **Run Tests Again**

```bash

/test

```

Tests should now pass (green phase)

5. **Quality Check**

```bash

/run make check

```

Must pass all quality gates

6. **Commit**

```bash

/commit

```

Auto-generates conventional commit message

Quality Gates (All Must Pass)

When to Mock (ONLY When Necessary)

**DO Mock:**

**DON'T Mock:**

Code Standards

**Type Hints (Required):**

```python

def func(param: str) -> int:

"""Brief description.

Args:

param: Description

Returns:

Description

"""

return len(param)

```

**Import Pattern:**

```python

Use package name, not src prefix

from python_modern_template import function_name

```

**Test File Pattern:**

Aider Commands

Example TDD Session

```

User: "Add a function to parse JSON safely"

AI:

> /add tests/test_utils.py src/python_modern_template/utils.py

> I'll write tests first following TDD...

[Edit tests/test_utils.py - add test_parse_json_safe]

> /test

[Tests fail - function doesn't exist] ❌

> Now implementing the function...

[Edit src/python_modern_template/utils.py - add parse_json_safe]

> /test

[Tests pass] ✅

> /run make check

[All quality checks pass] ✅

> /commit

[Commit with message: "✨ Add safe JSON parsing with tests"]

```

Coverage Requirements

Check coverage:

```bash

/run make coverage

```

View HTML report: `htmlcov/index.html`

Project Configuration

**Auto-commits**: Enabled with conventional commit messages

**Auto-testing**: Tests run after every code change

**Auto-linting**: Linting runs after every code change

**Repo map**: Enabled (2048 tokens) for better context

Documentation References

The skill automatically reads these shared documentation files:

Watched Files

Aider automatically monitors:

Important Constraints

1. **Tests ALWAYS come first** - No implementation without tests

2. **Minimize mocking** - Use real code whenever possible

3. **Type hints required** - mypy strict mode enforced

4. **Run `make check` before committing** - Non-negotiable

5. **Maintain 80%+ coverage** - Enforced by pre-commit hooks

6. **Follow TDD red-green-refactor** - Failing test → passing test → refactor

7. **Session management is mandatory** - Must use `ai-start-task` and `ai-finish-task`

Notes