ErgocodeAI Agent Framework

ErgocodeAI учит ваших ИИ-агентов работать по Эргономичному подходу:

1. вести разработку через тесты (TDD);
2. писать быстрые, надёжные и устойчивые к рефакторингу тесты;
3. разделять сложную логику (бизнес-логику, вычисления, трансформации) и ввод-вывод (действия, эффекты);
4. декомпозировать систему на небольшие сфокусированные модули с низкой сцепленностью;

Warning

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

Note

На данный момент соглашения, примеры и готовые процессы в первую очередь ориентированы на Kotlin и Spring Boot. Общие архитектурные и процессные идеи не зависят от стека, но их применение с другими технологиями потребует адаптации контекста.

Note

На данный момент фреймворк ориентирован в первую очередь на Codex и модели OpenAI.

Варианты использования фреймворка

Фреймворк поддерживает три способа использования:

1. Prompt-driven — вы ставите задачи как привыкли, агент автоматичски применяет релевантные соглашения фреймворка.
2. Skill-driven — вы явно выбираете скилл для решения очередной задачи.
3. Workflow-driven — агент идёт сам по процессу фреймворка, обращаясь к вам с вопросами и останавливаясь для ревью в ключевых точках.

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

Работа с фреймворком в Skill-driven варианте

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

Базовый поток реализации одного изменения:

1. Спроектировать тест-кейс проверки наблюдаемого поведения через $design-test-case.
2. При необходимости согласовать требуемые интерфейсы через $align-required-design.
3. Закодировать кейс через $code-test-case.
4. Реализовать кейс минимальным изменением production-кода через $fix-red-case.
5. Выполнить рефакторинг через $refactor-case.

Перед основным циклом при необходимости можно описать API через $describe-rest-api или найти связанные участки кода через $collect-code-anchors. Перед изменением production-кода можно подготовить план исправления одного красного кейса через $plan-test-case-fixing.

Работа с фреймворком в Workflow-driven варианте

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

Затем, по мере реализации, спецификации задачи и решения дополняются деталями или даже сущственно меняются, если в процессе реализации выяснилось, что первоначальный план оказался неудачным.

Подготовка задачи

1. Подготовьте рабочую директорию с помощью $prepare-task-workdir. Скилл в диалоге заполняет 010-task-brief.md, при необходимости собирает 020-code-anchors.md, формирует варианты решения и после явного выбора заполняет 030-solution-brief.md.
2. При необходимости добавьте другие артефакты 010-*, 020-* и 030-* с существенными сведениями о задаче, текущей реализации и целевом решении.
3. При необходимости добавьте стартовые задачи в todo.md.

Note

Коды артефактов

Код в начале имени файла обозначает назначение артефакта в рабочей директории задачи:

• 010-* — постановка задачи: требования и исходные материалы;
• 020-* — описание текущего состояния системы;
• 030-* — описание целевого состояния и выбранного решения;
• 040-* — рабочие файлы реализации.

Файл todo.md хранит прогресс реализации и используется без числового кода. Полный контракт рабочей директории описан в соглашении о задачах. Для создания пустой рабочей директории без подготовки брифов используйте $init-task-workdir.

Минимальная директория задачи имеет следующий вид:

devlog/123-example-task/
├── 010-task-brief.md
├── 030-solution-brief.md
└── todo.md

После сбора первичной спецификации итеративно выполняйте шаги до завершения реализации задачи.

Поток реализации одного шага задачи

1. Выбрать следующий минимальный инкремент из спецификации и todo.md ($select-next-increment).
2. Спроектировать и записать тест-кейс проверки целевого поведения в 030-test-cases-new.md ($design-test-case).
3. При необходимости согласовать требуемые интерфейсы ($align-required-design); скилл сам вызовет $describe-rest-api для нового или изменённого JSON-over-HTTP контракта.
4. Закодировать тест ($code-test-case).
5. Спроектировать и спланировать реализацию кейса ($plan-test-case-fixing).
6. Реализовать кейс ($fix-red-case).
7. Отрефакторить реализацию ($refactor-case).
8. Обновить todo.md.

Для явно нового SUT тест-кейс может сначала содержать Feature без технической ссылки. $align-required-design проектирует недостающий интерфейс и дополняет Feature точной ссылкой на SUT; до этого кодирование теста не начинается.

Итерации можно вести в трёх режимах:

1. Ручном - самостоятельно выбираете что делать дальше, вызываете соответствующий скилл и обновляете рабоиче файлы задачи;
2. Полуавтоматическом - используйте скилл $implement-task-tdd, чтобы агент сам полностью реализовал задачу до конца, останавливаясь на ревью после записи тест-кейса и в других ключевых точках, но не между озеленением кейса и запуском рефакторинга.
3. Автоматическом - используйте скилл $implement-task-tdd с указанием не останавливаться на ревью, чтобы агент сам полностью реализовал задачу до конца.

Warning

Автоматический режим очень жадный до токенов и может сжечь весь недельный лимит на одной задаче.

Доработка контекста

В случае если агент допустил ошибку, используйте $fix-project-context или $fix-framework-context для коррекции контекста, чтобы предотвратить повторение ошибки в будущем.

