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/README.md

@@ -0,0 +1,14 @@
+# Разработка с ИИ
+
+Практические материалы о работе с ИИ-ассистентами для разработчиков: как эффективно взаимодействовать с coding agents, организовать контекст и память, выстроить рабочий процесс.
+
+Раздел не привязан к основному роадмапу по Data Engineering и может использоваться независимо.
+
+## Материалы
+
+- [Лучшие практики работы с coding agents](best-practice.md): 10 принципов эффективной работы с ИИ-ассистентами, от структурирования задач до автоматизации
+- [Механизм памяти coding agents](memory-mechanism.md): как устроена память агентов, типы памяти, многоуровневая организация и практические рекомендации
+
+## Источники
+
+Материалы раздела подготовлены на основе документации [Z.AI DevPack](https://docs.z.ai/devpack/resources/best-practice).

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. Осознанное управление сессиями

ai-dev/memory-mechanism.md

@@ -0,0 +1,362 @@
+# Механизм памяти coding agents
+
+> По мотивам [Memory Mechanism](https://docs.z.ai/devpack/resources/memory-mechanism) (Z.AI DevPack)
+
+Память позволяет coding agent сохранять контекст между задачами и сессиями, сокращая повторный ввод и повышая эффективность выполнения. С хорошо продуманной системой памяти агент может постоянно учитывать структуру проекта, инженерные конвенции и предпочтения пользователя, автоматически переиспользуя эту информацию в будущей работе.
+
+В системах coding agents память обычно организована в несколько слоёв: **автоматическая память, проектная память** и **сессионная память**.
+
+## Зачем coding agents нужна память?
+
+Традиционные большие языковые модели не сохраняют состояние между вызовами. Они не могут запомнить контекст проекта между сессиями, накапливать опыт решения проблем или последовательно адаптироваться к предпочтениям пользователя.
+
+Агентные системы решают это ограничение через **внешнюю память**.
+
+Типичная архитектура выглядит так:
+
+```
+Ввод пользователя
+       ↓
+Извлечение памяти
+       ↓
+Сборка контекста
+       ↓
+Рассуждение LLM
+       ↓
+Действие / вызов инструмента
+       ↓
+Обновление памяти
+```
+
+Агент извлекает релевантную память перед началом задачи и обновляет память после завершения.
+
+Эта архитектура является общим паттерном в современных агентных системах, таких как LangGraph, AutoGPT и Devin.
+
+## Полная архитектура памяти
+
+На высоком уровне полная архитектура памяти агента выглядит так:
+
+```
+Краткосрочная память
+    ↓
+Контекст сессии
+
+Долгосрочная память
+    ├ семантическая память
+    ├ эпизодическая память
+    └ процедурная память
+```
+
+## Основные типы памяти
+
+### Сессионная память
+
+Сессионная память — это контекстная информация текущей задачи. Включает текущую историю разговора, последние результаты инструментов, текущий план выполнения и содержимое файлов в области видимости. Эта информация обычно находится в контекстном окне модели.
+
+Пример:
+
+```
+Пользователь: Исправь этот баг в Python
+Агент: Анализирует ошибку
+Агент: Модифицирует код
+Агент: Запускает тесты
+```
+
+Все эти шаги выполнения относятся к сессионной памяти.
+
+### Проектная память
+
+Проектная память хранит **долгоживущую информацию о всей кодовой базе**: архитектуру проекта, стандарты кодирования, процессы сборки, часто используемые команды. Такая память обычно записывается в `.md`-файлы и загружается в начале сессии.
+
+Пример структуры:
+
+```
+your-project/
+├── .claude/
+│   ├── CLAUDE.md           # Основные инструкции проекта
+│   └── rules/
+│       ├── code-style.md   # Стиль кода
+│       ├── testing.md      # Конвенции тестирования
+│       └── security.md     # Требования безопасности
+```
+
+При такой структуре агент автоматически следует этим правилам при модификации кода.
+
+### Семантическая память
+
+Семантическая память хранит фактические знания и справочную информацию: документацию API, правила языков программирования, базы знаний проекта. На практике часто реализуется через RAG (Retrieval-Augmented Generation).
+
+Типичный поток:
+
+```
+запрос
+  ↓
+эмбеддинг
+  ↓
+векторный поиск
+  ↓
+извлечение документов
+  ↓
+рассуждение LLM
+```
+
+Это один из наиболее распространённых методов запоминания в coding agents.
+
+### Эпизодическая память
+
+Эпизодическая память записывает прошлый опыт агента: шаги исправления предыдущего бага, корневую причину прошлого сбоя сборки, стратегию отладки, которая сработала. Этот тип памяти помогает агенту учиться на предыдущем опыте.
+
+Пример:
+
+```
+Эпизод:
+Сбой CI из-за отсутствующей зависимости
+Решение: обновить pip-пакет
+```
+
+### Процедурная память
+
+Процедурная память хранит стратегии или пошаговые процессы выполнения задач.
+
+Пример:
+
+```
+Debug_Workflow.md
+1. прочитать лог ошибок
+2. найти файл
+3. написать патч
+4. запустить тесты
+```
+
+Такая память обычно используется в системных промптах, шаблонах рабочих процессов и политиках агента.
+
+## Стандартный паттерн использования памяти
+
+В реальных системах агенты обычно следуют единообразному процессу работы с памятью.
+
+**Шаг 1: Извлечение памяти**
+
+Перед началом задачи агент извлекает релевантную проектную память, записи из базы знаний и предыдущий опыт, затем внедряет их в рабочий контекст.
+
+**Шаг 2: Сборка контекста**
+
+Извлечённые воспоминания собираются в полный контекст и передаются модели.
+
+**Шаг 3: Обновление памяти**
+
+После завершения задачи агент решает, нужно ли записать новые воспоминания: обнаруженные проектные правила, опыт отладки или предпочтения пользователя.
+
+## Как правильно использовать память
+
+В основных агентных системах память проектируется как **многослойная, управляемая, извлекаемая и обновляемая**.
+
+Обычно память делится на **краткосрочную** и **долгосрочную**. Краткосрочная используется для сохранения состояния в текущем потоке или сессии. Долгосрочная поддерживается через явные файлы, конфигурации правил, векторное извлечение или другие механизмы постоянного хранения.
+
+Например, в **Claude Code** каждая сессия начинается с чистого контекстного окна. Знания переносятся между сессиями через файлы инструкций (CLAUDE.md) и **автоматическую память**. В **LangChain / LangGraph** память также делится на **краткосрочную в рамках потока** и **долгосрочную между сессиями**.
+
+На практике наиболее эффективный подход: не полагаться на модель в автоматическом «запоминании всего», а установить чёткий паттерн управления памятью. Определить: что записывать в проектные файлы памяти, что извлекать из базы знаний или векторного хранилища, что оставить только в текущей сессии, а что продвинуть в долгосрочную память после завершения задачи.
+
+### Разделяйте инструкционную и обучающую память
+
+Один из наиболее практичных принципов: различать два фундаментально разных вида памяти.
+
+- **Инструкционная память**: написана людьми, чтобы указать агенту, как он должен работать. Обычно включает стандарты кодирования, конвенции директорий, команды сборки, процедуры тестирования, требования к именованию, правила коммитов и правила безопасности на уровне команды. В Claude Code это файлы инструкций вроде `CLAUDE.md`
+
+- **Обучающая память**: не определена заранее, а накоплена агентом из ваших поправок, предпочтений, неудачных попыток, частых команд и привычек проекта. В Claude Code это называется автоматическая память (auto memory)
+
+Если эти два типа памяти смешиваются, поведение системы со временем дрейфует. Лучший подход: чётко разделить их роли.
+
+- **Правила, политики и поведенческие ограничения** записывайте в **инструкционную память**, чтобы поведение агента оставалось стабильным и предсказуемым
+- **Опыт, предпочтения пользователя, временные открытия и ретроспективные выводы** записывайте в **обучающую память**, чтобы решения улучшались в будущих задачах
+
+Это разделение предотвращает постепенное загрязнение основных правил системы заметками из опыта.
+
+### Многоуровневое управление памятью
+
+#### Уровень организации
+
+Правила, определённые и распространяемые на уровне команды или компании, применимые ко всем разработчикам и проектам:
+
+- требования безопасности и соответствия
+- базовые стандарты код-ревью
+- запрещённые директории для чтения/записи
+- ограничения зависимостей и лицензий
+- инженерные стандарты организации
+
+На организационном уровне общий файл правил развёртывается по системному пути и не должен легко отключаться пользователями. **Организационная память — это высокоприоритетный управленческий слой, который не должен обходиться.**
+
+#### Уровень проекта
+
+Командный контекст проекта, версионируемый и общий для всех участников. **Это самый важный слой памяти для coding agent.**
+
+- документация архитектуры проекта
+- конвенции структуры директорий
+- команды сборки и тестирования
+- где должны располагаться API
+- конвенции именования
+- типовые процессы разработки
+
+Claude Code рекомендует хранить эту информацию в проектном файле, а команда `/init` может автоматически сгенерировать первоначальный черновик. Ключевое свойство этого слоя: **общий для проекта, под контролем версий, стабильный во времени**.
+
+#### Уровень пользователя
+
+Персональные предпочтения разработчика, применимые ко всем проектам. Лучше хранить в домашней директории пользователя как переиспользуемый личный контекст для всех рабочих пространств:
+
+- предпочитаемый стиль кодирования
+- привычная последовательность отладки
+- предпочитаемый формат вывода
+- персональные быстрые команды
+
+Должен дополнять проектные конвенции, а не переопределять их.
+
+#### Локальный уровень
+
+Специфичен для вашей локальной копии проекта, **не должен попадать в Git**:
+
+- персональные тестовые аккаунты
+- локальные порты разработки
+- временные адреса тестовых заглушек
+- заметки по среде выполнения на конкретной машине
+- экспериментальные рабочие процессы, не готовые к распространению
+
+Ценность этого слоя: **позволяет индивидуальную эффективную работу без загрязнения общей памяти**.
+
+#### Уровень субагента / роли
+
+Разные субагенты могут поддерживать собственные области памяти вместо использования единой глобальной. Это особенно важно в многоагентных системах, где одна из самых частых проблем: загрязнение контекста между ролями.
+
+Лучший паттерн: каждый субагент хранит только память, релевантную его роли:
+
+- **агент тестирования** помнит команды тестирования, поведение CI, стиль утверждений
+- **агент рефакторинга** помнит границы модулей, запрещённые зависимости, стратегии миграции
+- **агент документации** помнит глоссарий терминов, шаблоны документации, стиль для целевой аудитории
+
+Это делает память короче, точнее и стабильнее.
+
+### Загрузка `.md`-файлов по пути
+
+Для крупных репозиториев рекомендуется разделять инструкции на несколько Markdown-файлов в `.claude/rules/`, каждый посвящён одной теме: `testing.md`, `api-design.md`, `security.md`.
+
+Claude Code также поддерживает **привязку правил к определённым поддиректориям или типам файлов**: правила загружаются только когда агент работает с подходящими файлами. Это снижает шум и экономит контекстное окно.
+
+Три принципа организации:
+
+- **Основной файл памяти ограничен глобальным общим контекстом**: фон проекта, высокоуровневая архитектура, кросс-проектные конвенции
+- **Специализированные правила модульны**: один файл правил на тему
+- **Если правило можно загрузить по пути, не загружайте его глобально**: включайте в контекст только при необходимости
+
+Пример структуры:
+
+```
+agent-memory/
+├── project.md            # Обзор проекта
+├── rules/
+│   ├── code-style.md     # Стиль кода
+│   ├── testing.md        # Конвенции тестирования
+│   ├── api-design.md     # Правила дизайна API
+│   ├── security.md       # Требования безопасности
+│   └── frontend/
+│       └── react.md      # Правила фронтенда
+└── local/
+    └── developer.local.md
+```
+
+Три преимущества такой структуры:
+
+1. **Проще поддерживать.** Каждый файл правил фокусируется на одной теме, набор правил менее склонен к разрастанию
+2. **Проще загружать по запросу.** Когда агент работает над тестами, ему не нужно загружать конвенции фронтенда или правила баз данных
+3. **Лучше для командной работы.** Разные команды могут поддерживать собственные директории правил вместо редактирования единого монолитного файла
+
+### Пишите правила памяти как конкретные инструкции
+
+При написании памяти агента используйте **конкретные, проверяемые правила**, а не абстрактные принципы. Чем яснее инструкции, тем стабильнее поведение агента.
+
+Общие рекомендации:
+
+- инструкции должны быть **лаконичными и явными**
+- правила должны быть **согласованы** друг с другом
+- основной файл памяти **не более 200 строк** по возможности
+- используйте **Markdown-заголовки и списки** для читаемости
+- формулируйте требования как правила, которые можно **проверить и выполнить**
+
+Избегайте расплывчатых формулировок:
+
+- ~~Держите код чистым~~
+- ~~Пишите хорошие тесты~~
+- ~~Следите за дизайном API~~
+- ~~Разделяйте модули при необходимости~~
+
+Предпочитайте конкретные правила:
+
+- Используйте **2-пробельный отступ** во всех новых TypeScript-файлах
+- **Запускайте `pnpm test`** после модификации бизнес-логики
+- Размещайте **все обработчики API в `src/api/handlers/`**
+- Держите React-компоненты страниц **менее 300 строк**; разбивайте большие на хуки или дочерние компоненты
+
+Конкретные правила значительно сокращают пространство для интерпретации агентом, что повышает стабильность поведения.
+
+### Переиспользование памяти через импорт
+
+В реальных проектах многие правила — это **общие инженерные конвенции между репозиториями**. Переписывание их в каждом репозитории увеличивает накладные расходы на поддержку и повышает вероятность рассогласования.
+
+В Claude Code:
+
+- `CLAUDE.md` может импортировать другие файлы правил через `@path/to/import`
+- `.claude/rules/` может делить правила через **символические ссылки** (symlinks)
+- импортируемый контент раскрывается **рекурсивно**, символические ссылки разрешаются нормально
+
+Это позволяет командам создавать **переиспользуемые пакеты правил**:
+
+- `company-security-rules`
+- `frontend-react-rules`
+- `backend-api-rules`
+- `python-testing-rules`
+
+Каждый проект ссылается только на нужные модули правил, а не поддерживает полную копию всего набора.
+
+Два прямых преимущества:
+
+1. **Правила поддерживаются централизованно и обновляются единообразно**
+2. **Разные проекты разделяют один инженерный язык**, делая поведение агента согласованным между репозиториями
+
+## Устранение проблем с памятью
+
+### Агент не следует `.md`-файлам памяти
+
+`.md`-файлы памяти предоставляются агенту как контекстные инструкции, а не как принудительная конфигурация. Агент прочитает их и попытается следовать, но не гарантирует строгое соблюдение при расплывчатых, неясных или конфликтующих правилах.
+
+Если агент не следует правилам, проверьте:
+
+- Подтвердите загрузку `.md`-файлов памяти (команда `/memory` или аналог)
+- Проверьте, находятся ли файлы в пути, разрешённом для загрузки в текущей сессии
+- Проверьте конфликты правил между файлами. Если разные файлы дают разные инструкции для одного поведения, агент может выбрать произвольно
+
+### Непонятно, что сохранила автоматическая память
+
+Большинство coding agents поддерживают авто-память в фоне для захвата контекста проекта, предпочтений пользователя или частых действий.
+
+Способы проверки:
+
+- Выполните `/memory` (или аналогичную команду) для просмотра текущей директории авто-памяти
+- Авто-память обычно хранится в Markdown-файлах, которые можно читать, редактировать или удалять напрямую
+
+### Файлы памяти слишком большие
+
+Раздутые файлы памяти потребляют больше контекстного окна, снижают следование инструкциям и увеличивают вероятность конфликтов.
+
+Рекомендуется:
+
+- разделить детальный контент на несколько Markdown-файлов
+- использовать ссылки на файлы или импорты (`@path/to/file`)
+- перенести правила в выделенную директорию правил (`rules/`)
+
+### Инструкции исчезают после сжатия контекста
+
+Многие coding agents **сжимают или резюмируют контекст** в длинных разговорах для уменьшения длины контекста.
+
+В большинстве случаев файлы памяти **перезагружаются с диска** после сжатия, поэтому сохраняется только контент, записанный в файлы памяти. Если правила исчезают после сжатия, значит они **существовали только в разговоре** и не были записаны в файл.
+
+Решение:
+
+- записывайте долгосрочные инструкции в `.md`-файлы памяти
+- не полагайтесь только на разговор для сохранения правил

mkdocs.yml

@@ -31,6 +31,10 @@ nav:
       - SCD: dwh-modeling/SCD.md
       - Data Vault: dwh-modeling/DataVault.md
       - "Домашка: STG → DDS → DM": dwh-modeling/Homework_Customer_Status_DDS_DM.md
+  - Разработка с ИИ:
+      - Введение: ai-dev/README.md
+      - Лучшие практики: ai-dev/best-practice.md
+      - Механизм памяти: ai-dev/memory-mechanism.md
 
 theme:
   name: material