Amiga
Оглавление курса · урок 11 из 24

Модуль 3 · Датчики и ограничения · урок 11 из 24

Архитектура через инварианты: линтеры и структурные тесты

Агент воспроизводит то, что видит в репозитории, удачные решения вместе с неудачными. Правило «компоненты не ходят в базу напрямую», записанное в AGENTS.md, он выполнит в девяти случаях из десяти. Десятый случай станет образцом для следующих задач. Здесь речь о том, как перевести архитектуру из текста в проверки, которые срабатывают всегда, и как формулировать их ошибки, чтобы агент чинил их сам.

Что говорит источник

Команда OpenAI, описавшая эксперимент в статье Harness engineering, контролирует инварианты, а детали реализации оставляет агенту. Пример из статьи: агент обязан разбирать и проверять форму данных на границе системы, но библиотеку для этого ему не навязывают.

Внутри каждого домена у команды жёсткая слоистая модель: Types → Config → Repo → Service → Runtime → UI. Сквозные аспекты (авторизация, коннекторы, телеметрия, feature flags) входят только через один интерфейс Providers. Всё остальное запрещено, и это проверяется механически, кастомными линтерами (их тоже написал Codex) и структурными тестами. Авторы замечают, что такую архитектуру обычно откладывают, пока в команде не наберётся сотня инженеров, а с агентами она нужна с первого дня.

Оттуда же ещё два принципа. Границы задаются централизованно, а внутри границ у агента есть локальная свобода. Сообщения линтеров об ошибках пишутся как инструкции по исправлению, потому что попадают прямо в контекст агента.

Наш вывод. Если говорить языком Биргитты Бёкелер (подробно о нём в уроке о петлях обратной связи), правило в AGENTS.md работает как вероятностная направляющая, а структурный тест как детерминированный датчик. Правило повышает шанс, что агент решит задачу правильно, тест гарантирует, что неправильное решение не пройдёт. Нужны оба. Без текста агент узнаёт о правиле только после ошибки, без проверки правило со временем перестают соблюдать.

Слои для OctoberCMS-плагина

Слои OpenAI придуманы для их собственного продукта, копировать схему буквально не нужно. Переносится сама идея: у каждого слоя есть разрешённые зависимости, а остальное запрещено. В типичном плагине OctoberCMS это может выглядеть так:

Слой Каталог Можно зависеть от Нельзя
Модели models/ — компонентов, контроллеров, HTTP
Сервисы classes/ моделей компонентов, Request, Session
Компоненты components/ сервисов Db::, прямых запросов к моделям
Контроллеры бэкенда controllers/ сервисов, моделей компонентов фронта
Тема themes/*/pages, partials переменных компонентов бизнес-логики, больших inline-стилей

В мобильном приложении то же самое: data → domain → presentation, и экран не должен импортировать сетевой клиент. Для Kotlin такие правила проверяют библиотеки вроде Konsist или ArchUnit, для PHP есть Deptrac или собственные правила PHPStan. Но начать можно вообще без зависимостей, с обычного теста.

Структурный тест

Структурный тест читает исходники как данные и проверяет связи между ними. Он грубее статического анализатора, зато пишется за полчаса, и агент может сам его расширять.

php · tests/Architecture/LayerBoundariesTest.php
<?php

declare(strict_types=1);

namespace Tests\Architecture;

use PHPUnit\Framework\TestCase;
use RecursiveDirectoryIterator;
use RecursiveIteratorIterator;

final class LayerBoundariesTest extends TestCase
{
    private const PLUGIN = __DIR__ . '/../../src/plugins/acme/shop';

    /** @var array<string, array<string, string>> слой => [запрещённый шаблон => как исправить] */
    private const FORBIDDEN = [
        'components' => [
            '/\bDb::/' => 'Перенесите запрос в сервис в classes/ и вызовите его из компонента.',
            '/^use\s+Acme\\\\Shop\\\\Models\\\\/m' => 'Компонент не читает модели напрямую: добавьте метод в сервис classes/*Service.php.',
        ],
        'classes' => [
            '/\bRequest::|\brequest\(\)/' => 'Сервис не знает об HTTP: передайте нужные значения аргументами из компонента.',
        ],
    ];

    public function testLayersDoNotCrossBoundaries(): void
    {
        $violations = [];
        foreach (self::FORBIDDEN as $layer => $rules) {
            foreach ($this->phpFiles(self::PLUGIN . '/' . $layer) as $file) {
                $code = (string) file_get_contents($file);
                foreach ($rules as $pattern => $fix) {
                    if (preg_match($pattern, $code, $m, PREG_OFFSET_CAPTURE) === 1) {
                        $line = substr_count(substr($code, 0, $m[0][1]), "\n") + 1;
                        $violations[] = sprintf('%s:%d — нарушена граница слоя «%s». %s', $file, $line, $layer, $fix);
                    }
                }
            }
        }
        self::assertSame([], $violations, implode("\n", $violations));
    }

    /** @return list<string> */
    private function phpFiles(string $dir): array
    {
        if (!is_dir($dir)) {
            return [];
        }
        $files = [];
        foreach (new RecursiveIteratorIterator(new RecursiveDirectoryIterator($dir)) as $f) {
            if ($f->isFile() && $f->getExtension() === 'php') {
                $files[] = $f->getPathname();
            }
        }
        return $files;
    }
}

