Фазы Tasks и Implement

Вступление

Фазы Specify и Plan отвечают на вопросы "Что строить?" и "В каком порядке?". Фазы Tasks и Implement отвечают на вопросы "Как именно объяснить это AI?" и "Как убедиться, что AI сделал правильно?".

Это переход от человеческого мышления к машинному исполнению. И именно здесь качество предыдущих фаз проявляется наиболее ярко: хорошая спецификация и план делают декомпозицию на задачи тривиальной, плохая -- превращает её в мучение.

┌──────────┐    Gate 1    ┌──────────┐    Gate 2    ┌──────────┐    Gate 3    ┌──────────────┐
│ SPECIFY  │──────────────│   PLAN   │──────────────│  TASKS   │──────────────│  IMPLEMENT   │
│  ✓ Done  │              │  ✓ Done  │              │          │              │              │
└──────────┘              └──────────┘              │ ◄── ВЫ   │              │              │
                                                    │   ЗДЕСЬ  │              │              │
                                                    └──────────┘              └──────────────┘

Фаза 3: TASKS -- декомпозиция на атомарные задачи

Цель фазы

Разбить план реализации на атомарные, верифицируемые задачи, которые AI может выполнить автономно. Каждая задача -- это самодостаточная инструкция с чётким результатом.

Что делает задачу хорошей для AI

AI -- это не человек-разработчик. Человек может прочитать размытое описание и домыслить контекст из опыта. AI будет генерировать то, что статистически вероятно, а не то, что вы имели в виду. Поэтому задачи для AI должны обладать четырьмя свойствами:

1. Атомарность

Одна задача -- один чёткий результат. Не "создай сервис регистрации с тестами", а два отдельных задания: "создай сервис" и "напиши тесты для сервиса".

# ❌ Плохо: слишком много в одной задаче
Task: Create user registration with validation, email sending, and tests

# ✅ Хорошо: атомарные задачи
Task 4.1: Create RegistrationService with register() method
Task 4.2: Create SendConfirmationEmailMessage
Task 4.3: Create SendConfirmationEmailHandler
Task 7.1: Create unit tests for RegistrationService

Почему атомарность важна:

• Меньше контекста -- AI лучше справляется с фокусированными задачами
• Проще верифицировать -- один результат проще проверить, чем пять
• Легче откатить -- если задача провалилась, откатываем одно изменение
• Чёткий прогресс -- 15/20 задач выполнено vs "сервис частично готов"

2. Верифицируемость

Для каждой задачи -- чёткий критерий успеха, который можно проверить автоматически.

Правило: Если критерий успеха нельзя автоматизировать, задача либо слишком абстрактная, либо требует человеческого ревью (и это нужно указать явно).

3. Контекстная ограниченность

AI должен получить всю необходимую информацию внутри описания задачи. Не "посмотри в спеке", а конкретные данные из спеки прямо в задаче.

# ❌ Плохо: ссылка без контекста
Task: Create UserRepository (see spec for details)

# ✅ Хорошо: весь контекст в задаче
Task: Create UserRepository

**Context**: Part of user registration feature.
User entity is defined in src/Entity/User.php with fields:
id (UUID v7), email (string), password_hash (string),
status (string enum: pending, active, blocked),
created_at (DateTimeImmutable), updated_at (DateTimeImmutable).

**Action**: Create Doctrine repository with methods:
- findByEmail(string $email): ?User
- save(User $user): void (persist + flush)
- existsByEmail(string $email): bool

**Conventions**:
- Final class, extends ServiceEntityRepository
- Type hints on all parameters and return types
- PHPDoc only where types are insufficient

**Files to create**:
- src/Repository/UserRepository.php

**Verification**:
- PHPStan level 9 passes
- Unit test passes (see Task 7.1)

4. Независимость

Минимальные зависимости от незавершённых задач. Если задача зависит от другой, это указывается явно, и зависимая задача не начинается до завершения предыдущей.

## Task Dependencies

Task 1.1: Migration (users) ← no dependencies
Task 2.1: Entity (User) ← depends on: Task 1.1
Task 3.1: Repository (User) ← depends on: Task 2.1
Task 4.1: Service (Registration) ← depends on: Task 3.1, Task 3.2
Task 7.1: Tests (Registration) ← depends on: Task 4.1

