¶ Титульные листы
¶ Цель работы
Получить практические навыки проектирования агентского харнесса (обвязки вокруг LLM-агента, включающей правила, навыки, управление контекстом, контроль качества) на базе GigaIDE. Затем применить его для разработки веб-приложения (аналога Wiki.js).
¶ Задание
Качество результата ИИ-агента в разработке определяется не только моделью, но и окружением, в котором она работает. Это окружение и называют харнессом. Его обычно составляют:
- постоянные инструкции (Rules);
- переиспользуемые процедуры (Skills);
- внешние инструменты (MCP) при необходимости;
- политика хранения контекста между сессиями;
- проверки, которые не дают агенту "сломать и не заметить".
GigaIDE — отечественная среда разработки со встроенным ассистентом GigaCode. Плагин GigaCode работает в GigaIDE. В нём есть режимы Agent, Ask и Plan, просмотр изменений агента, Skills, Rules, MCP и настройки контекста.
Вам нужно построить харнесс в репозитории проекта. Затем с его помощью разработать MiniWiki — упрощённый аналог Wiki.js, платформы, на которой работает Вики кафедры ПМиФИ ОмГТУ. Wiki.js — это вики на Node.js с Markdown-редактором, поиском и другими полезными функциями. Результаты оформите отчётом по требованиям нормоконтроля кафедры.
Структура этапов выполнения ДЗ соответствует структуре разделов и подразделов отчёта.
¶ Минимальные требования к MiniWiki
Приложение должно запускаться одной командой через Docker (docker compose up --build). Пользователь с ролью admin создаётся при старте, если его нет. Данные берутся из переменных окружения. Обязательный функционал (MVP):
- Страницы с иерархическими путями (
/docs/nlp), создание, редактирование, удаление. - Markdown-редактор с предпросмотром.
- Аутентификация и три роли:
admin,editor,reader. Пользователь с рольюreaderможет читать только страницы с тегомpublic. - Поиск, теги и дерево страниц (навигация).
- Экспорт (скачивание) всех страниц в структуру каталогов с
.md-файлами (может запускать только пользователь с рольюadmin). - Задокументированный REST API.
¶ 1 этап: проектирование обвязки и формирование стека
1.1. Зафиксируйте технологический стек (здесь рекомендация, можете действовать по своему).
| Компонент | Рекомендация | Допустимые замены |
|---|---|---|
| Backend | Python 3.11+, FastAPI | Django, Express/NestJS |
| БД | SQLite | PostgreSQL |
| Frontend | Jinja2 + HTMX | React/Vue |
| Markdown | markdown-it-py или markdown + очистка nh3 | marked + DOMPurify |
| Тесты | pytest + httpx | Jest/Vitest |
1.2. Визуализируйте архитектурную схему харнесса: Rules - Skills - контекстная память - проверки (тесты, линтер). Опишите, какую проблему решает каждый слой.
1.3. Установите GigaIDE (Desktop; дистрибутив на странице загрузки).
1.4. Подготовьте окружение для разработки. Инициализируйте пустой проект.
Результат данного раздела: зафиксированный стек, схема харнесса.
¶ 2 этап: разработка правил и системы сохранения контекста
2.1. Создайте Project Rules. Правила описываются в .md-файлах, после сохранения сразу активны, проектные правила хранятся в репозитории. Документация рекомендует формулировать однозначно, регулярно чистить устаревшее и писать несколько коротких правил вместо одного большого.
Минимальный набор правил (по файлу на тему):
stack.md: стек, структура каталогов, запрет на добавление зависимостей без обоснования вDECISIONS.md;security.md: пароли только через argon2/bcrypt, весь пользовательский HTML очищается, SQL только параметризованный, секреты только из переменных окружения;workflow.md: сначала Plan, потом реализация; после каждой задачи запускатьpytest; не коммитить при проваленных тестах; не трогать файлы вне задачи;definition-of-done.md: критерии готовности задачи.
2.2. Спроектируйте политику сохранения контекста. Агент не помнит прошлые сессии, поэтому память должна лежать в файлах репозитория. Создайте каталог docs/ai/:
| Файл | Назначение | Когда обновляется |
|---|---|---|
PROJECT.md |
Краткое описание продукта и архитектуры (не более 100 строк) | При смене архитектуры |
PROGRESS.md |
Что сделано, что в работе, что дальше | В конце каждой сессии |
DECISIONS.md |
Решение, альтернативы, причина | При каждом значимом решении |
GOTCHAS.md |
Грабли и их решения | При обнаружении ошибки агента |
В правилах укажите: "в начале сессии прочитать docs/ai/PROGRESS.md и docs/ai/PROJECT.md; в конце обновить PROGRESS.md".
Результат данного раздела: набор Project Rules, каталог
docs/ai/, политика контекста.
¶ 3 этап: создание навыков
Skill — директория с обязательным SKILL.md и опциональными scripts/, references/, assets/. Файл начинается с YAML-frontmatter (спецификация). Требования к полям:
name: до 64 символов, строчные латинские буквы, цифры и дефисы, без дефиса в начале и конце;description: до 1024 символов, не пустое, описывает что делает навык и когда его применять;- имя должно совпадать с именем родительской директории;
- тело
SKILL.mdжелательно держать до 500 строк, а детали выносить в отдельные файлы.
Агент в начале сессии видит только имя и описание навыка, а полный текст загружает при совпадении задачи. Поэтому качество поля
descriptionкритично.
3.1. Разместите навыки в .gigacode/skills/<имя>/SKILL.md внутри проекта.
3.2. Обязательный минимум: 3 навыка, из них не менее двух со скриптами или references/. Например:
| Навык | Назначение | Пример скрипта или ресурса |
|---|---|---|
add-wiki-endpoint |
Новый API-метод по шаблону | references/api-conventions.md |
security-review |
Проверка XSS, прав | scripts/grep_dangerous.py |
session-handoff |
Обновление PROGRESS.md и DECISIONS.md в конце сессии |
assets/progress-template.md |
Можете интегрировать дополнительные навыки
Результат данного раздела: 3 и более работающих навыка
¶ 4 этап: разработка с применением обвязки
Порядок разработки по "спринтам". Каждый спринт: Plan - согласование - Agent - тесты - сохранение информации.
| Спринт | Содержание | Критерий готовности |
|---|---|---|
| 0 | Каркас проекта, README, запуск, /health |
Запуск одной командой |
| 1 | Модель страниц, CRUD, пути, Markdown-рендер | Тест XSS (ограничение инъекции <script>alert(1)</script>) проходит |
| 2 | Поиск, теги, навигация | Поиск находит по заголовку и тексту |
| 3 | Аутентификация, роли, ограничения | Тест прав на 3 роли |
| 4 | Экспорт в .md |
Структура файлов повторяет пути страниц |
Пополняйте
GOTCHAS.mdкаждой найденной ошибкой агента и превращайте повторяющиеся ошибки в правило.
В отчёте должны быть скриншоты, на которых видно, что навыки действительно вызываются
Правило ответственности: вы отвечаете за каждую строку кода и каждое правило, независимо от того, кто их написал. Преподаватель вправе попросить объяснить любой фрагмент.
Результат данного раздела: работающая MiniWiki с MVP-функционалом
¶ Критерии приёмки домашнего задания
- Репозиторий содержит каталоги
.gigacode/skills/, правила проекта (Rules) иdocs/ai/ - Продемонстрированы не менее 3 навыков
- Реализована политика сохранения контекста; новая сессия продолжает работу по
PROGRESS.md - MiniWiki запускается одной командой и выполняет все пункты MVP
- Представлен отчёт в соответствии с требуемой структурой
- Отчёт и список источников в нём выполнены в соответствии с требованиями нормоконтроля
- Отчёт подписан и загружен в электронный кабинет
¶ Структура отчёта
Отчет обязательно должен содержать:
- введение: краткое описание темы работы, цели работы и поставленных задач;
- основную часть, совпадающую с этапами выполнения домашнего задания (4 подраздела: стек и архитектура харнесса, правила и контекст, навыки, разработка MiniWiki);
- заключение: выводы, возникшие трудности и способы их решения (обязательно с ошибками агента и обходами), полученные знания, улучшения харнесса;
- список использованных источников (источник добавляется только в том случае, если в тексте работы есть ссылка на него).
Отчёт оформляется в соответствии с требованиями
Для списка источников отдельные требования к оформлению
¶ Важные замечания
Домашнее задание считается выполненным, если оно подписано, загружено через электронный кабинет ОмГТУ и принято преподавателем
Преподаватель оставляет за собой право отклонить работу без объяснения причин, если оформление отчёта и списка источников не соответствует требованиям нормоконтроля