implementation

This skill provides systematic guidance for implementing features with high-quality code, comprehensive tests, and proper documentation, following project standards and best practices.

• After design phase is complete and approved
• Need to implement code for a feature
• Writing unit and integration tests
• Creating technical documentation
• Following TDD (Test-Driven Development) workflow

1. Setup and Preparation

Review Design Document:

• Read architecture design from previous phase
• Understand component structure
• Review API contracts and data models
• Note security and performance requirements

Setup Development Environment:

```bash

# Activate virtual environment

source venv/bin/activate # or: uv venv && source .venv/bin/activate

# Install dependencies

pip install -r requirements.txt

# or: uv pip install -r requirements.txt

# Install dev dependencies

pip install -e ".[dev]"

```

Create Feature Branch:

```bash

git checkout -b feature/feature-name

```

Deliverable: Development environment ready

---

2. Test-Driven Development (TDD)

TDD Cycle: Red → Green → Refactor

Step 1: Write Failing Test (Red)

```python

# tests/test_feature.py

import pytest

from feature import process_data

def test_process_data_success():

"""Test successful data processing."""

# Arrange

input_data = {"name": "test", "value": 123}

# Act

result = process_data(input_data)

# Assert

assert result.name == "test"

assert result.value == 123

```

Step 2: Write Minimal Code (Green)

```python

# src/tools/feature/core.py

def process_data(input_data: dict):

"""Process input data."""

# Minimal implementation to pass test

return type('Result', (), input_data)()

```

Step 3: Refactor (Refactor)

```python

# src/tools/feature/core.py

from .models import InputModel, ResultModel

def process_data(input_data: dict) -> ResultModel:

"""

Process input data and return result.

Args:

input_data: Input data dictionary

Returns:

ResultModel with processed data

Raises:

ValidationError: If input is invalid

"""

# Proper implementation with validation

validated = InputModel(**input_data)

return ResultModel(

name=validated.name,

value=validated.value

)

```

Repeat: Write next test, implement, refactor

Deliverable: Tested, working code

---

3. Code Implementation

Follow Project Structure:

```

src/tools/feature_name/

├── __init__.py # Public exports

├── models.py # Pydantic models (data)

├── interfaces.py # Abstract interfaces

├── core.py # Core business logic

├── repository.py # Data access layer

├── validators.py # Input validation

├── utils.py # Helper functions

├── config.py # Configuration

├── exceptions.py # Custom exceptions

└── main.py # CLI entry point (if applicable)

```

Coding Standards:

Refer to code-style-guide.md for:

• PEP 8 style guide
• Type hints for all functions
• Google-style docstrings
• 500-line file limit
• Single responsibility principle

Example Implementation:

```python

# src/tools/feature/models.py

from pydantic import BaseModel, Field

from typing import Optional

from datetime import datetime

class FeatureInput(BaseModel):

"""Input model for feature."""

name: str = Field(..., min_length=1, max_length=100)

value: int = Field(..., ge=0)

class Config:

validate_assignment = True

class FeatureOutput(BaseModel):

"""Output model for feature."""

id: Optional[int] = None

name: str

value: int

created_at: datetime = Field(default_factory=datetime.utcnow)

# src/tools/feature/core.py

from .models import FeatureInput, FeatureOutput

from .repository import FeatureRepository

from .validators import FeatureValidator

class FeatureService:

"""Feature service with business logic."""

def __init__(

self,

repository: FeatureRepository,

validator: FeatureValidator

):

"""

Initialize service with dependencies.

Args:

repository: Repository for data access

validator: Validator for input validation

"""

self.repository = repository

self.validator = validator

def create(self, input_data: FeatureInput) -> FeatureOutput:

"""

Create new feature resource.

Args:

input_data: Validated input data

Returns:

FeatureOutput with created resource

Raises:

ValidationError: If validation fails

RepositoryError: If save fails

"""

# Validate

self.validator.validate_create(input_data)

# Create

output = FeatureOutput(

name=input_data.name,

value=input_data.value

)

# Persist

saved = self.repository.save(output)

return saved

```

Deliverable: Implemented core functionality

---

4. Testing Implementation

Testing Checklist:

Refer to testing-checklist.md for comprehensive coverage

Unit Tests (80%+ Coverage):

