diff --git a/ai-dev/README.md b/ai-dev/README.md new file mode 100644 index 0000000..e1cfb1a --- /dev/null +++ b/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). diff --git a/ai-dev/best-practice.md b/ai-dev/best-practice.md new file mode 100644 index 0000000..35ebf08 --- /dev/null +++ b/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. Осознанное управление сессиями diff --git a/ai-dev/memory-mechanism.md b/ai-dev/memory-mechanism.md new file mode 100644 index 0000000..87b7ee4 --- /dev/null +++ b/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`-файлы памяти +- не полагайтесь только на разговор для сохранения правил diff --git a/mkdocs.yml b/mkdocs.yml index b30b5d2..82982fe 100644 --- a/mkdocs.yml +++ b/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