• $fix-project-context изменяет AGENTS.md, .agents/**, .codex/** и другие agent-facing инструкции конкретного проекта, не затрагивая runtime-контекст Ergocode.
• $fix-framework-context изменяет общий runtime-контекст ErgocodeAI под src/**;

Передайте выбранному скиллу описание проблемы, требуемое поведение и, при наличии, id Codex-сессии с примером неправильной работы:

Используй $fix-project-context.

codex session id: <необязательно>
problem: <что в текущем контексте приводит к неправильной работе агента или что агент сделал не так в сессии Codex>
target behavior: <как агент должен действовать после изменения>

Устройство фреймворка

Фреймворк разделяет базовый контекст, ответственность агента, инженерные правила, исполняемые процессы и память конкретной задачи.

flowchart TD
    Project[Контекст проекта<br/>AGENTS.md, .agents/, .codex/] --> Baseline[Базовый контекст<br/>project-baseline.md]
    Baseline --> Roles[Индекс ролей<br/>roles.md]
    Roles --> Role[Роль<br/>roles/*.md]
    Role --> Conventions[Конвенции<br/>conventions/**]
    Skill[Скилл<br/>skills/**/SKILL.md] --> Role
    Skill --> Conventions
    Skill --> Artifacts[Форматы артефактов<br/>artifacts/**]
    Skill <--> Task[Контекст задачи<br/>devlog/**]

Loading

Слой	Назначение
bootstrap/	Устанавливает фреймворк в целевой репозиторий и подключает обязательный SessionStart hook.
src/project-baseline.md	Задаёт минимальные правила загрузки контекста и работы с задачами.
src/roles/	Определяет ответственность и границы текущей роли агента.
src/conventions/	Хранит архитектурные, кодовые, тестовые и процессные соглашения.
src/skills/	Описывает воспроизводимые рабочие процессы с входами, этапами, проверками и результатами.
src/artifacts/	Задаёт форматы проверяемых промежуточных результатов.
devlog/ целевого проекта	Хранит постановку, анализ, целевое решение и прогресс конкретной задачи.
AGENTS.md целевого проекта	Интегрирует фреймворк с проектными и локальными правилами.

Поддерживаемые агенты

Установка и runtime-интеграция сейчас поддерживают только Codex. Для других агентов фреймворк скорее всего придётся адаптировать.

Для адаптации фреймворка другой агент должен уметь:

• загружать репозиторные инструкции и дополнительные Markdown-файлы по ссылкам;
• резолвить символические ссылки;
• выбирать и явно исполнять процессы, описанные в SKILL.md;
• выполнять startup hook или предоставлять эквивалентный механизм загрузки baseline-контекста;
• запускать отдельные последовательные субагенты для автоматического TDD-цикла.

Без последней возможности остаются доступны неявный и ручной способы применения после адаптации загрузчика контекста.

Установка для Codex

1. Добавьте репозиторий фреймворка в целевой проект. Рекомендуемый вариант — Git submodule в .agents/ergo:

   git submodule add https://github.com/ergonomic-code/dot-agents.git .agents/ergo

   Также можно скопировать репозиторий или создать symlink на него.

2. Попросите Codex выполнить установочный скилл:

   Install the framework in this repository using [SKILL.md](.agents/ergo/bootstrap/skills/installing-framework/SKILL.md).
   

3. Ответьте на вопросы установщика о расположении framework config, если они появятся.

Установщик идемпотентно обновляет framework-секцию в AGENTS.md, подключает скиллы и настраивает Codex hook, сохраняя несвязанные проектные инструкции.

Текущие скиллы

Скилл	Назначение
$advance-task	Определяет и выполняет одну следующую стадию TDD-инкремента.
$align-required-design	Проектирует и фиксирует только интерфейсы, необходимые для кодирования одного выбранного тест-кейса.
$code-test-case	Преобразует проверку в формате verification-check-format-v0.1 в Kotlin JUnit-тест, затем в репозитории проверяет, что тест падает из-за отсутствующего поведения или уже проходит.
$collect-code-anchors	Находит связанные с требуемым поведением участки кода, модели, запросы, таблицы, конфигурацию и другие якоря в коде.
$describe-rest-api	Строит, валидирует и отображает описание REST API по коду, OpenAPI, требованиям или другим входным данным.
$design-test-case	Проектирует одну проверку размером с тестовый метод и при заданном пути записывает её в артефакт.
$find-touched-tables	Определяет таблицы и представления, затрагиваемые кодом на готовой диаграмме structure-chart/v1.
$fix-framework-context	Анализирует и после выбора варианта изменяет общий runtime-контекст Ergocode.
$fix-project-context	Анализирует и после выбора варианта изменяет agent-facing контекст конкретного проекта.
$fix-red-case	Изменяет production-код, чтобы сделать зелёным один красный Kotlin JUnit-тест.
$implement-task-tdd	Координирует реализацию задачи минимальными TDD-инкрементами с субагентами и ревью в определённых точках; после green сразу запускает рефакторинг.
$init-task-workdir	Создаёт директорию задачи devlog/NNN-slug с обязательными рабочими файлами из шаблонов.
$plan-test-case-fixing	Исследует один красный тест-кейс и составляет план его реализации.
$prepare-task-workdir	В диалоге подготавливает бриф задачи, якори в коде и выбранное направление решения.
$refactor-case	Полностью проверяет один зелёный TDD-инкремент, группирует совместимые узкие рефакторинги и сообщает оставшиеся кандидаты.
$select-next-increment	Выбирает следующий минимальный нереализованный вертикальный инкремент.
$write-verification-check	Описывает один тест-кейс в стандартном Gherkin-подобном формате.