Agentica

Spec Driven фреймворк для агентного кодинга. Вдохновлен SpecKit, но исповедует Developer-first подход.

В то время как другие инструменты работают в пространстве "продукта" (User Stories, Vibe Coding), Agentica работает в пространстве "архитектора", предоставляя разработчику полный контроль над структурой и качеством кода до того, как AI напишет первую строчку.

Prerequisites

• VSCode 1.109.0+
• GitHub Copilot
• Bun 1.3+ или Node.js 18+ (для запуска CLI)
• Расширение Context7 (Upstash.context7-mcp) — опционально

Quick Start

Один раз в саом начале нужно установить Agentica:

# Установка глобально
bun install -g @jakerdy/agentica

Затем, можно начинать пользоваться CLI для инициализации проекта:

# Обновляем до последней версии
bun update -g @jakerdy/agentica

# Создаём новый проект с помощью шаблона CLI для TypeScript
# в под-директории MyProject
agentica init typescript/cli MyProject

# Открываем в VSCode
cd MyProject && code .

После init Agentica автоматически:

• копирует в проект .agentica/prompts, .agentica/templates и .agentica/skills;
• создаёт директории спецификаций .agentica/research, .agentica/changes, .agentica/features, .agentica/release;
• обновляет .vscode/settings.json, добавляя пути в chat.promptFilesLocations и chat.agentSkillsLocations.
• добавит context7 в рекомендованные расширения, чтобы агенты сами могли искать документацию по библиотекам

Открой AI-чат (Ctrl + Shift + I) и запустите инициализационный промпт:

/agentica.init

Опишите тут свой проект
 - Стек технологий
 - Основную функциональность
 - Прочие важные детали

CLI

Чтобы было проще интегрировать Agentica в ваш проект, был создан небольшой, но удобный CLI.

Agentica CLI поддерживает два формата запуска init:

• Позиционный (основной): agentica init <stack> [targetPath]
• Через опции (совместимость): agentica init --stack <type> [--out <path>]

Основные команды

# Инициализация Agentica в текущей папке
agentica init typescript/cli

# Инициализация с созданием новой папки проекта
agentica init typescript/spa MyProject

# То же через опции (режим совместимости)
agentica init --stack typescript/spa --out MyProject

# Показать доступные шаблоны стеков
agentica stacks

# Справка по CLI
agentica --help
agentica init --help

Мотивация

Agentica был создан в ходе мучительного поиска "идеального" инструмента для работы с агентными системами.

На момент начала 2026 года существует множество инструментов, чтобы держать агента в рамках. Но большинство из них исходит из непростительно оптимистичного предположения, что агентная система:

1. Достаточно умна, чтобы писать качественный код.
2. Может самостоятельно построить адекватную архитектуру.
3. Позволяет пользователю быть "менеджером", который вообще не думает про структуру кода.

Однако практика показывает, что это ложь. Агентный кодинг обычно представляет собой одно из двух:

• Цикл бесконечной борьбы, в котором вы раз за разом затыкаете дыры в реализации, получая в итоге качество кода "ниже среднего".
• Адская бюрократия, требующая составления спецификации на пару тысяч строк Markdown с постоянной вычиткой и невозможностью вернуться назад без переписывания половины текста.

Но у агентов есть одно свойство, которое сложно игнорировать - они способны выдавать очень много кода за единицу времени. Чтобы это было полезно, им нужна правильная спека. Agentica - это конструктор таких спек. Она заполняет расстояние между вашими архитектурными решениями и финальным кодом.

Всадники апокалипсиса агентного кодинга

Фреймворк спроектирован для обхода четырех главных ограничений LLM:

1. Контекст модели ограничен. То, что помнит модель - это 1/10 или 1/20 часть проекта. Наша задача - сделать так, чтобы в контекст попало только то, что действительно важно для задачи, и ссылки на то, куда нужно "сходить".
2. Context Rot (Гниение контекста). Чем больше данных, тем глупее модель (на 5-15%). Поэтому чем уже скоуп спецификации и "общих файлов", тем лучше результат.
3. Context Compaction. При переполнении агент начинает сжимать информацию, выкидывая детали. Проблема в том, что он может выкинуть важное. Мы должны либо помещаться в одну сессию, либо заставлять модель перечитывать важное.
4. Говнокод. Модели обучались на GitHub. Беда в том, что в среднем люди пишут спагетти-код.
   • Молодой разработчик неопытен, пишет переусложненный код и радостно выкладывает его в OpenSource - это идеальный корм для обучения моделей.
   • Дядьки с опытом 15+ лет сидят в своих уютненьких банках, страховых и FAANG'ах. Им давно не нужно ничего контрибутить в OpenSource.
   • Итог: Есть явный bias модели в сторону кода сомнительного качества. Агент скорее напишет 100 строк 10-этажных вложенных конструкций, чем разделит это на плоские функции.