Шаблон задачи

Стандартизированный шаблон гарантирует, что ничего не забыто.

## Task [ID]: [Short Name]

**Phase**: [Plan step reference]
**Priority**: [Critical / High / Medium / Low]
**Dependencies**: [List of task IDs that must be completed first]
**Estimated complexity**: [Low / Medium / High]
**AI autonomy level**: [High / Medium / Low]

### Context
[What is this task part of? What business problem does it solve?
Include relevant excerpts from spec.]

### Input
[What already exists? Files, interfaces, data structures
that this task depends on.]

### Action
[Precisely what needs to be done. Step by step if complex.
Include method signatures, logic rules, edge cases.]

### Output
[What files will be created/modified? What interfaces
will be implemented?]

### Conventions
[Project-specific rules: naming, patterns, libraries to use.]

### Verification
[How to check that the task is done correctly.
Specific commands to run, expected output.]

### Notes
[Anything else AI needs to know. Pitfalls, related issues,
references to other tasks.]

Пример: задачи для регистрации пользователя

Используем план из предыдущей статьи и раскладываем шаг 4.1 (RegistrationService) в полноценную задачу.

## Task 4.1: Create RegistrationService

**Phase**: Step 4 — Business Logic
**Priority**: Critical
**Dependencies**: Task 3.1 (UserRepository), Task 3.2 (TokenRepository)
**Estimated complexity**: Medium
**AI autonomy level**: Medium

### Context
RegistrationService handles the core business logic for
user registration. It validates input, creates the user,
generates a confirmation token, and dispatches an async
email message.

### Input
- src/Repository/UserRepository.php (findByEmail, save, existsByEmail)
- src/Repository/ConfirmationTokenRepository.php (save)
- src/Entity/User.php (id, email, password_hash, status, timestamps)
- src/Entity/ConfirmationToken.php (id, user_id, token, expires_at)

### Action
Create RegistrationService with method:

```php
public function register(string $email, string $password): User

Logic:

1. Check if email already exists (UserRepository::existsByEmail)
   • If exists with status "active" → throw EmailAlreadyExistsException
   • If exists with status "pending" → resend confirmation, return existing user
2. Hash password using UserPasswordHasherInterface
3. Create User entity with status "pending"
4. Create ConfirmationToken with 24h expiry
5. Save both entities
6. Dispatch SendConfirmationEmailMessage via MessageBusInterface
7. Return created User

Output

• src/Service/RegistrationService.php
• src/Exception/EmailAlreadyExistsException.php

Conventions

• Final class
• Constructor injection only
• All dependencies via interfaces
• Wrap in database transaction (Doctrine)

Verification

# Syntax check
docker compose exec php php -l src/Service/RegistrationService.php

# Static analysis
docker compose exec php vendor/bin/phpstan analyse src/Service/RegistrationService.php --level=9

# Related tests (after Task 7.1)
docker compose exec php vendor/bin/phpunit --filter=RegistrationServiceTest

Notes

• Use Symfony PasswordHasher component (not manual bcrypt)
• Token expiry: DateTimeImmutable('+24 hours')
• MessageBus dispatch is fire-and-forget (async via Messenger)

### Порядок задач: критический путь

Не все задачи равны. Некоторые блокируют множество других -- это **критический путь**.

Критический путь (каждая задержка сдвигает финальный срок):

Migration → Entity → Repository → Service → Controller → Tests 1.1 2.1 3.1 4.1 5.1 7.1

Параллельный путь (не влияет на основной):

Migration → Entity → Repository 1.2 2.2 3.2

Независимые задачи (можно делать в любой момент):

2.3 (Validator) 6.1 (security.yaml) 6.2 (messenger.yaml)

> **Правило:** Задачи на критическом пути выполняются первыми. Параллельные задачи заполняют "пустоты" между критическими.

### Gate 3: Ревью списка задач

| Проверка | Вопрос |
|----------|--------|
| Атомарность | Каждая задача имеет ровно один результат? |
| Верифицируемость | У каждой задачи есть автоматизированная проверка? |
| Полнота контекста | AI получит всю нужную информацию в описании задачи? |
| Покрытие плана | Все шаги плана покрыты задачами? |
| Зависимости | Порядок корректен, циклов нет? |
| Реалистичность | Оценки сложности адекватны? |

---

## Фаза 4: IMPLEMENT -- исполнение с верификацией

### Цель фазы

Выполнить задачи с помощью AI, **верифицировать каждую**, интегрировать результаты.

### Цикл реализации

Каждая задача проходит через стандартный цикл:

┌─────────────────┐ │ Выбрать задачу │ └────────┬────────┘ ▼ ┌─────────────────┐ │ Передать AI │◄────────────────────┐ │ (с контекстом) │ │ └────────┬────────┘ │ ▼ │ ┌─────────────────┐ │ │ AI генерирует │ │ │ код │ │ └────────┬────────┘ │ ▼ │ ┌─────────────────┐ Fail │ │ Верификация │─────────────────────┤ │ (тесты, линтер) │ (retry, max 3) │ └────────┬────────┘ │ │ Pass │ ▼ │ ┌─────────────────┐ Still failing │ │ Коммит │ after 3 tries │ │ (маленький) │ │ │ └────────┬────────┘ ▼ │ │ ┌───────────────┐ │ │ │ Human review │ │ │ │ & intervention│ │ │ └───────────────┘ │ ▼ ┌─────────────────┐ │ Следующая задача │ └─────────────────┘

### Шаг 1: Передача задачи AI

Задача передается AI как промпт. Промпт содержит описание задачи из шаблона плюс актуальный контекст проекта.

```markdown
## Промпт для Claude Code / Cursor

