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>
2026-04-02 11:05:12 +03:00
parent f1d118b81e
commit f1a3ec00dd
4 changed files with 614 additions and 0 deletions
@@ -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`-файлы памяти
+- не полагайтесь только на разговор для сохранения правил