Разработка с ИИ-агентами
С полного нуля до готового pet-проекта
Владимир Сидоров
10.08.2026, Зеленоград
ВВЕДЕНИЕ
Что такое AI-агент?
AI‑агент или агентная система — это автоматизированная система, соответствующая трем критериям:
Планированию действий — способности понять потребности человека и построить план действий;
Выполнению плана — способности самостоятельно совершить указанные действия, в том числе используя агентные инструменты для взаимодействия с внешней средой;
Автономности — наличию полномочий исполнять план без необходимости предварительного согласования шагов с человеком
OpenCode — это открытый AI-агент для программирования, который работает прямо в терминале, читает ваш проект, редактирует файлы и выполняет команды. По сути, это альтернатива таким инструментам, как Claude Code, но с открытым исходным кодом и независимостью от конкретного провайдера.
СХЕМА ПОТОКА
Концептуальная схема исполнеиия запроса
Вывод
Выполнение
Планирование
LLM Core
Восприятие
Агент итеративно проходит через цикл восприятия, рассуждения и действия — возвращаясь к LLM Core при необходимости доработки — до получения готового результата.
Центральная роль LLM Core
Интерпретирует запросы пользователя и контекст
Генерирует ответы, планы и вызовы инструментов
Управляет function calling / plugins
Обратная связь
Self-critique и verification позволяют агенту оценить результат и повторить цикл при необходимости итеративного улучшения.
КОМПОНЕНТЫ
Основные комоненты ИИ-агента
Perception Layer
Принимает текст, голос, изображения и данные от API/сенсоров. Извлекает контекст и метаданные из истории диалога для передачи в LLM Core.
Memory Module
Краткосрочная память хранит контекст текущей сессии. Долгосрочная реализуется через векторную БД (RAG). Эпизодическая фиксирует прошлые действия и их исходы.
Planning / Reasoning
Декомпозиция задачи на подзадачи. Применяет Chain-of-Thought, ReAct или Tree-of-Thought для выработки стратегии. Определяет порядок вызова инструментов.
Tools / Actions
Вызов внешних API, поиск в интернете, выполнение кода, работа с файлами и БД. Реализуется через function calling и plugins модели.
REACT
ReAct: синергия рассуждения и действия
Shunyu Yao et al., Princeton & Google, 2022. Статья: arxiv.org/abs/2210.03629
До ReAct рассуждение (chain-of-thought) и действие (вызов инструментов) использовались отдельно. ReAct объединяет их в одном цикле: reasoning traces помогают планировать и обновлять план, а actions позволяют получать актуальные данные из внешних источников.
Проблемы без ReAct
Только рассуждение (CoT) — галлюцинирует, опирается на устаревшие знания, не может проверить факты
Только действие — нет рассуждения, не может синтезировать ответ из наблюдений
ReAct решает это
Чередует Thought → Action → Observation в одном промпте
Reasoning traces заземляют модель в реальных данных
Человек может читать и корректировать ход мыслей агента
Результаты: +34% на ALFWorld, +10% на WebShop vs RL-методов
Меньше галлюцинаций на HotpotQA и Fever
АГЕНТЫ
Встроенные агенты Opencode
Primary agents — переключение: Tab
Build
агент по умолчанию, все инструменты включены. Для полноценной разработки
Plan
только анализ и планирование. file edits и bash = ask. Не вносит изменений
Subagents — вызов: @имя
@general
универсальный, полный доступ к инструментам. Параллельные задачи
@explore
read-only, быстрый поиск по кодовой базе. Не изменяет файлы
@scout
read-only, исследование внешних зависимостей и документации
Скрытые системные агенты: compaction (сжимает контекст), title (заголовки сессий), summary (саммари) — запускаются автоматически
Создать своего агента: opencode agent create — интерактивный мастер: описание → промпт → разрешения → markdown-файл
СКИЛЛЫ
Agent Skills: переиспользуемые инструкции для агентов
Где хранятся скиллы
Проект: .opencode/skills/<name>/SKILL.md
Глобально: ~/.config/opencode/skills/<name>/SKILL.md
Совместимо с .claude/skills/ и .agents/skills/
Структура SKILL.md
---
name: git-release
description: Create releases
compatibility: opencode
---
- Draft release notes
- Propose a version bump
Управление доступом
allow — загружается сразу
deny — скрыт от агента
ask — запрашивает подтверждение
Настраивается глобально и per-agent через opencode.json
РАСШИРЕНИЯ
LSP и MCP: расширение возможностей агента
LSP — Language Server Protocol
Opencode интегрируется с LSP-серверами для получения диагностики прямо в цикл агента. Отключён по умолчанию.
Встроенные серверы (компактный список):
TypeScript
Python (pyright)
Go (gopls)
Rust (rust-analyzer)
Java (jdtls)
C/C++ (clangd)
и 25+ других
Как включить (code):
// opencode.json
{ "lsp": true }
MCP — Model Context Protocol
MCP позволяет подключать внешние инструменты и источники данных к агенту через стандартный протокол.
Примеры MCP-серверов:
Базы данных (PostgreSQL, SQLite)
Внешние API и сервисы
Файловые системы
Браузер и веб-инструменты
Настройка в opencode.json:
{ "mcp": { "my-server": { "type": "stdio", "command": ["npx", "my-mcp-server"] } } }
ХАРНЕСС
Агентный харнесс: что это такое
Харнесс = операционная система для LLM
«Если ты не модель — ты харнесс» — Vivek Trivedy, LangChain
Аналогия с компьютером
Контекстное окно — RAM (быстрая, но ограниченная)
Внешние БД — Диск (большое, но медленное)
Инструменты — Драйверы устройств
Харнесс — Операционная система
Три уровня инжиниринга
01
Prompt Engineering
Формирует инструкции для модели
02
Context Engineering
Управляет тем, что модель видит и когда
03
Harness Engineering
Оркестрация, память, верификация, безопасность
ХАРНЕСС
ХАРНЕСС
02
Specification-Driven Development
Разработка с ИИ-агентами через спецификации
КОНЦЕПЦИИ
Как устроен OpenSpec: структура проекта
Change (Изменение)
Единица работы: папка с proposal, specs, design и tasks для каждой фичи.
Specs (Спецификации)
Согласованные требования в формате SHALL/WHEN/THEN.
Tasks (Задачи)
Чеклист реализации — AI выполняет по порядку и отмечает выполненные.
Archive (Архив)
Завершённые изменения хранятся как история решений.
КОМАНДЫ
Команды: от идеи до кода
Команда
Что делает
/opsx:explore
Анализирует код и формирует план — до написания чего-либо
/opsx:propose <название>
Создаёт папку изменения с proposal, specs, design и tasks
/opsx:apply
Реализует задачи из tasks.md по порядку, отмечая выполненные
/opsx:verify
Проверяет реализацию против спецификаций
/opsx:archive
Завершает изменение, перемещает в archive/, обновляет specs/
КОНЦЕПЦИИ
SDD pipe-line
После /opsx:propose
Создаётся папка changes/add-dark-mode/ с файлами proposal.md, specs/, design.md, tasks.md (все задачи unchecked)
После /opsx:apply
Задачи реализованы по порядку. tasks.md: все задачи ✓ checked
После /opsx:archive
specs/ мёрджатся в openspec/specs/. Папка перемещается в changes/archive/ с датой
ПРИМЕРЫ SDD
proposal.md — зачем и что
Первый артефакт изменения. Отвечает на вопрос: почему мы это делаем и что именно меняем.
# Proposal: Add Dark Mode
 