I need to implement Task 4.1: RegistrationService.

**Context:**
[Вставить полное описание задачи из шаблона]

**Current project state:**
- UserRepository exists at src/Repository/UserRepository.php
- ConfirmationTokenRepository exists at src/Repository/ConfirmationTokenRepository.php
- User entity at src/Entity/User.php
- ConfirmationToken entity at src/Entity/ConfirmationToken.php

**Conventions:**
- PHP 8.4, declare(strict_types=1)
- Final classes by default
- Constructor property promotion
- Symfony 7.4 dependency injection

Please implement the service and the exception class.

Ключевые правила передачи задачи:

Шаг 2: AI генерирует код

AI создает файлы согласно задаче. На этом этапе ваша роль -- наблюдение. Не вмешивайтесь раньше времени.

<?php

declare(strict_types=1);

namespace App\Service;

use App\Entity\ConfirmationToken;
use App\Entity\User;
use App\Exception\EmailAlreadyExistsException;
use App\Message\SendConfirmationEmailMessage;
use App\Repository\ConfirmationTokenRepository;
use App\Repository\UserRepository;
use Doctrine\ORM\EntityManagerInterface;
use Symfony\Component\Messenger\MessageBusInterface;
use Symfony\Component\PasswordHasher\Hasher\UserPasswordHasherInterface;

final class RegistrationService
{
    public function __construct(
        private readonly UserRepository $userRepository,
        private readonly ConfirmationTokenRepository $tokenRepository,
        private readonly UserPasswordHasherInterface $passwordHasher,
        private readonly MessageBusInterface $messageBus,
        private readonly EntityManagerInterface $entityManager,
    ) {
    }

    public function register(string $email, string $password): User
    {
        $existingUser = $this->userRepository->findByEmail($email);

        if ($existingUser !== null) {
            if ($existingUser->getStatus() === 'active') {
                throw new EmailAlreadyExistsException($email);
            }

            // Resend confirmation for pending users
            $this->resendConfirmation($existingUser);

            return $existingUser;
        }

        return $this->entityManager->wrapInTransaction(function () use ($email, $password): User {
            $user = new User($email);
            $hashedPassword = $this->passwordHasher->hashPassword($user, $password);
            $user->setPasswordHash($hashedPassword);

            $this->userRepository->save($user);

            $token = new ConfirmationToken($user);
            $this->tokenRepository->save($token);

            $this->messageBus->dispatch(
                new SendConfirmationEmailMessage($user->getId(), $token->getToken()),
            );

            return $user;
        });
    }