Философия подхода

0. Вся ответственность за принятые решения лежит на вас

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

В идеале, вся та работа по "продумыванию" проекта должна быть сделана человеком. И только после того, как человек удостоверился в том что:

• Все структуры данных и интерфейсы правильные
• Ответственность между элементами распределена верно
• Будут использоваться именно те библиотеки которые вы выбрали при планировании проекта
• Не добавится сущностей, которые уже были реализованы
• Изменение органично встроится в существующую систему Можно давать агенту возможность написать несколько тысяч строк кода. Другими словами, когда вы "всё понимаете" и "неопределённость ожиданий сведена к минимуму".

1. Тех-Задание + Продукт = Баланс

Все Spec-Driven фреймворки (которые я видел) исходят из того, что продукт первичен ("Vibe Coding"). Мы опираемся на "ощущения", а не на техническую красоту.

• Думать только о продукте = коллекционирование тех-долга с первого дня.
• Думать только о технике = постройка никому не нужного космолета.

Нужно приземлиться посередине. Агент через 100k токенов всё забудет, а код, который он написал, станет вашей проблемой. Поэтому ответственность должна начинаться до того, как агент начнет писать. Вы должны придумать архитектуру. Агенту останется только "заполнить тело методов".

В Agentica мы работаем сразу над "продуктовой" и "технической" частью. Например, в базовых структурах (кеши, фабрики) продукта нет - там чистая инженерия. А в новой панели GUI техничка простая, но важен UX.

2. Узкий Scope и Модульность

Вместо одного огромного контекста Agentica внедряет директорию .agentica/ в каждый пакет монорепозитория. Это позволяет:

• Держать в контексте LLM только правила конкретного модуля.
• Использовать 20 файлов по 40 строк вместо одного на 1000.

3. Anti-Spaghetti Метод

В файле AGENTS.md и промптах мы перечисляем всё то, что нам не нравится в коде агента, и дополняем это "хорошими практиками". Мы редактируем этот список до тех пор, пока код не станет "совсем хорошим".

4. Семантическая валидация

Review'ить код, написанный AI - то ещё удовольствие. Для этого нужен отдельный процесс: Семантическая Валидация.

Агент сам ходит по коду и сверяет его с продуктовыми и техническими требованиями, выступая в роли придирчивого сеньора.

И в конце выдаёт вам отчёт. И уже вы решаете, что с этим всё делать:

• Збить
• Попросить агента поправить критические проблемы
• Адаптировать требования к новой информации полученной из реализации, и начать сначала, но уже с более продуманной спекой

Главное помнить: сгенерированный код — ваша проблема, агент всё забудет, как только вы начнёте новый чат, и "обвинять" в плохих решениях будет уже некого...

Структура проекта

Agentica строго разделяет уровни ответственности.

Топология файлов

• Root проекта: Шаблоны, промпты, глобальный контекст.
• Package root: Фичи, изменения, архитектура пакета.

.
├── .agentica/                  # GLOBAL SCOPE (Конфигурация и общие знания)
│   ├── templates/              # Шаблоны (feature, arch, change, release)
│   ├── prompts/                # Промпты (init, create, implement, commit, release...)
│   ├── skills/                 # Skills для Copilot Agent (например frontend-design)
│   ├── product.md              # Глобальный продукт
│   ├── structure.md            # Структура репозитория
│   ├── tech.md                 # Глобальный стек и стандарты
│   └── status.md               # Статус интеграции в корне
├── packages/
│   ├── package1/
│   │   ├── .agentica/          # PACKAGE SCOPE (Спецификации и локальный контекст)
│   │   │   ├── research/       # RnD-XXXX (R&D исследования)
│   │   │   ├── changes/        # CH-XXXX (Изменения существующего)
│   │   │   ├── features/       # FT-XXXX (Новые фичи)
│   │   │   ├── release/        # REL-XXXX (Подготовка и выпуск релизов)
│   │   │   ├── product.md      # Контекст пакета
│   │   │   ├── structure.md    # Структура пакета
│   │   │   ├── tech.md         # Стек пакета
│   │   │   └── status.md       # Статус интеграции пакета
│   │   ├── src/
│   │   └── ...
└── ...

Важно: В Single-project структуре списки объединяются в одной корневой .agentica/.

Справочник команд

Все команды вызываются через /agentica.<command>. Аргументы опциональны - агент постарается вывести их из контекста, но явное указание надежнее.

