GOAL.md — автономная оптимизация проектов с помощью AI-агентов

Karpathy доказал формулу: AI-агент + фитнес-функция + цикл = ночные прорывы. Его проект autoresearch показывает, как агент может бесконечно улучшать модель, пока человек спит. Но autoresearch работает только тогда, когда метрика уже существует — loss уменьшается, статья становится лучше. Большинство проектов не такие. Метрику нужно сначала построить, прежде чем оптимизировать.

GOAL.md — это паттерн и формат файла, который обобщает подход autoresearch на любой программный проект. Один файл в репозитории превращает кодинг-агента (Claude, Cursor, Windsurf или любой другой) в автономного оптимизатора.

Как это появилось

Автор проекта столкнулся с проблемой: 30 Playwright-тестов для системы роутинга, половина сломана, и непонятно какие. Нужно было не «починить тесты», а придумать, как измерить надёжность тестовой инфраструктуры. Никакого инструмента для этого не существовало.

Он сконструировал составную метрику — четыре взвешенных компонента, определяющих «routing confidence»:

═══════════════════════════════════════════
  routing confidence: 47 / 100 (47%)
═══════════════════════════════════════════

    health                       ✗ 0.42
    accuracy                     ◐ 0.61
    coverage                     ◐ 0.67
    consistency                  ✗ 0.38

Затем написал файл с инструкциями для Claude: вот оценка, вот как её повысить, вот когда остановиться. Утром — 12 атомарных коммитов, каждый увеличивает оценку. С 47 до 83.

Почему не просто хороший CLAUDE.md

CLAUDE.md — это инструкция. Она говорит агенту, как работать в репозитории. GOAL.md — это функция вознаграждения. Она определяет, что значит «лучше», и даёт цикл для достижения цели. Агент измеряет, диагностирует, действует и верифицирует самостоятельно.

Пять элементов GOAL.md

1. Фитнес-функция

Не ощущение, а число. Агенту нужна вычислимая функция, определяющая «лучше»:

./scripts/score.sh    # → 47/100... потом 52... потом 61... потом 83

Три режима управления оценкой:

Split-режим — самый практичный. Используются две оценки: «работает ли система?» и «можно ли доверять тестам?». Агент может точить инструмент, не играя с результатом.

2. Цикл улучшений

repeat:
  1. Запустить фитнес-функцию
  2. Найти самый слабый компонент
  3. Выбрать действие с наибольшим эффектом
  4. Внести изменение
  5. Переизмерить
  6. Улучшилось? Коммит. Регресс? Откат.

Каждая итерация записывает одну строку в iterations.jsonl — оценки до/после, действие, результат. Будущие сессии читают лог, чтобы не повторять неудачные эксперименты.

3. Каталог действий

Таблица конкретных действий с оценкой влияния:

Оценки — это сигналы приоритизации, не точные прогнозы. Они помогают агенту не тратить время на мелочи, когда есть крупные выигрыши.

4. Режим работы

5. Ограничения

Строгие правила, которые агент не может нарушать:

- Никогда не фабриковать результаты тестов
- Никогда не модифицировать credentials
- Всегда измерять до и после — оценка не должна снижаться
- Атомарные коммиты — по одному улучшению, чтобы откаты были чистыми

Без ограничений агент обязательно найдёт «креативные» способы увеличить число, которые вы не предусматривали.

Двойная система оценки

Самый интересный паттерн — двойной скоринг. Когда агент измеряет качество документации, линтер может быть сломан (например, Vale помечает onChange как опечатку). Наивный агент «исправит» документацию под линтер, сделав её хуже.

Решение: две оценки — качество документации и качество инструмента измерения. Агент сначала чинит свой «телескоп», потом через него наблюдает за звёздами.

Примеры использования

В репозитории есть готовые примеры GOAL.md для разных доменов:

Как начать

Быстрый путь — направить агента на репозиторий:

Read github.com/jmilinovich/goal-md — read the template and examples.
Then write me a GOAL.md for this repo and start working on it.

Ручной путь:

1. Скопировать template/GOAL.md в свой репозиторий
2. Определить фитнес-функцию (скрипт, выводящий число)
3. Заполнить цикл улучшений и каталог действий
4. Направить агента и запустить

Когда нужен GOAL.md

Когда работа — это цикл оптимизации, а не разовая задача. Когда «лучше» требует метрики, которую нужно сконструировать, а не просто «тесты проходят». Когда хочется лечь спать и утром увидеть прогресс.

Не нужен для одиночных чётких задач («добавить переключатель тёмной темы») или когда «готово» очевидно.