Агент в старом проекте: как подготовить legacy и внедрять постепенно

Агенту нужны карта и обратная связь

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

Две вещи решают почти всё:

• Карта. Где модули, какие правила, что нельзя трогать. Это файл правил для агента и короткие README.
• Обратная связь. Одна команда, которая за минуты говорит: «всё хорошо» или «сломано вот тут». Тесты, линтер, проверка типов.

Семь паттернов AI-First

1. Карта проекта и правила. AGENTS.md (или CLAUDE.md) в корне: как запустить, как проверить, правила кода, запреты. Короткие README в ключевых модулях.
2. Быстрая обратная связь. Одна команда make check или composer check: тесты, линтер, статический анализ. Чем быстрее, тем чаще агент её запускает.
3. Характеризационные тесты. Перед правкой старого кода фиксируем, как он работает сейчас, даже если странно. Агент правит — тест показывает, что поведение не уехало.
4. Границы модулей и контракты. Чем меньше модуль связан с остальными, тем меньше контекста нужно агенту и тем меньше он сломает.
5. Генераторы для шаблонного. CRUD, DTO, клиенты API делает генератор, а не агент (урок 6). Быстрее, дешевле, одинаково.
6. Спецификации для изменений. Новая функциональность начинается со спеки, а не с «сделай фичу» (урок 5).
7. Постепенное внедрение. Сначала безопасные задачи, потом средние, потом сложные. На каждом шаге — метрики.

# Магазин — правила для агента

## Запуск и проверка
- Поднять: `docker compose up -d`
- Проверить всё: `make check` (тесты + PHPStan + php-cs-fixer, ~3 мин)
- Один тест: `vendor/bin/phpunit --filter ИмяТеста`

## Карта
- `src/Order/` — заказы и расчёт цены. Владелец: команда Checkout.
- `src/Billing/` — платежи. Любая правка — только с тестом.
- `legacy/` — старый код. Не рефакторить без характеризационных тестов.

## Правила
- Деньги — только в копейках (int), никаких float.
- Миграции БД не писать без отдельной задачи.
- Не трогать `config/secrets/` и `.env`.

## Готово, если
- `make check` зелёный;
- на новое поведение есть тест;
- в описании PR — что и зачем изменено.

{
  "scripts": {
    "test": "phpunit",
    "stan": "phpstan analyse --no-progress",
    "cs": "php-cs-fixer fix --dry-run --diff",
    "check": ["@cs", "@stan", "@test"]
  }
}

{
  "scripts": {
    "lint": "eslint .",
    "typecheck": "tsc --noEmit",
    "test": "vitest run",
    "check": "npm run lint && npm run typecheck && npm test"
  }
}

.PHONY: check
check:
	ruff check .
	mypy src
	pytest -q

Как внедрять, не ломая систему и команду

Лестница задач. Сначала агент только читает и объясняет код. Потом пишет тесты и документацию. Потом чинит мелкие баги, где есть тест. Потом делает средние фичи по спеке. Сложные изменения с деньгами и миграциями — последними и с человеком на ключевых шагах.

Удушающее дерево (strangler fig). Старый модуль не переписывают целиком. Ставят перед ним фасад и по одной функции переносят в новый код. Новый код агент пишет по спеке и с тестами, старый тем временем продолжает работать.

Метрики внедрения. Сколько задач решено с агентом, время от задачи до PR, доля откатов и регрессий, стоимость на задачу. Если откатов стало больше — притормозите и усильте проверки.

Люди и процесс. За код агента отвечает человек, который открыл PR. Ревью остаётся. Команде нужно обучение: как ставить задачи, как читать сессию агента, когда остановить его.

<?php
use PHPUnit\Framework\Attributes\DataProvider;
use PHPUnit\Framework\TestCase;

final class LegacyShippingCharacterizationTest extends TestCase
{
    // Значения сняты с текущего прода. Странное (бесплатно при 0 кг) — тоже фиксируем.
    public static function cases(): iterable
    {
        yield 'лёгкая посылка' => [0.5, 'MINSK', 350];
        yield 'тяжёлая посылка' => [12.0, 'MINSK', 1890];
        yield 'регион' => [2.0, 'BREST', 790];
        yield 'вес 0 — так сейчас' => [0.0, 'MINSK', 0];
    }

    #[DataProvider('cases')]
    public function testKeepsCurrentBehaviour(float $kg, string $city, int $expectedKopecks): void
    {
        self::assertSame($expectedKopecks, legacy_calc_shipping($kg, $city));
    }
}

import pytest
from legacy.shipping import calc_shipping

# Значения сняты с текущего поведения. Не «как должно быть», а «как есть».
@pytest.mark.parametrize("kg, city, expected", [
    (0.5, "MINSK", 350),
    (12.0, "MINSK", 1890),
    (2.0, "BREST", 790),
    (0.0, "MINSK", 0),   # странно, но так сейчас работает прод
])
def test_keeps_current_behaviour(kg, city, expected):
    assert calc_shipping(kg, city) == expected

import { test } from "node:test";
import assert from "node:assert/strict";
import { calcShipping } from "../legacy/shipping.js";

const cases = [
  [0.5, "MINSK", 350],
  [12.0, "MINSK", 1890],
  [2.0, "BREST", 790],
  [0.0, "MINSK", 0], // фиксируем как есть
];

for (const [kg, city, expected] of cases) {
  test(`доставка ${kg} кг в ${city}`, () => {
    assert.equal(calcShipping(kg, city), expected);
  });
}