feat(site): добавлен раздел «Разработка с ИИ» с двумя статьями-переводами

- Зачем:
  - расширить роадмап практическим разделом о работе с ИИ-ассистентами.
- Что:
  - добавлена вводная страница ai-dev/README.md.
  - добавлен перевод «Лучшие практики работы с coding agents» (ai-dev/best-practice.md).
  - добавлен перевод «Механизм памяти coding agents» (ai-dev/memory-mechanism.md).
  - добавлен раздел «Разработка с ИИ» в навигацию mkdocs.yml.
- Проверка:
  - mkdocs build --strict проходит без ошибок.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

ai-dev/best-practice.md

@@ -0,0 +1,234 @@
+# Лучшие практики работы с coding agents
+
+> По мотивам [Best Practice](https://docs.z.ai/devpack/resources/best-practice) (Z.AI DevPack)
+
+По мере развития фундаментальных моделей ИИ-инструменты для разработки эволюционируют от простых ассистентов автодополнения кода в **coding agents**, способных участвовать в полном цикле разработки ПО. В отличие от традиционных copilot-инструментов, coding agents умеют читать и навигировать по кодовой базе, модифицировать файлы, выполнять команды, вызывать внешние инструменты и решать сложные задачи через многошаговое взаимодействие.
+
+С этим сдвигом разработчикам нужно больше, чем техники написания промптов. Нужен надёжный подход к работе с coding agents на практике. Среди ведущих инструментов формируется общий паттерн использования: предоставить чёткий контекст задачи, спланировать шаги выполнения, зафиксировать проектные правила, подключить внешние инструменты и системы, автоматизировать повторяющиеся процессы.
+
+Опираясь на официальные рекомендации этих инструментов, статья описывает **общий фреймворк лучших практик для coding agents**.
+
+## 1. Относитесь к агенту как к коллеге, а не к одноразовому инструменту
+
+Типичная ошибка при работе с coding agent — использовать его как одноразовый вопрос-ответ:
+
+> Задать вопрос, получить код, завершить взаимодействие.
+
+На практике этот подход не раскрывает возможности агента.
+
+Coding agent лучше воспринимать как настраиваемого коллегу, которого можно совершенствовать со временем. Через конфигурационные файлы проекта, интеграции с инструментами и переиспользуемые навыки (skills) разработчик может постоянно формировать поведение агента так, чтобы оно соответствовало рабочему процессу команды.
+
+!!! tip "Ключевая мысль"
+    Ценность coding agent определяется не только возможностями модели. Она складывается из возможностей модели **и** рабочего процесса вокруг неё.
+
+## 2. Структурируйте входные данные задачи: контекст важнее промпт-инженерии
+
+При работе с coding agent многие разработчики слишком фокусируются на технике написания промптов и недостаточно на том, что важнее: **контексте задачи**.
+
+В сложной кодовой базе эффективное описание задачи обычно включает четыре элемента:
+
+- **Цель.** Чётко опишите, что нужно сделать: исправить баг, реализовать эндпоинт, отрефакторить модуль
+- **Контекст.** Укажите релевантные файлы, сообщения об ошибках, документацию или примеры. Назовите конкретные файлы, функции или модули
+- **Ограничения.** Перечислите инженерные требования: стандарты кодирования, архитектурные правила, требования безопасности, ограничения зависимостей
+- **Критерии завершения.** Определите, как оценивать готовность: тесты проходят, поведение изменилось ожидаемым образом, баг больше не воспроизводится
+
+Такой структурированный ввод снижает лишние догадки и делает изменения агента более последовательными и легко проверяемыми.
+
+В большинстве coding agents контекст можно предоставить, указав на файлы, приложив фрагменты кода или явно описав детали в промпте. Когда контекст задан, следующий шаг для сложной работы: планирование перед внесением изменений.
+
+## 3. Планируйте перед выполнением сложных задач
+
+Когда задача имеет чёткий контекст, следующая проблема: выполнение. Для сложных запросов coding agents наиболее эффективны, когда они **планируют перед действием**.
+
+Если попросить агента сразу писать код при сложном запросе, это часто приводит к логическим ошибкам, ненужной переработке или повторным правкам. Более эффективный подход: **сначала план, потом реализация**.
+
+Фаза планирования обычно включает:
+
+- Анализ кодовой базы
+- Определение объёма изменений
+- Подтверждение подхода к реализации до начала правок
+
+Например, Claude Code поощряет шаг анализа и планирования для сложных задач. Некоторые coding agents также предоставляют выделенный режим планирования, который генерирует полный план выполнения перед реализацией.
+
+Это сдвигает агента от простой генерации кода по запросу к выполнению работы пошагово по явному плану.
+
+## 4. Фиксируйте повторяющиеся правила в конфигурационных файлах проекта
+
+На практике многие промпты повторяют одни и те же проектные правила:
+
+- структура директорий проекта
+- команды сборки
+- процесс тестирования
+- стандарты кодирования
+- процесс подачи PR
+
+Если эти правила повторяются в каждом промпте, рабочий процесс становится неэффективным, а инструкции со временем начинают расходиться.
+
+Поэтому большинство coding agents позволяют хранить **долгоживущие проектные правила** в конфигурационных файлах проекта, чтобы агент автоматически загружал нужный контекст при выполнении задач.
+
+В одних инструментах это файлы-инструкции для агента, описывающие структуру репозитория, способ запуска проекта и принятые конвенции. В других та же информация фиксируется через конфигурационные файлы, скрипты или настройки проекта.
+
+Независимо от реализации, цель одна: перенести информацию, которую иначе пришлось бы повторять в диалоге, в **стабильный проектный контекст**.
+
+!!! success "Практическое правило"
+    **Временные инструкции пишите в промпте, а долгоживущие правила фиксируйте в конфигурационных файлах проекта.**
+
+## 5. Среда выполнения определяет возможности агента
+
+Работая с coding agents, разработчики часто объясняют непоследовательные результаты возможностями модели. На практике многие из этих проблем вызваны неполной или неправильно настроенной **средой выполнения**.
+
+В отличие от традиционных инструментов автодополнения, coding agents обычно работают в реальной среде разработки и выполняют задачи:
+
+- чтение и модификация исходных файлов
+- запуск команд сборки или тестирования
+- вызов внешних инструментов или API
+- взаимодействие с системами контроля версий
+
+Поведение агента зависит не только от возможностей модели, но и от того, **насколько среда выполнения полна, стабильна и доступна**. При неправильной конфигурации агент может столкнуться с проблемами:
+
+!!! warning "Типичные проблемы среды"
+    - Невозможность найти нужную директорию проекта
+    - Отсутствие прав на чтение или модификацию критичных файлов
+    - Невозможность запустить команды сборки или тестирования
+    - Отсутствие доступа к внешним инструментам или сервисам
+
+Эти проблемы часто выглядят как непонимание со стороны модели или низкое качество кода, но реальная причина обычно в том, что у агента недостаточно прав выполнения или доступа к нужному контексту.
+
+Большинство ведущих coding agents предоставляют настройки среды:
+
+- выбор модели или уровня рассуждений
+- управление правами доступа к файлам и политиками песочницы
+- определение разрешённых команд
+- настройка подключений к внешним инструментам или сервисам
+
+!!! success "Три типа контекста"
+    Coding agent зависит от трёх типов контекста:
+
+    - **Контекст задачи**: промпт и входные данные текущей задачи
+    - **Контекст проекта**: структура репозитория и инженерные правила
+    - **Контекст среды**: инструменты, права доступа и среда выполнения
+
+    Из них контекст среды определяет **что агент может делать и как далеко зайти**.
+
+## 6. Вовлекайте агента в полный цикл разработки
+
+Когда у coding agent есть правильная среда выполнения, следующий шаг: вовлечь его в полный цикл разработки, а не использовать только для генерации кода. В реальной разработке изменение кода оценивается не только по генерации. Оно должно пройти тесты, соответствовать инженерным стандартам и пройти ревью.
+
+Типичный цикл разработки с агентом включает шаги:
+
+1. **Реализация изменений.** Модификация существующего кода или добавление нового по требованиям задачи
+2. **Написание или обновление тестов.** Добавление тестового покрытия для новой функциональности или исправляемого бага
+3. **Запуск тестов.** Выполнение модульных или интеграционных тестов для проверки ожидаемого поведения
+4. **Проверка кода.** Запуск линтеров, форматирования или проверки типов для соответствия стандартам
+5. **Ревью изменений.** Инспекция диффа для выявления потенциальных проблем, рисков регрессии или нежелательных модификаций
+
+В этом рабочем процессе coding agent перестаёт быть просто генератором кода. Он становится активным участником **реализации, валидации и ревью**.
+
+!!! success "Смена роли"
+    С точки зрения рабочего процесса, coding agent трансформируется из традиционного **генератора кода** в **узел выполнения внутри цикла разработки**.
+
+## 7. Расширяйте контекст агента через MCP
+
+В реальных рабочих процессах информация, необходимая coding agent, не всегда находится в репозитории. Многие данные, влияющие на решения при реализации, распределены по внешним системам:
+
+- системы трекинга задач и требований
+- статус и результаты CI/CD
+- схемы баз данных или продуктовые данные
+- документация API и ссылки на внешние сервисы
+
+Если эту информацию приходится копировать и вставлять вручную каждый раз, процесс становится неэффективным, а контекст, передаваемый агенту, фрагментирован и ненадёжен.
+
+Поэтому многие coding agents поддерживают **Model Context Protocol (MCP)**, который предоставляет стандартный способ подключения внешних инструментов и систем. Через MCP coding agent может получать доступ к:
+
+- платформам хостинга и совместной работы с кодом
+- базам данных и интерфейсам запросов
+- API-сервисам и технической документации
+- внутренним инструментам и системам автоматизации
+
+!!! success "Расширение границ"
+    Когда агент может работать только с информацией из промпта, он обычно ограничен локальными задачами. Подключение к внешним системам позволяет ему участвовать в более полных рабочих процессах: читать контекст задач, исследовать упавшие CI-запуски, проверять определения API, анализировать проблемы по схемам баз данных.
+
+    Агент эволюционирует из **исполнителя уровня репозитория** в **узел взаимодействия внутри реальной инженерной среды**.
+
+## 8. Оформляйте повторяющиеся процессы как Skills
+
+Со временем команды обнаруживают, что определённые задачи возникают снова и снова:
+
+- ревью PR
+- анализ логов
+- генерация release notes
+- стандартные отладочные процессы
+
+Если описывать эти задачи вручную в промпте каждый раз, результат: ненужное повторение и менее стабильные результаты.
+
+Поэтому многие системы coding agents предоставляют механизм **Skills**: упаковку типовых процессов в переиспользуемые шаблоны.
+
+На высоком уровне Skill можно понимать как **структурированный шаблон рабочего процесса**. Он абстрагирует логику выполнения, которая иначе была бы разбросана по промптам, и позволяет агенту применять один и тот же процесс последовательно при обработке похожих задач.
+
+Разные инструменты реализуют Skills по-разному: через выделенные файлы, конфигурацию или скрипты. Но цель одна: **превратить разовые промпты в переиспользуемые рабочие процессы**.
+
+На практике работает простое правило:
+
+> **Если паттерн промпта или поток задач используется повторно, он, вероятно, должен быть оформлен как Skill.**
+
+## 9. Автоматизируйте стабильные процессы
+
+Когда Skill можно выполнить надёжно, следующий шаг: автоматизация.
+
+В долгоживущих рабочих процессах разработки многие задачи повторяются или привязаны ко времени:
+
+- генерация резюме коммитов по расписанию
+- автоматическое расследование упавших CI-запусков
+- сканирование на потенциальные баги или аномальные логи
+- подготовка ежедневных или еженедельных инженерных отчётов
+
+Даже если эти задачи уже оформлены как Skills, они по-прежнему создают ручную работу, если разработчикам приходится запускать их каждый раз.
+
+!!! info "Автоматизация как следующий слой"
+    Автоматизация находится уровнем выше Skills. Skill определяет **как** выполняется рабочий процесс, а автоматизация определяет **когда** он запускается и **как** продолжает работать со временем.
+
+Например, навык генерации release notes можно настроить на запуск:
+
+- при каждой новой публикации релиза
+- раз в неделю для подготовки сводки релизов
+- автоматически после завершения CI
+
+Это сдвигает coding agent из **интерактивного инструмента** в **непрерывного ассистента разработки**.
+
+## 10. Управляйте сессиями осознанно
+
+При работе с coding agents сессия — это больше, чем история чата. На практике она функционирует как **рабочий контекст**, который накапливает контекст, промежуточные рассуждения и результаты выполнения.
+
+По мере продвижения задачи агент постепенно наращивает информацию в рамках той же сессии:
+
+- цель задачи
+- релевантный контекст кода
+- уже внесённые изменения
+- промежуточные рассуждения и решения
+
+Если сессиями не управлять, несвязанные задачи накапливаются в одной сессии, делая контекст излишне сложным. Это часто снижает качество рассуждений и выполнения агента.
+
+Общие практики:
+
+- **Используйте отдельную сессию для каждой задачи.** Не смешивайте несвязанные задачи, чтобы рабочий контекст оставался ясным
+- **Избегайте слишком длинных сессий.** Когда сессия накапливает слишком много истории, используйте резюме или сжатие для снижения нагрузки на контекст
+- **Начинайте новую сессию для ответвлений.** Если задача открывает новое направление исследования, продолжайте его в отдельной сессии
+- **Периодически сжимайте исторический контекст.** Резюмируйте старые части разговора для снижения давления на контекстное окно
+
+В более сложных сценариях команды могут использовать **модель многоагентного сотрудничества**: подзадачи (исследование кодовой базы, запуск тестов, расследование сбоев) делегируются отдельным агентам, а главный агент координирует общую задачу. Это сохраняет ясность основной сессии и повышает эффективность выполнения.
+
+## Заключение
+
+Эффективность coding agent определяется не только моделью. Она зависит от того, как разработчики выстраивают рабочий процесс вокруг неё.
+
+Зрелый рабочий процесс с coding agent обычно включает следующие этапы:
+
+1. Структурированный ввод задачи с контекстом
+2. Планирование перед выполнением
+3. Проектные правила в конфигурационных файлах
+4. Настроенная среда выполнения
+5. Участие в полном цикле разработки
+6. Расширение контекста через MCP
+7. Повторяющиеся процессы как Skills
+8. Автоматизация стабильных процессов
+9. Осознанное управление сессиями