Фреймворк ИИ-агентов ErgocodeAi

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

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

Warning

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

Note

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

Note

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

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

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

1. Через обычные запросы — вы ставите задачи как привыкли, агент автоматически применяет релевантные соглашения фреймворка.
2. Через скиллы — вы явно выбираете скилл для решения очередной задачи.

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

Работа с фреймворком через скиллы

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

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

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

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

Работа над задачами в нескольких сессиях

Контекст задачи хранится в отдельной директории и дополняется по мере работы. Директория создаётся только по явному запросу пользователя через $init-task-workdir. В новой сессии укажите код задачи в первой строке запроса.

Минимальная директория задачи:

devlog/123-example-task/
├── 010-task-brief.md
├── todo.md
└── work-state.md

• 010-task-brief.md — что требуется, критерии завершения и приёмка; общий контекст по необходимости.
• todo.md — сделанные и предстоящие подзадачи; подзаголовки и вложенные маркерные списки по потребности.
• work-state.md — актуальное состояние для продолжения в другой сессии: намерения, существенные результаты, ближайшие шаги и неочевидные или дорогие для повторного получения факты.

Агент обновляет соответствующие файлы по ходу работы при появлении новых сведений, устаревании записанных или по указанию пользователя. Загрузчик автоматически включает бриф, содержательные todo.md и work-state.md в контекст выбранной задачи. Дополнительные материалы создаются по необходимости. Правила хранения и ведения памяти описаны в контексте задач.

Для легковесной подготовки любой задачи используйте $prepare-task-workdir: агент проведёт интервью, согласует постановку и актуализирует бриф, todo.md и work-state.md.

Структурированный процесс разработки

При необходимости подготовки решения используйте $prepare-development-task. Скилл сначала выполняет $prepare-task-workdir, затем в 030-solution-brief.md записывает, как техлид хочет реализовать задачу. При необходимости собирает якори в коде и помогает сравнить и выбрать ещё не определённые решения. Уже согласованная постановка при неизменных требованиях используется без повторного интервью. Для новой задачи явно запросите создание директории; для существующей укажите её код или путь.

Бриф решения, API, тестовые кейсы и дизайн не входят в обязательную память задачи. Они добавляются по необходимости подготовки и реализации; их назначение, коды файлов и привязки описаны в справочнике процесса разработки. Структурированный процесс предполагает первоначальное согласование основных требований и направления решения с последующей детализацией по мере реализации.

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

1. Выбрать следующий минимальный инкремент из спецификации и todo.md ($select-next-increment).
2. Спроектировать и записать тест-кейс проверки целевого поведения в 030-test-cases-new.md ($design-test-case).
3. Закодировать тест ($code-test-case).
4. Реализовать кейс ($fix-red-case).
5. Отрефакторить реализацию ($refactor-case).
6. Обновить todo.md.

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

Для исправления ошибки агента или добавления нового поведения выбирайте скилл по каноническому пути изменяемого файла после разрешения симлинков:

• $fix-project-context изменяет локальные инструкции агента целевого проекта.
• $fix-framework-context изменяет поставляемые фреймворком файлы под src/**, bootstrap/** и docs/** как из репозитория фреймворка, так и из целевого проекта.
• $fix-self-context изменяет AGENTS.md, .agents/** и .codex/** самого репозитория фреймворка.

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

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

сессия: <необязательно>

целевое поведение: <как агент должен действовать после изменения>
что агент седал не так: <необязательно; что агент сделал неправильно>

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

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

flowchart TD
    SessionStart[Codex SessionStart] --> Baseline[Базовый контекст<br/>project-baseline.md]
    SessionStart --> Context[Корневой роутинг контекста<br/>context/index.md]
    SessionStart -->  ContextIndexes[Доступные тематические индексы<br/>context/*.md]
    Baseline --> TaskEntry[Подключение задачи<br/>task-workdir/entrypoint.md]
    TaskEntry --> TaskLoader[Загрузчик контекста задачи<br/>task-workdir/load_task_context.py]
    TaskLoader --> TaskResolver[Резолвер задачи<br/>task-workdir/resolve_task.py]
    TaskLoader -. при наличии задачи .-> TaskModule[Модуль task-workdir<br/>task-workdir/context.md]
    TaskModule --> Skill[Применимый скилл<br/>skills/**/SKILL.md]
    Caller[Вызывающая сторона] --> Skill
    Skill --> Intrinsic[Внутренние зависимости скилла]
    Skill --> Artifacts[Форматы артефактов<br/>artifacts/**]
    TaskModule <--> Task[Контекст задачи<br/>devlog/**]

Loading

В первом ходе базовый контекст подключает протокол task-workdir/entrypoint.md, который задаёт однократный вызов загрузчика контекста задачи и использование его вывода напрямую. Резолвер учитывает только идентификаторы активных задач, явно указанные отдельной строкой или сразу после ссылки на скилл, а при нескольких кандидатах изолированно выбирает единственное ясное соответствие по брифам. Загрузчик вызывает резолвер и собирает контекст из правил памяти задачи, брифа выбранной задачи и существующих содержательных todo.md и work-state.md либо сообщает об отсутствии активной задачи. После разрешения задачи модуль передаёт применимой операции конкретные привязки артефактов как явные смысловые входы и разрешённые вызывающей стороной пути результатов.

Хук SessionStart детерминированно загружает project-baseline.md, общий протокол context/index.md с маршрутами, отфильтрованными по конфигурации, и затем саму конфигурацию. Тела тематических индексов и соглашений при старте не загружаются: агент выбирает применимые индексы только внутри разрешённого списка. Изменение задачи не расширяет подтверждённый набор модулей.

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

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

Каждый файл в src/conventions/ объявляет в заголовке YAML хотя бы одно ключевое слово; рекомендуется использовать не более трёх. Ключевые слова образуют пересечение: каждое правило файла относится ко всем объявленным словам, а правила с другим пересечением находятся в отдельном файле и маршрутизируются независимо.

Соглашения компонуются выбираемыми модулями; core обязателен, а тематические пересечения становятся доступны автоматически только при наличии всех требуемых модулей. Назначение модулей, признаки их выбора и доступные пересечения описаны в каталоге модулей. Метаданные каждого тематического индекса задают требуемые модули, условие применимости и порядок маршрутизации рядом с самим маршрутом. Общий протокол загружает все применимые доступные индексы по затронутому коду, подтверждённым зависимостям и явно указанному стеку, а не по наличию технологии где-либо в репозитории. Фильтрация ограничивает вывод стартового хука и разрешённые пути загрузки фреймворка, но не удаляет не используемые файлы из директории фреймворка и не запрещает агенту читать эти файлы обычными средствами.

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

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

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

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

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

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

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

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

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

   Установи фреймворк в этот репозиторий с помощью [SKILL.md](.agents/ergo/bootstrap/skills/installing-framework/SKILL.md).
   

3. Ответьте на вопросы агента о подключении модулей и местоположении файла ergo-config.yaml.

Новая установка обязательно создаёт ergo-config.yaml; например:

artifact_language: ru
modules:
  - core
  - kotlin
  - junit

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

Установщик идемпотентно обновляет секцию фреймворка в AGENTS.md, подключает общие скиллы через .agents/skills/ergo, скиллы работы с задачми через .agents/skills/ergo-task-workdir, проверяет доступность PyYAML и настраивает хук Codex, сохраняя несвязанные проектные инструкции.

Общие скиллы

Скилл	Назначение
$code-test-case	Кодирует один тест-кейс в формате test-case-specification-format.
$collect-code-anchors	Находит связанные с требуемым поведением участки кода, модели, запросы, таблицы, конфигурацию и другие якоря в коде.
$describe-rest-api	Пишет человекочитаемое описание REST API по коду, OpenAPI, требованиям или другим входным данным.
$design-test-case	Проектирует один тест-кейс по описанию целевого поведения.
$fix-framework-context	Обновляет контекст, поставляемый фреймворком целевым проектам.
$fix-project-context	Обновляет контекст для агентов конкретного проекта для исправления ошибок в поведении агента.
$fix-red-case	Реализует поведение, специфицированное одним тест-кейсом.
$refactor-case	Выполняет ревью одного TDD-инкремента.
$save-session-evidence	Сохраняет свидетельства ошибки сессии и Git-снимок для последующего исправления.

Скиллы рабочей директории задачи

Скилл	Назначение
$init-task-workdir	По явному запросу создаёт директорию задачи с брифом, todo.md и work-state.md.
$prepare-task-workdir	Через интервью согласует постановку задачи любого типа и актуализирует бриф, todo.md и work-state.md.
$prepare-development-task	Выполняет легковесную подготовку, затем собирает необходимые якори в коде и согласует техническое решение для задачи на разработку по структурированному процессу.
$select-next-increment	Выбирает следующий минимальный нереализованный инкремент.