    private function resendConfirmation(User $user): void
    {
        $token = new ConfirmationToken($user);
        $this->tokenRepository->save($token);

        $this->messageBus->dispatch(
            new SendConfirmationEmailMessage($user->getId(), $token->getToken()),
        );
    }
}

Шаг 3: Верификация

Сразу после генерации -- автоматическая проверка.

# Step 1: Syntax check
docker compose exec php php -l src/Service/RegistrationService.php
# Expected: No syntax errors detected

# Step 2: Static analysis
docker compose exec php vendor/bin/phpstan analyse \
  src/Service/RegistrationService.php \
  src/Exception/EmailAlreadyExistsException.php \
  --level=9
# Expected: [OK] No errors

# Step 3: Code style
docker compose exec php vendor/bin/php-cs-fixer fix \
  src/Service/RegistrationService.php \
  --dry-run --diff
# Expected: No changes needed

# Step 4: Unit tests (if available)
docker compose exec php vendor/bin/phpunit \
  --filter=RegistrationServiceTest
# Expected: OK (X tests, Y assertions)

Шаг 4: Обработка ошибок (retry loop)

Если верификация провалилась -- AI получает ошибку и пытается исправить.

Attempt 1:
  AI → Code → PHPStan error: "Method return type mismatch"
  → Feed error to AI → AI fixes return type

Attempt 2:
  AI → Fixed code → PHPStan passes → Unit test fails: "Expected exception not thrown"
  → Feed test output to AI → AI adds missing validation

Attempt 3:
  AI → Fixed code → All checks pass → SUCCESS → Commit

Максимум 3 попытки. Если после трёх итераций задача не закрыта:

1. Проанализировать паттерн ошибок -- AI не понимает контекст? Задача слишком сложная? Неверная спецификация?
2. Вмешательство человека -- исправить вручную или переформулировать задачу
3. Обновить спецификацию -- если проблема в спеке, вернуться к фазе Specify

## Retry Log — Task 4.1

### Attempt 1 (Failed)
- Error: PHPStan level 9 — "Parameter $email of method register()
  has no type hint"
- Root cause: AI forgot declare(strict_types=1)
- Fix: AI added strict_types and type hints
- Time: 15 seconds

### Attempt 2 (Failed)
- Error: Unit test — "Expected EmailAlreadyExistsException was not thrown"
- Root cause: AI checked existsByEmail() but should check findByEmail()
  and compare status
- Fix: AI rewrote existence check logic
- Time: 30 seconds

### Attempt 3 (Passed)
- All checks green
- Total time: 2 minutes for 3 attempts

Шаг 5: Коммит после успешной верификации

Каждая успешная задача -- маленький, атомарный коммит.

# After Task 4.1 passes all checks
git add src/Service/RegistrationService.php
git add src/Exception/EmailAlreadyExistsException.php
git commit -m "feat(auth): add RegistrationService with email confirmation"

# After Task 4.2 passes
git add src/Message/SendConfirmationEmailMessage.php
git commit -m "feat(auth): add SendConfirmationEmailMessage"

# After Task 4.3 passes
git add src/MessageHandler/SendConfirmationEmailHandler.php
git commit -m "feat(auth): add email confirmation message handler"

Маленькие коммиты -- ваша страховка. Если задача 5.1 ломает что-то из задачи 4.1, вы видите это сразу и можете откатить конкретный коммит.

Периодическая интеграционная проверка

Помимо верификации каждой задачи, периодически запускайте полный тестовый набор.

# After every 3-5 tasks, run full suite
docker compose exec php vendor/bin/phpunit
docker compose exec php vendor/bin/phpstan analyse src/ --level=9

# Check that nothing is broken across components
docker compose exec php php bin/console cache:clear
docker compose exec php php bin/console debug:router | grep registration

Рекомендуемая частота:

Best Practices фазы Implement

1. Одна задача за раз

Не пытайтесь скормить AI пять задач одновременно. Каждая задача -- отдельный контекст, отдельная верификация, отдельный коммит.

