ErgocodeAI Agent Framework

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

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

Warning

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

Note

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

Note

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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-* — рабочие файлы реализации.

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

Для создания пустой рабочей директории без подготовки брифов используйте $init-task-workdir.

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

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

work-state.md перезаписывается как актуальная контрольная точка для продолжения задачи в другой сессии или на другой машине и автоматически входит в контекст активной задачи, если содержит полезное состояние помимо структуры шаблона. todo.md при этом остаётся списком запланированных и завершённых работ, а не журналом выполнения или состоянием передачи работы.

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

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

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 для коррекции контекста, чтобы предотвратить повторение ошибки в будущем.

• $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
    SessionStart[Codex SessionStart] --> Baseline[Базовый контекст<br/>project-baseline.md]
    SessionStart --> Context[Корневой роутинг контекста<br/>context/index.md]
    SessionStart --> Config[Опциональная конфигурация фреймворка]
    Context --> ContextIndexes[Тематические индексы<br/>context/*.md]
    ContextIndexes --> RoutedContext[Соглашения и справочные материалы<br/>conventions/, references/, patterns/, artifacts/]
    Baseline --> 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

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

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

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

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

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

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

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

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

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

Установка для 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, подключает generic-скиллы через .agents/skills/ergo, task-workdir-скиллы через .agents/skills/ergo-task-workdir и настраивает Codex hook, сохраняя несвязанные проектные инструкции. Обе коллекции подключаются отдельными прямыми symlink, поэтому установка не зависит от рекурсивного обнаружения скиллов.

Generic-скиллы

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

Task-workdir-скиллы

Скилл	Назначение
$init-task-workdir	Создаёт директорию задачи devlog/NNN-slug с обязательными рабочими файлами из шаблонов.
$prepare-task-workdir	В диалоге подготавливает бриф задачи, якори в коде и выбранное направление решения.
$select-next-increment	Выбирает следующий минимальный нереализованный инкремент.