Посмотрите на третий элемент каждой строки отчёта. Тест сообщает, что сломано, и тут же говорит, что делать. Человеку это просто удобно, а агенту даёт следующий шаг.

Сообщение линтера как инструкция

Сравните два сообщения об одной ошибке:

text
partials/hero.htm: inline style found
text
partials/hero.htm:14 — inline <style> длиннее 10 строк.
Перенесите правила в resources/scss/pages/<slug>.scss, подключите бандл
страницы через vite в layout и пересоберите: cd src/themes/amiga && npm run build.
Правило: docs/CODESTYLE_BACK_FRONT.md, раздел 3.4.

По первому сообщению агент исправит ошибку как придётся. Например, переложит стили в атрибут style и формально пройдёт проверку. Второе задаёт безопасный путь и ссылается на систему записи. Хорошее сообщение отвечает на четыре вопроса: где ошибка, какое правило нарушено, как исправить и где прочитать подробнее.

Простой линтер под такое правило занимает десяток строк:

bash · scripts/lint/inline-assets.sh
#!/usr/bin/env bash
set -euo pipefail
status=0
while IFS= read -r file; do
  lines=$(awk '/<style/{f=1} f{n++} /<\/style>/{f=0} END{print n+0}' "$file")
  if [ "$lines" -gt 10 ]; then
    echo "$file — inline <style> на $lines строк. Перенесите в resources/scss/pages/, см. docs/CODESTYLE_BACK_FRONT.md §3.4"
    status=1
  fi
done < <(find src/themes -name '*.htm')
exit $status

Вкусовые инварианты

OpenAI выделяет отдельную группу, taste invariants: структурированное логирование, правила именования схем и типов, лимиты размера файлов, платформенные требования к надёжности. Раньше ревьюер писал о таком в комментариях к каждому третьему MR. В агентстве этот список легко продолжить: declare(strict_types=1) в каждом PHP-файле, BEM в SCSS, запрет console.log в собранном JS, лимит длины метода, обязательный data-testid у интерактивных элементов, на которые опираются Playwright-тесты.

Отбирать правила просто. Если замечание звучит в ревью третий раз, его надо перенести из памяти ревьюера в проверку. В best practices Codex советуют то же самое: добавлять правила после повторяющихся ошибок, заранее их не выдумывать.

Где это ломается

Первая проблема — ложные срабатывания. Регулярное выражение поймает Db:: в комментарии. Заведите явный список исключений, где у каждого указаны причина и срок, и не отключайте тест «временно». Иначе агент усвоит, что правила можно выключать.

Вторая — легаси. На существующем проекте тест сразу упадёт в сотнях мест. Зафиксируйте текущие нарушения в baseline-файле и проверяйте только новые. Сокращать baseline можно фоновой задачей, об этом урок об энтропии.

Третья — слишком жёсткие рамки. Бёкелер называет свойство кодовой базы harnessability: строгие типы и явные границы модулей облегчают построение обвязки. Но каждое правило сужает пространство решений. Если агент регулярно упирается в инвариант и решает задачу в обход, возможно, ошибается сам инвариант. В OpenAI на этот счёт считают так: код не обязан совпадать со вкусом людей, если он корректен, поддерживаем и читаем для будущих запусков агента.

Последний вопрос — кто пишет правила. В эксперименте OpenAI линтеры писал Codex. Это разумное разделение: человек формулирует правило, а агент кодирует проверку и прогоняет её по истории репозитория.

Попробуйте сами

10–15 мин на рабочем месте
  1. Откройте последние десять MR своего проекта и выпишите замечания ревьюеров, которые повторялись. Выберите одно, которое можно проверить механически.
  2. Попросите Codex превратить его в структурный тест или линтер: «Напиши тест в tests/Architecture, который ловит это нарушение. Сообщение об ошибке должно содержать файл, строку, правило и конкретный способ исправления. Прогони тест на текущем коде и покажи нарушения».
  3. Если нарушений много, попросите сделать baseline-файл и проверять только новые случаи. Затем добавьте строку о тесте в AGENTS.md.

Коротко

  • Проверяйте инварианты, а не детали реализации: «данные валидируются на границе», а не «используем библиотеку X».
  • Слои и разрешённые зависимости дешевле всего мешают агенту размножить неудачный шаблон.
  • Структурный тест на PHPUnit пишется за полчаса и не требует новых зависимостей.
  • Сообщение об ошибке читается агентом как промпт: где, какое правило, как исправить, где читать.
  • Повторяющееся замечание ревью переносите в проверку, а в легаси заводите baseline и ловите только новые нарушения.
Отметка хранится только в вашем браузере
Хотите связаться с владельцем
компании напрямую?
Дмитрий Тарасов
Дмитрий Тарасов
СЕО

НАПИСАТЬ

Написать в MAX