Модуль 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
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;
}
}Посмотрите на третий элемент каждой строки отчёта. Тест сообщает, что сломано, и тут же говорит, что делать. Человеку это просто удобно, а агенту даёт следующий шаг.
Сообщение линтера как инструкция
Сравните два сообщения об одной ошибке:
partials/hero.htm: inline style foundpartials/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 и формально пройдёт проверку. Второе задаёт безопасный путь и ссылается на систему записи. Хорошее сообщение отвечает на четыре вопроса: где ошибка, какое правило нарушено, как исправить и где прочитать подробнее.
Простой линтер под такое правило занимает десяток строк:
#!/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 мин на рабочем месте- Откройте последние десять MR своего проекта и выпишите замечания ревьюеров, которые повторялись. Выберите одно, которое можно проверить механически.
- Попросите Codex превратить его в структурный тест или линтер: «Напиши тест в tests/Architecture, который ловит это нарушение. Сообщение об ошибке должно содержать файл, строку, правило и конкретный способ исправления. Прогони тест на текущем коде и покажи нарушения».
- Если нарушений много, попросите сделать baseline-файл и проверять только новые случаи. Затем добавьте строку о тесте в AGENTS.md.
Коротко
- Проверяйте инварианты, а не детали реализации: «данные валидируются на границе», а не «используем библиотеку X».
- Слои и разрешённые зависимости дешевле всего мешают агенту размножить неудачный шаблон.
- Структурный тест на PHPUnit пишется за полчаса и не требует новых зависимостей.
- Сообщение об ошибке читается агентом как промпт: где, какое правило, как исправить, где читать.
- Повторяющееся замечание ревью переносите в проверку, а в легаси заводите baseline и ловите только новые нарушения.