Зачем это нужно
После первых трех уроков студент уже понимает, что LLM может ошибаться, coding agent работает через agent loop, а one-shot development плохо масштабируется. Но дальше появляется новая проблема: рынок инструментов выглядит как один большой список названий.
В одном разговоре могут встретиться Codex, Claude Code, Cursor, Kiro, Cline, Roo Code, Aider, Spec Kit, BMAD, Superpowers, LangGraph, AutoGen, CrewAI, MCP, OpenAPI и evals. Новичок пытается сравнить их напрямую и быстро попадает в ловушку:
Какой инструмент лучше: Claude Code или LangGraph?
Что выбрать: Cursor или Spec Kit?
Нужен ли CrewAI, если уже есть Codex?
Эти вопросы звучат естественно, но часто сравнивают разные слои системы. Это похоже на вопрос "что лучше: IDE, Git workflow или web framework". Ответ зависит от того, какую задачу вы решаете.
Главная цель урока - дать карту инструментов AI-разработки, чтобы студент понимал:
- какой слой инструмента перед ним;
- какую проблему этот слой решает;
- какие инструменты можно комбинировать;
- когда инструмент преждевременен;
- как не заменить инженерный процесс модным названием.
Основная идея
Инструмент AI-разработки нужно выбирать не по известности названия, а по месту в инженерной системе.
В этом курсе мы используем такую карту:
Product / engineering process
|
v
Specification and planning layer
|
v
Coding agent harness
|
v
Repository, tests, tools, CI
Optional advanced layer:
Agent runtime framework for custom agent systems
Если задача - изменить код в существующем репозитории, вам нужен coding agent harness.
Если задача - формализовать путь от идеи до задач, вам нужен SDD workflow.
Если задача - построить собственную agentic application, вам может понадобиться agent runtime framework.
Если задача - заставить агента соблюдать API contract, вам нужны specification artifacts и contract tooling.
Ключевые термины
| Термин | Значение |
|---|---|
| Coding Agent Harness | Инструмент, который запускает coding agent поверх repository, читает файлы, редактирует код, запускает команды и показывает diff. |
| SDD Framework | Методология или набор утилит, которые ведут feature через spec -> design/plan -> tasks -> implementation. |
| Agent Runtime Framework | Библиотека или framework для программирования собственной agent system: tools, state, handoffs, graph, multi-agent coordination. |
| API Specification Tool | Инструмент для OpenAPI, AsyncAPI, JSON Schema, contract testing и документации API. |
| Project Rules | Постоянные инструкции проекта для агента: coding conventions, boundaries, verification policy. |
| Skill | Повторяемая процедура, которую агент применяет по trigger conditions. |
| Tool | Исполняемая capability: команда, API call, MCP tool, script. |
| Guardrail | Ограничение или проверка, которая предотвращает опасное действие или неверный результат. |
Слой 1. Coding Agent Harness
Coding Agent Harness - это основной hands-on слой курса. Такой инструмент работает рядом с вашим кодом и помогает выполнять инженерные задачи:
- прочитать specification;
- исследовать repository;
- предложить plan;
- изменить файлы;
- запустить tests;
- показать diff;
- зафиксировать evidence;
- помочь с review.
Примеры из исходного плана курса:
| Инструмент | Сильная сторона в курсе |
|---|---|
| Codex | Delegated engineering, работа с repository, skills, параллельные задачи в подходящем окружении. |
| Claude Code | Terminal-first workflow, project instructions, skills, hooks, MCP, subagents. |
| Cursor | Интерактивная IDE-работа, быстрый feedback loop, project rules, agent mode. |
| Kiro | IDE/workflow вокруг specs: requirements, design, tasks, execution. |
| Cline | Plan/Act, permissions, checkpoints, MCP, worktrees, контролируемая автономность. |
| Roo Code | Роли и modes: Architect, Code, Debug, Ask, Orchestrator, Custom Modes. |
| Aider | Lightweight Git-first pair programming, repo map, lint/tests после изменений. |
Что решает этот слой
Coding agent harness отвечает на вопрос:
Как безопасно поручить агенту конкретное изменение в repository?
Хорошая задача для этого слоя:
Реализуй TASK AUTH-17.
Контекст:
- specs/auth/spec.md
- specs/auth/design.md
- specs/auth/tasks.md
Allowed scope:
- src/auth/*
- tests/auth/*
Verification:
- pytest tests/auth/test_reset_token.py
Плохая задача:
Сделай authentication как в хороших SaaS.
Проблема не в инструменте. Проблема в том, что агенту дали не задачу, а туман.
Слой 2. SDD Framework
SDD означает Specification-Driven Development. Этот слой нужен, чтобы до кода появились артефакты:
- requirements;
- specification;
- design;
- plan;
- tasks;
- acceptance criteria;
- verification commands.
Примеры из исходного плана:
| Инструмент или методология | Основная идея |
|---|---|
| GitHub Spec Kit | Agent-independent workflow specify -> plan -> tasks -> implement. |
| OpenSpec | Delta specs: описание изменений и архивирование реализованных спецификаций. |
| Kiro Specs | requirements.md -> design.md -> tasks.md -> execution внутри продукта. |
| BMAD Method | Full-lifecycle AI development methodology с ролями и guided workflows. |
| Superpowers | Skill-first development process: brainstorm, design, worktree, TDD, review. |
| Agent-OS | Ориентация на системные спецификации, роли и соответствие architecture constraints. |
Что решает этот слой
SDD framework отвечает на вопрос:
Как превратить идею в набор проверяемых задач для агента?
Этот слой особенно важен, когда:
- feature содержит несколько скрытых решений;
- есть архитектурные constraints;
- нужно сохранить traceability;
- над проектом работают несколько людей или агентов;
- важна воспроизводимость процесса.
Слой 3. Agent Runtime Framework
Agent Runtime Framework нужен не для того, чтобы "агент написал код", а для того, чтобы вы сами построили agentic system.
Примеры из исходного плана:
| Framework | Когда рассматривать |
|---|---|
| OpenAI Agents SDK | Нужно быстро собрать agent workflow вокруг agents, tools, handoffs, guardrails, sessions, tracing. |
| LangGraph | Нужен явный graph/state machine, persistent state, deterministic control flow, human-in-the-loop. |
| AutoGen | Центральна коммуникация нескольких agents, teams, messages, termination conditions. |
| CrewAI | Удобна role-oriented модель: agents, tasks, crews, flows. |
Что решает этот слой
Agent runtime framework отвечает на вопрос:
Как запрограммировать собственную agentic application?
Например:
- support triage agent;
- code review assistant как сервис;
- research agent с tools и memory;
- multi-agent workflow для обработки заявок;
- automated planner/verifier pipeline внутри продукта.
Для первых модулей курса этот слой обычно не нужен. Сначала студент должен научиться управлять одним coding agent через specs, tasks, tests и Git.
Дополнительный слой. API и contract tooling
Есть еще один слой, который часто путают с SDD: API specification tools.
Это инструменты вокруг машиночитаемых контрактов:
- OpenAPI;
- AsyncAPI;
- JSON Schema;
- TypeScript types;
- Swagger OSS tools;
- Specmatic;
- Stoplight / Elements;
- Redocly.
Они отвечают на другой вопрос:
Как доказать, что implementation соответствует API contract?
Для агента это особенно полезно, потому что contract становится внешней проверяемой рамкой. Агент не просто "думает", какой JSON вернуть, а должен пройти contract validation, tests и review.
Подробно этот слой разбирается в уроке 2.6.
Схема ландшафта
Главная мысль схемы: SDD framework, coding agent harness и runtime framework не заменяют друг друга. Они могут находиться в одной системе, но выполняют разные роли.
Пример 1. Студент делает password reset
Задача:
Добавить password reset в существующий web app.
Нужный слой:
| Что нужно | Подходящий слой |
|---|---|
| Описать поведение reset token | Specification |
| Разложить feature на tasks | SDD workflow |
| Попросить агента изменить backend | Coding agent harness |
| Проверить API response shape | OpenAPI / contract tests |
| Запустить unit/integration tests | Test toolchain / CI |
| Построить собственного support agent | Не нужно для этой задачи |
Новичку не нужен LangGraph только потому, что в проекте используется AI. Ему нужен нормальный spec, маленькие tasks, tests и controlled agent run.
Пример 2. Команда строит внутреннего reviewer agent
Задача:
Создать сервис, который принимает Pull Request,
сравнивает diff со spec, запускает проверки
и возвращает structured review.
Нужный слой:
| Что нужно | Подходящий слой |
|---|---|
| Определить review protocol | Specification / SDD |
| Дать сервису tools для GitHub/CI | Tools / MCP / API integration |
| Хранить state review run | Agent runtime framework |
| Разделить planner/reviewer/verifier roles | Runtime orchestration |
| Проверять качество reviewer | Evals |
Здесь runtime framework уже может быть оправдан. Мы строим не просто feature в repository, а agentic application.
Beginner Stack
Для первых проектов курс рекомендует простой стек:
Git
+
обычный language/toolchain
+
Codex / Claude Code / Cursor / Kiro
+
простая SDD структура или Spec Kit
+
Unit / Integration Tests
+
CI
Этого достаточно, чтобы научиться главному:
- агент работает маленькими задачами;
- требования записаны;
- контекст ограничен;
- verification автоматизирована;
- diff можно проверить;
- изменения можно откатить.
Сложные frameworks добавляются только тогда, когда появились реальные причины.
Порядок усложнения
Не нужно начинать с multi-agent orchestration. Лучше двигаться по лестнице зрелости:
Single agent
|
v
Skills
|
v
MCP / external tools
|
v
Subagents
|
v
Parallel agents in worktrees
|
v
Custom agent runtime
Почему такой порядок важен
Если single-agent workflow неуправляем, multi-agent workflow станет только быстрее производить хаос.
Если нет тестов, параллельные агенты не дадут надежности.
Если нет specification, runtime framework не знает, что считать правильным поведением.
Если нет Git дисциплины, worktrees и checkpoints не спасут от смешанных изменений.
Как выбирать инструмент под задачу
Задайте пять вопросов.
1. Что является главным результатом?
| Результат | Скорее всего нужен |
|---|---|
| Изменение кода в repository | Coding agent harness |
| Набор specs/tasks | SDD framework |
| Машиночитаемый API contract | API specification tool |
| Собственный agentic сервис | Agent runtime framework |
| Повторяемая процедура для агента | Skill |
| Детерминированная проверка | Script / CI / hook |
2. Насколько задача повторяемая?
Если действие выполняется один раз, достаточно task prompt и spec.
Если действие повторяется часто, оформляйте skill.
Если действие должно выполняться детерминированно, делайте script или tool.
Если действие связано с внешним сервисом и permissions, рассматривайте MCP.
3. Где находится source of truth?
| Source of truth | Что использовать |
|---|---|
| Product behavior | spec.md, PRD, acceptance criteria |
| Architecture decision | ADR |
| API shape | OpenAPI / JSON Schema / TypeScript types |
| Development procedure | Skill |
| Stable project rule | Project instructions |
| Verification | Tests / CI / evals |
4. Какой риск у действия?
Read-only analysis можно делегировать свободнее.
Изменение кода требует scope и tests.
Изменение data, billing, permissions, secrets, production deployment требует human gate.
5. Что будет evidence?
Инструмент выбран плохо, если после его работы у вас есть только фраза:
Done, everything works.
Нужно evidence:
- какие файлы изменены;
- какие acceptance criteria закрыты;
- какие команды запущены;
- какие тесты прошли;
- какие риски остались;
- что должен проверить человек.
Open-source инструменты: как смотреть на них в курсе
Open-source важен в AI Agent Development по трем причинам:
- Его можно изучать как reference implementation.
- Его проще встроить в локальный repository workflow.
- Его можно адаптировать под свои rules, scripts, hooks и CI.
Но "open-source" не означает "подходит автоматически". Для курса полезнее такая проверка:
| Вопрос | Почему важен |
|---|---|
| Можно ли запускать локально? | Для учебного и корпоративного окружения это часто критично. |
| Есть ли CLI? | CLI проще встроить в scripts и agent workflow. |
| Есть ли стабильный format artifacts? | Markdown, YAML, OpenAPI, JSON Schema проще ревьюить и версионировать. |
| Можно ли использовать без облачного lock-in? | Это влияет на переносимость курса и проектов. |
| Понятна ли лицензия? | Лицензия должна соответствовать правилам проекта. |
| Есть ли активная экосистема? | Мертвый инструмент быстро превращается в технический долг. |
В рамках курса важнее понять архитектурную роль инструмента, чем запомнить текущий список брендов.
Типичные ошибки
Ошибка 1. Сравнивать разные слои
Плохой вопрос:
Что лучше: Cursor или LangGraph?
Лучший вопрос:
Мне нужен инструмент для редактирования repository
или framework для построения собственного agent workflow?
Ошибка 2. Начинать с runtime framework
Команда еще не умеет писать specs, но уже строит multi-agent graph.
Результат:
- больше moving parts;
- сложнее debug;
- нет проверяемых требований;
- непонятно, кто принял неправильное решение.
Ошибка 3. Пытаться заменить tests агентом
Даже сильный coding agent не является verification system. Он может помочь написать tests, но evidence должна давать внешняя проверка.
Ошибка 4. Держать все знания в prompt
Prompt становится огромным, устаревает и противоречит сам себе.
Лучше разделить:
- stable rules в project instructions;
- repeated procedures в skills;
- exact requirements в specs;
- deterministic checks в scripts;
- external context в MCP resources;
- acceptance в tests и evals.
Ошибка 5. Выбирать инструмент по демо
Демо почти всегда показывает счастливый путь. В реальном проекте важнее:
- rollback;
- permission model;
- auditability;
- CI integration;
- работа с большим repository;
- качество diff;
- способность не выходить за allowed scope.
Практика
Возьмите три задачи и классифицируйте, какой слой нужен.
Задача A
Добавить endpoint POST /api/projects,
валидацию request body,
unit tests и OpenAPI update.
Ожидаемый ответ:
- coding agent harness для изменения repository;
- feature spec или task из SDD workflow;
- API contract tool для OpenAPI validation;
- tests и CI как verification.
Runtime framework не нужен.
Задача B
Сформировать требования, design и tasks для notifications subsystem.
Ожидаемый ответ:
- SDD framework или локальная SDD структура;
- coding agent может помочь писать документы;
- tests появятся позже;
- runtime framework не нужен.
Задача C
Построить сервис, который сам принимает user request,
выбирает tools, вызывает другие agents,
сохраняет state и показывает trace.
Ожидаемый ответ:
- agent runtime framework;
- tools/MCP;
- guardrails;
- observability/tracing;
- evals.
Coding agent harness может помочь разработать этот сервис, но не заменяет runtime.
Критерии готовности
После урока студент должен уметь:
- отличить coding agent harness от SDD framework;
- объяснить, зачем нужен agent runtime framework;
- назвать место OpenAPI/contract tooling в agent development;
- собрать простой beginner stack;
- объяснить, почему не стоит начинать с multi-agent runtime без specs/tests/Git;
- выбрать минимально достаточный инструмент под задачу.
Краткое резюме
Инструменты AI-разработки находятся на разных слоях. Coding agent harness помогает менять repository. SDD framework помогает превратить идею в specs, plans и tasks. Agent runtime framework нужен, когда вы программируете собственную agentic system. API specification tools дают контрактные рельсы для агента.
Для курса важен не культ конкретного продукта, а инженерная карта: где source of truth, где execution, где verification, где human gate.
Вопросы для самопроверки
- Почему Claude Code и LangGraph нельзя сравнивать напрямую?
- В каком случае достаточно coding agent harness, а runtime framework будет лишним?
- Какой слой отвечает за
spec -> plan -> tasks -> implement? - Почему API contract tools важны для agent development?
- Какие элементы входят в beginner stack для первых проектов?
Что дальше
Дальше курс переходит к Specification-Driven Development. Теперь, когда карта инструментов понятна, можно подробно разобрать главный источник управляемости: хорошую specification.