| Команда | Аргументы | Назначение | | :---------- | :-------------- | :----------------------------------------------------- | | init | --lang, | Инициализация и настройка проекта | | rnd | --name | R&D исследование (RnD-XXXX) | | reverse | --name | Reverse Engineering по существующему коду (RnD-XXXX) | | create | --name | Спецификация новой фичи (FT-XXXX) | | change | --name | Спецификация изменений (CH-XXXX) | | tasks | --id | Декомпозиция спеки на задачи | | implement | --id | Написание кода по задачам | | validate | --id | Семантическая и техническая приемка | | commit | --skip-checks | Коммит с проверками безопасности | | release | --type | Подготовка релиза (REL-XXXX) и черновика changelog | | readme | --id | Генерация документации | | refactor | --- | Улучшение кода без смены API |

Рабочие процессы (Workflows)

Ниже описаны типовые циклы разработки (Loops).

Общие советы (Pain-killers)

• Новая фича - новый чат. Нам нужен максимально пустой и чистый контекст.
• Не спасайте спеку. Если что-то не получилось и вы хотите всё поменять в середине - удаляйте спеку, создавайте новый чат. Не пытайтесь "вылечить" текущую сессию. Вы потратите в 3 раза больше времени, а результат будет хуже. Выбрасывайте смелее.
• Учитесь писать на русском. Если вы не можете чётко сформулировать мысли текстом так, чтобы понял ваш товарищ, агент вас точно не поймёт. "Ну это же очевидно" для агента не работает. Спросите у LLM, как писать хорошие технические тексты - это прокачает ваш скилл промптинга.

1. Zero-to-Hero (Инициализация)

/agentica.init --lang TypeScript

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

Оснвной стек: TypeScript, Node.js, Commander.js для CLI

Что происходит: Агент создает структуру .agentica/, заполняет tech.md и structure.md под ваш запрос, готовит промпты.

2. Разработка новой фичи (Feature Loop)

Цикл: Spec → Tasks → Implement → Validate.

1. Создание спецификации:

   /agentica.create --name Пакетная загрузка
   Нужна загрузка CSV из папки, фильтр по маске и отчет об ошибках.
   Добавь ограничение файла до 100MB и retry при ошибках сети.

   Агент задаст уточняющие вопросы в процессе создания спеки для получения полной картины.

2. План работ:

   /agentica.tasks --id FT-0012

3. Кодинг:

   /agentica.implement --id FT-0012

4. Приемка:

   /agentica.validate --id FT-0012

3. Изменение существующего (Change Loop)

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

/agentica.change --name Формат ошибок
Нужно перевести ошибки с string на JSON объект {code, msg}.
Важно: сохранить exit-codes для CLI, чтобы не сломать CI.

Агент создаст CH-XXXX, проанализирует риски (Breaking Changes), предложит план миграции и только потом перейдет к коду.

4. R&D исследование

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

/agentica.rnd --name Система плагинов
Нужно спроектировать событийно-ориентированную систему плагинов.
Оцени целесообразность, подбери библиотеки, опиши интерфейсы ядра и шаблоны.

Агент создаст RnD-XXXX, зафиксирует исследование, оценку, архитектурные советы и принятые решения.

5. Реверс-инжиниринг (Legacy Analysis)

Когда документация умерла (или не рождалась), и нужно понять "как оно работает сейчас", чтобы не выстрелить себе в ногу.

/agentica.reverse --name Анализ текущего монорепо
Восстанови карту модулей, просканируй entry-points.
Найди циклические зависимости и узкие места в текущей реализации.

Агент просканирует кодовую базу и создаст описание системы “As-Is” в отдельном RnD-XXXX документе, подсветив зоны риска и архитектурный долг.

6. Документация

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

/agentica.readme --id FT-0012
Сделай короткую доку для разработчиков с примерами и описанием архитектуры нового решения.

7. Коммит "по богатому"

Используйте, когда нужно автоматически собрать staged-изменения, проверить их на мусор/секреты и создать качественное сообщение коммита.

Или просто используйте его всегда, когда собираетесь коммитить. Это просто, довольно быстро, а плюсы огромныe:

• Детальные сообщения которые муторно и лениво писать руками
• Гарантия, что в коммит не попадет мусор или секреты
• На основе истории можно будет делать качественные changelog'и и релизы, а не "misc updates" и "fixes"

/agentica.commit
Подготовь commit для текущих изменений.

Агент добавит изменения в stage, предупредит о потенциальных артефактах (.exe, .dll, .tgz и т.п.), предложит обновить .gitignore, сформирует сообщение в формате <change_type>: <Short Change Description> + детальное описание и выполнит git commit.

8. Подготовка релиза

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

/agentica.release --type minor
Собери релиз для текущего состояния main и подготовь команды публикации.

Агент проверит ветку (main/master), рассчитает новую версию (patch/minor/major), соберёт черновик changelog с последнего тега, пройдёт предрелизный checklist и создаст REL-XXXX документ.