❌ "Implement tasks 4.1, 4.2, 4.3, and 4.4"
✅ "Implement task 4.1: RegistrationService"
   [verify] → commit
   "Implement task 4.2: SendConfirmationEmailMessage"
   [verify] → commit

2. Обновляйте спецификацию по ходу реализации

Реализация всегда выявляет пробелы в спецификации. Это нормально. Но пробелы нужно фиксировать, а не игнорировать.

## Spec Update Log

### During Task 4.1 Implementation
- **Gap found**: Spec didn't define behavior for blocked users
  trying to re-register
- **Decision**: Return generic 409 error (don't reveal user status)
- **Updated**: spec.md section "Edge Cases" — added scenario #9
- **Approved by**: [architect/self]

3. Контекст между задачами

AI не помнит предыдущие задачи (если не используется агентный режим с памятью). При передаче каждой новой задачи -- обновляйте контекст.

## Task 5.1: Create RegistrationController

**What was done before this task:**
- RegistrationService created at src/Service/RegistrationService.php
  - Method: register(string $email, string $password): User
  - Throws: EmailAlreadyExistsException on duplicate active email
- SendConfirmationEmailMessage at src/Message/SendConfirmationEmailMessage.php

**Your task:** Create a thin controller that:
1. Accepts POST /api/v1/auth/register
2. Validates request body (email, password, password_confirmation)
3. Calls RegistrationService::register()
4. Returns 201 with user data on success
5. Returns 400 on validation error
6. Returns 409 on duplicate email

4. Журнал реализации

Ведите лог прогресса. Это помогает отслеживать статус и анализировать проблемы.

## Implementation Log

| Task | Status | Attempts | Time | Notes |
|------|--------|----------|------|-------|
| 1.1 | ✅ Done | 1 | 30s | Clean first attempt |
| 1.2 | ✅ Done | 1 | 30s | Clean first attempt |
| 2.1 | ✅ Done | 2 | 1m | Forgot UUID v7 annotation |
| 2.2 | ✅ Done | 1 | 30s | — |
| 2.3 | ✅ Done | 1 | 45s | — |
| 3.1 | ✅ Done | 1 | 30s | — |
| 3.2 | ✅ Done | 1 | 30s | — |
| 4.1 | ✅ Done | 3 | 2m | Type hint issues, logic fix |
| 4.2 | ✅ Done | 1 | 20s | Simple message class |
| 4.3 | ✅ Done | 2 | 1.5m | Missing interface import |
| 5.1 | 🔄 In progress | — | — | — |
| 5.2 | ⏳ Blocked by 5.1 | — | — | — |

5. Обратная связь в спецификацию (Feedback Loop)

Самая важная часть SDD -- это замкнутый цикл. Инсайты из реализации улучшают будущие спецификации.

Реализация Task 4.1 показала:
  → Нужен TransactionManager для атомарности
  → Спецификация не покрывала concurrent registration race condition
  → Добавить это в шаблон спецификации для будущих фич

Реализация Task 5.1 показала:
  → Symfony Request validation лучше делать через DTO + Validator
  → Добавить в conventions: "Always use DTO for request validation"

Этот feedback loop работает на трех уровнях:

Сквозной пример: все 4 фазы

Пройдем весь цикл SDD для одной маленькой фичи -- добавление rate limiting на регистрацию.

Specify

# Feature: Registration Rate Limiting

## Problem
Registration endpoint is vulnerable to abuse.
Attackers can create thousands of accounts or
use the endpoint for email bombing.

## Success Criteria
- Max 5 registration attempts per IP per hour
- Rate-limited requests get 429 response
- Legitimate users are not affected

## Requirements
- FR-1: Count registration attempts per IP address
- FR-2: Block after 5 attempts in rolling 1-hour window
- FR-3: Return 429 with Retry-After header
- NFR-1: Rate limit check < 5ms (Redis-based)
- NFR-2: No data loss on Redis restart (acceptable: brief unprotected window)

## API Changes
- POST /api/v1/auth/register
  - New response: 429 Too Many Requests
    - Header: Retry-After: <seconds>
    - Body: {"code": 429, "message": "Too many registration attempts"}

Plan

# Implementation Plan: Rate Limiting

## Components
1. Rate limiter configuration (Symfony RateLimiter)
2. Controller update (apply rate limiter)
3. Tests (unit + integration)

## Dependencies
Config → Controller update → Tests

## Steps
1. Configure rate limiter in framework.yaml
2. Apply rate limiter in RegistrationController
3. Write integration tests for rate limiting

## Complexity: Low
## Estimated time: 15 minutes with AI

Tasks

## Task RL-1: Configure Rate Limiter
**Action**: Add to config/packages/framework.yaml:
  - Name: registration_limiter
  - Policy: sliding_window
  - Limit: 5
  - Interval: 1 hour
**Verification**: `php bin/console debug:config framework rate_limiter`

## Task RL-2: Apply Rate Limiter in Controller
**Action**: Inject RateLimiterFactory, consume token,
  throw TooManyRequestsHttpException if exceeded
**Input**: RegistrationController at src/Controller/RegistrationController.php
**Verification**: PHPStan clean, manual curl test

## Task RL-3: Integration Tests
**Action**: Test that 6th request returns 429,
  test Retry-After header, test reset after window
**Verification**: `phpunit --filter=RateLimitTest`

Implement

# Task RL-1: AI generates config
# Verification:
docker compose exec php php bin/console debug:config framework rate_limiter
# ✅ Pass — commit

# Task RL-2: AI updates controller
# Verification:
docker compose exec php vendor/bin/phpstan analyse src/Controller/RegistrationController.php
# ✅ Pass — commit

# Task RL-3: AI writes tests
# Verification:
docker compose exec php vendor/bin/phpunit --filter=RateLimitTest
# ❌ Fail: Redis not available in test environment
# Retry: AI adds Redis mock/in-memory adapter for tests
# ✅ Pass — commit

# Full suite check:
docker compose exec php vendor/bin/phpunit
# ✅ All green

Результат: 3 задачи, 4 попытки (одна ошибка на тестах), 10 минут общего времени. Фича готова, протестирована, задокументирована.

Анти-паттерны фазы Implement

1. "Давай AI всё сделает за один промпт"

❌ "Create a complete user registration system with email confirmation,
   rate limiting, tests, and documentation"

Result: AI generates 500+ lines, 60% wrong, impossible to debug

2. "Я не буду верифицировать, AI же умный"

❌ Accept AI output without running tests or linter

Result: Subtle bugs accumulate, discovered in production

3. "Спецификация не нужна, план в голове"

❌ Jump straight to Implementation without Specify/Plan/Tasks

Result: Constant context-switching between coding and design,
inconsistent output, missed requirements

4. "Retry бесконечно, AI когда-нибудь справится"

❌ Attempt 7: Still the same PHPStan error
   Attempt 8: AI "fixes" by suppressing the error with @phpstan-ignore
   Attempt 9: Different error appears

Result: Wasted time, degraded code quality, frustrated developer

Правило трех попыток: Три retry -- это предел. После третьей неудачной попытки проблема в задаче, а не в AI. Вмешайтесь, переформулируйте, или решите вручную.

Метрики эффективности SDD

Отслеживайте эти метрики, чтобы улучшать процесс:

Если first-attempt success rate ниже 50% -- ваши задачи недостаточно детализированы или контекст неполный. Вернитесь к фазе Tasks и улучшите шаблоны.

Итоги

Фазы Tasks и Implement -- это место, где SDD доказывает свою ценность. Хорошо декомпозированные задачи позволяют AI работать автономно и предсказуемо. Верификация на каждом шаге гарантирует качество. Feedback loop улучшает процесс с каждой итерацией.

Главный принцип: AI -- это исполнитель, а не архитектор. Ваша работа -- дать ему четкие инструкции (Tasks) и проверить результат (Verify). Чем лучше инструкции, тем меньше исправлений. Чем строже верификация, тем выше качество.

SDD в одном предложении:

Specify (ЧТО) → Plan (В КАКОМ ПОРЯДКЕ) → Tasks (КАК ОБЪЯСНИТЬ AI) → Implement (AI ДЕЛАЕТ, ВЫ ПРОВЕРЯЕТЕ)