```python

# tests/test_core.py

import pytest

from unittest.mock import Mock, MagicMock

from feature.core import FeatureService

from feature.models import FeatureInput, FeatureOutput

@pytest.fixture

def mock_repository():

"""Mock repository for testing."""

repo = Mock()

repo.save.return_value = FeatureOutput(

id=1,

name="test",

value=123

)

return repo

@pytest.fixture

def mock_validator():

"""Mock validator for testing."""

validator = Mock()

validator.validate_create.return_value = None

return validator

@pytest.fixture

def service(mock_repository, mock_validator):

"""Service fixture with mocked dependencies."""

return FeatureService(

repository=mock_repository,

validator=mock_validator

)

def test_create_success(service, mock_repository):

"""Test successful creation."""

# Arrange

input_data = FeatureInput(name="test", value=123)

# Act

result = service.create(input_data)

# Assert

assert result.name == "test"

assert result.value == 123

mock_repository.save.assert_called_once()

def test_create_validation_error(service, mock_validator):

"""Test validation error handling."""

# Arrange

input_data = FeatureInput(name="test", value=123)

mock_validator.validate_create.side_effect = ValidationError("Invalid")

# Act & Assert

with pytest.raises(ValidationError):

service.create(input_data)

```

Integration Tests:

```python

# tests/integration/test_feature_integration.py

import pytest

from pathlib import Path

from feature import FeatureService, FileSystemRepository

@pytest.fixture

def temp_data_dir(tmp_path):

"""Temporary directory for test data."""

return tmp_path / "data"

def test_create_and_retrieve(temp_data_dir):

"""Test end-to-end create and retrieve."""

# Arrange

repo = FileSystemRepository(temp_data_dir)

service = FeatureService(repo)

# Act: Create

created = service.create(FeatureInput(name="test", value=123))

# Act: Retrieve

retrieved = service.get(created.id)

# Assert

assert retrieved.name == "test"

assert retrieved.value == 123

```

Run Tests:

```bash

# Run all tests with coverage

pytest --cov=src --cov-report=html --cov-report=term

# Run specific test file

pytest tests/test_core.py -v

# Run with markers

pytest -m "not slow" -v

```

Deliverable: Comprehensive test suite (80%+ coverage)

---

5. Code Quality Checks

Run Formatters and Linters:

```bash

# Format code with Black

black src/ tests/

# Type check with mypy

mypy src/

# Lint with flake8 (if configured)

flake8 src/ tests/

# Run all checks

make lint # If Makefile configured

```

Pre-commit Hooks (If Configured):

```bash

# Run pre-commit checks

pre-commit run --all-files

```

Code Review Checklist:

• [ ] All functions have type hints
• [ ] All functions have docstrings
• [ ] No files exceed 500 lines
• [ ] Tests achieve 80%+ coverage
• [ ] No lint errors or warnings
• [ ] Error handling implemented
• [ ] Logging added where appropriate
• [ ] Security best practices followed

Deliverable: Quality-checked code

---

6. Documentation

Code Documentation:

• Docstrings for all public functions/classes
• Inline comments for complex logic
• Type hints for clarity

Technical Documentation:

```markdown

# Feature Implementation

[What was implemented]

[Actual structure (may differ from design)]

```python

from feature import FeatureService

service = FeatureService()

result = service.create(name="example")

```

Required environment variables:

• FEATURE_API_KEY: API key for service
• FEATURE_TIMEOUT: Timeout in seconds (default: 30)

```bash

pytest tests/test_feature.py

```

• [Issue 1]: [Workaround]

• [Enhancement 1]

```

User Documentation (If Applicable):

• Usage guide in docs/guides/
• CLI help text
• Example configurations

Deliverable: Complete documentation

---

7. Integration and Verification

Verify Against Requirements:

• [ ] All acceptance criteria met
• [ ] Security checklist items addressed
• [ ] Performance requirements met
• [ ] Edge cases handled
• [ ] Error scenarios tested

Manual Testing:

```bash

# Test CLI (if applicable)

python -m src.tools.feature.main create --name test

# Test with real data

python -m src.tools.feature.main --input sample.json

# Test error cases

python -m src.tools.feature.main --invalid-input

```

Integration with Existing Code:

• [ ] Imports work correctly
• [ ] No circular dependencies
• [ ] Backward compatibility maintained (if applicable)
• [ ] No breaking changes to public APIs

Deliverable: Verified, working feature

---

Python Style (PEP 8)

Imports:

```python

# Standard library

import os

import sys

from pathlib import Path

# Third-party

import click

from pydantic import BaseModel

# Local

from .models import FeatureModel

from .exceptions import FeatureError

```

Naming:

