Appearance
Хендбук по Agentic Engineering
AI coding почти всегда начинается одинаково: кто-то отдаёт агенту небольшую задачу, получает рабочий diff и думает: «Так, это можно масштабировать». Через пару недель становится видно, что масштабируется не только скорость, но и хаос. PR растут, reviewer не понимает исходный intent, контекст живёт в чате, а фраза агента "готово" начинает подменять инженерную проверку.
Этот хендбук про более взрослый режим работы. Команда не просто просит AI написать код, а строит процесс, в котором agent берёт ограниченную задачу, работает в понятных границах, оставляет evidence и проходит проверки до того, как результат считают готовым.
Для кого
Хендбук рассчитан на людей, которые уже пробовали AI coding tools и хотят перейти от личных экспериментов к воспроизводимому командному workflow.
Он особенно полезен:
- middle/senior engineers, которые отвечают за качество изменений;
- tech leads, которым нужно разложить AI coding на понятный процесс;
- platform/devtools/infrastructure команды;
- engineering managers с техническим бэкграундом;
- продуктовые команды со сложным доменом, privacy, compliance или высокой ценой ошибки.
Если вы ищете набор «сильных промптов», это не тот материал. Здесь фокус на инженерной системе вокруг агента: задачи, контекст, проверки, права доступа, логи, ревью и rollout.
Как выглядит результат
После внедрения процесс выглядит не как «мы доверяем агенту», а как обычная engineering line:
| Было | Стало |
|---|---|
| "Попроси агента поправить onboarding" | Есть task contract: цель, scope, non-goals, acceptance criteria, testing plan. |
| Контекст держится в голове автора задачи | Контекст лежит в AGENTS.md, specs, task notes и context pack. |
| Reviewer смотрит большой diff и пытается понять intent | Reviewer видит spec, run summary, checks, risk summary и policy exceptions. |
| Агент сам сообщает, что всё готово | Harness классифицирует результат по checks: done, failed, blocked, needs_review. |
| Опасные действия ловятся вручную | Tool gateway и policy gate блокируют unsafe commands, write paths и external actions. |
| Успех зависит от конкретного человека и конкретного prompt | Процесс можно повторить, replay, улучшать и постепенно автоматизировать. |
Итоговый образ простой:
text
spec -> task contract -> context -> harness -> backend output -> checks -> logs -> reviewКак читать
Не обязательно читать всё подряд. Выберите маршрут под свою задачу.
Если вы один инженер: начните с Agentic Engineering, затем Task contract и Verification. После этого запустите практическую цепочку.
Если вы внедряете это в команду: прочитайте разработку от spec, архитектуру инструкций, tool gateway и policy, командный workflow и управляемую автономность.
Если вы строите platform/harness: идите через memory и knowledge base, минимальный harness, observability, оценку harness, очередь задач и self-hosting.
Перед чтением проверьте prerequisites: это не входной экзамен, а калибровка ожиданий.
Практическая линия
В репозитории есть labs, которые можно запустить руками:
text
examples/harness-labs/
examples/algi-lite/Сначала вручную пишется минимальный harness v01. Потом предыдущая версия harness строит следующую версию harness, а новая версия строит очередной кусок ALGI.
text
v01 hand-written runner
-> builds v02 with JSONL logs
-> v02 builds ALGI pain diary
-> v02 builds v03 with policy gates
-> v03 builds ALGI clinician reportЭто важная часть курса: ALGI не лежит готовым приложением. Он появляется как результат работы harness над specs, task contracts, policy и checks. Поэтому примеры не остаются словами: в каждой практической главе есть изменение в harness или в продукте.
Оглавление
| # | Раздел | Что вы сделаете |
|---|---|---|
| 0 | Практика: harness строит ALGI | Запустите chapter-by-chapter цепочку в локальном repo. |
| 1 | Agentic Engineering | Разберёте, почему agent без harness не является production workflow. |
| 2 | Разработка от spec | Зафиксируете behavior в spec до генерации кода. |
| 3 | Task contract | Превратите расплывчатую просьбу в ограниченную задачу с проверками. |
| 4 | Архитектура инструкций | Разложите instructions по слоям: chat, specs, AGENTS.md, policies, skills. |
| 5 | Context engineering | Соберёте context pack без лишнего шума. |
| 6 | Memory и knowledge base | Разделите trajectory, project memory и retrievable knowledge base. |
| 7 | Минимальный harness | Напишете первый runner и отделите harness от backend. |
| 8 | Tool gateway и policy | Опишете tools, policy gates и audit trail. |
| 9 | Безопасность агентов | Разберёте prompt injection, lethal trifecta и supply chain risks. |
| 10 | Проверка результата | Соберёте quality gate: tests, static checks, evaluator, retry/review/block rules. |
| 11 | Observability | Добавите events, logs, run summary и failure taxonomy. |
| 12 | Оценка harness | Проверите сам harness через eval set и replay. |
| 13 | Очередь задач | Разложите epic на dependencies, ready queue и безопасный parallelism. |
| 14 | Командный workflow | Встроите agent-generated changes в PR/review процесс. |
| 15 | Harness по доменам | Настроите разные loops для frontend, backend, mobile и DevOps. |
| 16 | Управляемая автономность | Определите уровни autonomy, approval gates и rollback. |
| 17 | Lifecycle агента | Заведёте registry, owner, eval coverage и incident response. |
| 18 | Self-hosting | Спроектируете путь, где harness улучшает ограниченные части самого себя. |
| C | Финальный проект | Соберёте end-to-end agentic engineering harness под продуктовую или platform-задачу. |
Шаблоны
| Шаблон | Когда открыть |
|---|---|
| Task contract | Когда задача ещё слишком расплывчатая. |
| BDD spec | Когда нужно описать behavior до кода. |
| Spec review checklist | Перед запуском agent/backend. |
| Context pack | Когда нужно собрать минимальный полезный context. |
| Project memory patch | Когда lesson из run/review должен стать stable memory. |
| Tool catalog | Перед подключением tools, MCP или external actions. |
| Policy | Когда нужно зафиксировать allowed commands, paths и approval-required actions. |
| Run summary | После запуска, чтобы reviewer видел evidence. |
| PR risk summary | Перед review agent-generated PR. |
| Eval suite | Когда меняете harness и хотите не сломать прошлые cases. |
| Agent registry entry | Перед использованием agent/backend в командном процессе. |
Сквозные кейсы
- ALGI / ALGORA - продуктовый кейс: приложение для пациентов с хронической болью и врачей.
- yolo-runner-like Harness - инженерный reference system: runner, task graph, checks, logs, observability, self-hosting.
Если хочется внедрить это в команду
Самостоятельное чтение даст язык и базовые artifacts. Для команды обычно нужна адаптация под конкретный repo, backlog, CI, review process, domain constraints и risk tolerance.
Если нужен B2B-формат для вашей engineering-команды, откройте Контакты.