## Intent
Users have requested a dark mode option to reduce eye strain
during nighttime usage and match system preferences.
 
## Scope
In scope:
- Theme toggle in settings
- System preference detection
 
Out of scope:
- Custom color themes (future work)
Intent — проблема и мотивация, не решение
Scope — явно указать что НЕ входит в scope
Approach — высокоуровневый технический подход, детали в design.md
ПРИМЕРЫ SDD
specs/ui/spec.md — что меняется в поведении
# Delta for Auth
 
## ADDED Requirements
 
### Requirement: Two-Factor Authentication
- GIVEN a user without 2FA enabled
- WHEN the user enables 2FA in settings
- THEN a QR code is displayed and user must verify before activation
 
## MODIFIED Requirements
 
### Requirement: Session Expiration
The system MUST expire sessions after 15 minutes of inactivity. (Previously: 30 minutes)
Что меняется
При archive
ADDED
добавляется в основной spec
MODIFIED
заменяет существующее требование
REMOVED
удаляется из основного spec
ПРИМЕРЫ SDD
design.md и tasks.md — как и по шагам
design.md — технический подход
Technical Approach: Theme state via React Context. CSS custom properties enable runtime switching.
Architecture Decision: Context over Redux — simple binary state, no complex transitions.
File Changes: ThemeContext.tsx (new), ThemeToggle.tsx (new), globals.css (modified)
tasks.md — чеклист реализации
Theme Infrastructure
Create ThemeContext, add CSS custom properties, implement localStorage persistence
UI Components & Styling
Create ThemeToggle, add to settings page, define dark theme color palette
После /opsx:apply все задачи отмечаются как выполненные — AI работает по порядку
ПРИМЕР
От идеи до реализации: dark mode за 4 команды
/opsx:explore
→ Cleanest path: CSS variables + theme context. No new dependencies.
 
/opsx:propose add-dark-mode
→ Created openspec/changes/add-dark-mode/ (proposal.md, specs/, design.md, tasks.md)
 