```python

# Classes: PascalCase

class FeatureService:

pass

# Functions/methods: snake_case

def process_data():

pass

# Constants: UPPER_SNAKE_CASE

MAX_RETRIES = 3

# Private: leading underscore

def _internal_helper():

pass

```

Type Hints:

```python

from typing import Optional, List, Dict, Union

def function(

required: str,

optional: Optional[int] = None,

items: List[str] = None

) -> Dict[str, Any]:

pass

```

Docstrings (Google Style):

```python

def function(param1: str, param2: int) -> bool:

"""

Short description.

Longer description if needed.

Args:

param1: Description of param1

param2: Description of param2

Returns:

Description of return value

Raises:

ValueError: When this happens

"""

pass

```

---

Pytest Conventions

Test File Naming:

• test_.py or _test.py
• Mirror source structure: src/core.py → tests/test_core.py

Test Function Naming:

```python

def test_function_name_condition_expected_result():

"""Test description."""

pass

# Examples:

def test_create_feature_valid_input_returns_feature():

pass

def test_validate_input_missing_name_raises_error():

pass

```

Test Structure (Arrange-Act-Assert):

```python

def test_example():

"""Test example."""

# Arrange: Setup test data and mocks

input_data = {"name": "test"}

mock_service = Mock()

# Act: Execute the code being tested

result = function_under_test(input_data, mock_service)

# Assert: Verify expected outcomes

assert result == expected

mock_service.method.assert_called_once()

```

Fixtures:

```python

# tests/conftest.py (shared fixtures)

import pytest

@pytest.fixture

def sample_data():

"""Sample data for tests."""

return {"name": "test", "value": 123}

@pytest.fixture

def temp_directory(tmp_path):

"""Temporary directory for test files."""

test_dir = tmp_path / "test_data"

test_dir.mkdir()

yield test_dir

# Cleanup happens automatically

```

Parametrize for Multiple Cases:

```python

@pytest.mark.parametrize("input_value,expected", [

("valid", True),

("invalid", False),

("", False),

])

def test_validation(input_value, expected):

"""Test validation with multiple inputs."""

result = validate(input_value)

assert result == expected

```

---

Error Handling Pattern

```python

from typing import Optional

import logging

logger = logging.getLogger(__name__)

def process_data(data: dict) -> Result:

"""Process data with proper error handling."""

try:

# Validate

validated = validate_data(data)

# Process

result = perform_processing(validated)

return result

except ValidationError as e:

logger.warning(f"Validation failed: {e}")

raise

except ProcessingError as e:

logger.error(f"Processing failed: {e}", exc_info=True)

raise

except Exception as e:

logger.exception(f"Unexpected error: {e}")

raise ProcessingError("Unexpected error occurred") from e

```

Dependency Injection Pattern

```python

from abc import ABC, abstractmethod

# Interface

class Repository(ABC):

@abstractmethod

def save(self, data) -> None:

pass

# Implementation

class FileRepository(Repository):

def save(self, data) -> None:

# File-based implementation

pass

# Service with dependency injection

class Service:

def __init__(self, repository: Repository):

self.repository = repository # Injected dependency

def create(self, data):

# Use injected repository

self.repository.save(data)

# Usage

repo = FileRepository()

service = Service(repository=repo) # Inject dependency

```

Configuration Pattern

```python

from pydantic_settings import BaseSettings

class Config(BaseSettings):

"""Application configuration."""

api_key: str

timeout: int = 30

debug: bool = False

class Config:

env_prefix = "FEATURE_"

env_file = ".env"

# Usage

config = Config() # Loads from environment/file

service = Service(api_key=config.api_key, timeout=config.timeout)

```

---

• code-style-guide.md: Detailed Python style guidelines
• testing-checklist.md: Comprehensive testing requirements
• scripts/generate_tests.py: Test scaffolding automation

---

Input: Approved architecture design

Process: TDD implementation with quality checks

Output: Tested, documented code

Next Step: Validation skill for quality assurance

---

Before marking feature complete:

• [ ] All code implemented per design
• [ ] Unit tests written (80%+ coverage)
• [ ] Integration tests written
• [ ] All tests passing
• [ ] Code formatted (Black)
• [ ] Type checking passing (mypy)
• [ ] No lint errors
• [ ] Docstrings complete
• [ ] Technical documentation written
• [ ] User documentation written (if applicable)
• [ ] Manual testing completed
• [ ] Security considerations addressed
• [ ] Performance requirements met
• [ ] Code reviewed (if applicable)
• [ ] Ready for validation phase