/opsx:apply
→ ✓ 1.1 Theme context provider ✓ 1.2 Toggle component
→ ✓ 2.1 CSS variables ✓ 2.2 localStorage persistence
 
/opsx:archive
→ Archived. Specs updated. Ready for the next feature.
03
Практическое применение
От теории к рабочему pet-проекту
УСТАНОВКА
Установка Opencode
Ссылка на документацию: https://opencode.ai/docs
01
Через install script (рекомендуется)
curl -fsSL https://opencode.ai/install | bash
02
Через npm / bun / pnpm / yarn
npm install -g opencode-ai
03
Через Homebrew (macOS / Linux)
brew install anomalyco/tap/opencode
04
Windows (Chocolatey / Scoop)
choco install opencode
или: scoop install opencode
После установки — инициализировать проект:
cd /path/to/project
opencode
/init ← создаёт AGENTS.md, анализирует проект
Подключить LLM-провайдера (для тестов можно использовать routerai.ru, доступен в РФ, оплата картой):
/connect ← выбрать провайдера и вставить API-ключ
Или через OpenCode Zen: opencode.ai/auth
УСТАНОВКА
Установка OpenSpec
01
Установить CLI глобально
npm install -g @fission-ai/openspec@latest
02
Инициализировать в проекте
cd your-project
openspec init
Также: pnpm, yarn, bun, nix · openspec update — обновить инструкции агента
04
Дополнительные материалы
Рецепты OpenSpec: разбор сценариев
ПРИМЕРЫ
Рецепт 1: маленькая фича — быстрый путь
/opsx:propose add-logout-button
→ proposal.md specs/ design.md tasks.md
 
/opsx:apply
→ ✓ Add logout button to header
→ ✓ Clear session on click
→ ✓ Add confirmation dialog
 
/opsx:archive
→ ✓ Merged specs, moved to archive/
Рецепт 2: баг-фикс
/opsx:propose fix-login-redirect-loop
→ Captures broken vs intended behavior.
→ Delta spec MODIFIES redirect requirement.
GIVEN logged-out user, WHEN they submit valid credentials, THEN they land on dashboard and are not redirected again.
ПРИМЕРЫ
Рецепт 3: сначала исследуй, потом строй
You: /opsx:explore
AI: Found three likely culprits:
1. Large unoptimized images
2. Synchronous fetching blocking render
3. Re-renders from context changes
 
You: The data fetching one.
 
You: /opsx:propose optimize-product-list-fetching
AI: Created. Ready for implementation.
"Исследование проясняет мышление до того, как вы тратите изменение на него."
Не знаете с чего начать
Несколько возможных подходов
Хотите понять кодовую базу перед изменением
ПРИМЕРЫ
Рецепт 4: параллельные изменения · Рецепт 5: рефакторинг
Рецепт 4: два изменения одновременно
You: /opsx:propose fix-login-redirect
AI: Created. Ready for implementation.
 
You: /opsx:apply && /opsx:archive
AI: ✓ Archived fix-login-redirect.
 
You: /opsx:apply add-dark-mode
AI: Resuming add-dark-mode.
Picking up at task 2.3: Update Header...
Рецепт 5: рефакторинг без изменения поведения
You: /opsx:propose refactor-payment-module
AI: No spec changes.
$ openspec archive refactor-payment-module --skip-specs
Specs описывают поведение. Если поведение не изменилось — spec тоже не должен.
МАТЕРИАЛЫ
Полезные ссылки
Подкаст Podlodka #486
Описание: Подкаст про SDD — как применять спецификации в разработке с ИИ-агентами
Mitchell Hashimoto — My AI Adoption Journey
Описание: 5 февраля 2026. Создатель Vagrant и Terraform о 6 шагах принятия ИИ и термине Harness Engineering
Meta-Harness: End-to-End Optimization of Model Harnesses
Описание: Stanford & MIT, 30 марта 2026. Научная статья о формализации и автоматической оптимизации харнессов
Хабр: Что такое Harness?
Описание: Апрель 2026, 61K охват. Полный разбор на примере Claude Code, OpenAI и LangChain — 12 компонентов production-харнесса
ИТОГИ
Выводы и следующие шаги
Понять архитектуру
LLM + память + планирование + инструменты — четыре кита AI-агента
Освоить SDD
Писать спецификации до кода: цели, контекст, инструменты, формат вывода
Применить на практике
Итеративно строить pet-проект от POC до production
Ключевые тезисы
AI-агент — это сочетание LLM с памятью, планированием, инструментами и обратной связью
ReAct-цикл (Наблюдение → Мысль → Действие) — универсальный паттерн для большинства агентов
SDD (Spec-Driven Development) — писать спецификацию агента до кода сокращает итерации и делает систему предсказуемой
Вопросы?
Обсуждение и следующие темы