Как дать AI-агенту для кодинга надёжные знания предметной области

Универсальный coding agent может написать правдоподобный ответ и пропустить решающую деталь вашего стека: недавно изменившийся API, границу репозитория или соглашение, поддерживающее стабильность production. Решение не всегда в более длинном промпте. Лучше дать агенту небольшие повторно используемые инструкции предметной области и проверяемое определение готовности.

1. Отделите правила проекта от процедур предметной области

Начните с двух уровней. Первый — короткий контракт репозитория: что это за проект, как он устроен, какие команды выполняют сборку и тесты, какие файлы нельзя менять и что означает “готово”. В документации JetBrains о поведении агентов файлы вроде AGENTS.md и CLAUDE.md описаны как инструкции, которые хранятся вместе с репозиторием и могут использоваться разными инструментами.

Сделайте этот уровень стабильным и практичным. Он должен отвечать, где находится доменная логика, как запускать проверки и что запрещено редактировать. Правило для одного процесса вынесите в отдельный skill.

Второй уровень — знания предметной области: точный рецепт повторяющейся задачи, например миграции Android-навигации, изменения схемы БД или подготовки релиза. Skill должен иметь понятный триггер, короткую последовательность и явную проверку.

2. Стройте skill вокруг пробела в знаниях

Хороший skill нужен потому, что модель регулярно ошибается или заново ищет одно и то же. Философия Android Skills предлагает искать проверяемые пробелы, особенно при изменении API или нестандартной архитектуре. Она также советует брать skills из надёжных источников, а не из больших непроверенных коллекций с потенциально вредными инструкциями.

Небольшой пример:

---
name: navigation-upgrade
description: Use when changing the app's Navigation 3 setup or upgrading its related APIs.
---

Before editing:
1. Inspect the current dependency versions and existing navigation tests.
2. Read the project's navigation conventions.
3. Confirm the target API in the approved platform documentation.

While editing:
- Make the smallest vertical change that satisfies the requested behavior.
- Do not replace the navigation architecture without approval.
- Preserve existing deep-link and back-stack behavior unless the task says otherwise.

Done means:
- The focused tests pass.
- The relevant build or lint command passes.
- The response names changed files, checks run, and unresolved risks.

Пример намеренно узкий. Он не вставляет полное руководство по framework в каждый запрос, а задаёт момент применения, проверки, границы и доказательство готовности. Замените проверки на реальные команды и соглашения вашего репозитория.

3. Пусть агент сначала исследует

Coding agents объединяют запрос с контекстом среды, рассуждают над ним и выполняют редактирование, тесты и сборку. Именно такой процесс описан в рекомендациях AWS для coding agents. Инструкции должны сделать этапы видимыми.

Практический запрос состоит из четырёх частей:

1. Контекст: функция, каталоги и ограничения.
2. План: список файлов и проверок до редактирования.
3. Изменение: минимальная реализация для критериев приёмки.
4. Доказательства: точные тесты, lint, build или ручные проверки.

Это не даёт агенту начать с одной фразы, поздно обнаружить архитектуру и компенсировать это широким переписыванием. Исследование — источник контекста, на котором основаны решения.

4. Дайте короткую петлю обратной связи

Инструкции области объясняют проект, а исполняемые проверки показывают, работает ли изменение. Актуальное руководство VS Code по TDD разделяет red с падающим тестом, green с минимальной реализацией и refactor при сохранении зелёных тестов.

Три сложных агента не обязательны. Для маленькой задачи сначала попросите падающий или characterization-тест, затем реализуйте изменение и запустите обычные quality gates. Если проверка не проходит, это информация о требовании или среде, а не повод скрывать сбой в уверенном отчёте.

5. Пересматривайте и выводите инструкции из употребления

Считайте skill версионируемой инженерной инфраструктурой. Проверяйте его при изменении framework, повторяющейся ошибке агента или шумной проверке. Руководство Android Skills прямо рассматривает skills как кандидатов на deprecation: модели улучшаются, старые инструкции становятся лишними, а новые API создают новые пробелы.

Простой цикл обслуживания:

• Храните пример задачи, использующий skill.
• Записывайте ожидаемые файлы и команды проверки.
• Запускайте пример после изменения skill или модели.
• Удаляйте ненужные инструкции.
• Оставляйте чувствительные действия явными, необязательными и проверяемыми.

Цель — не заставить агента звучать умнее, а сделать правильное поведение воспроизводимым: короткий контракт репозитория, точная процедура и исполняемое определение готовности ведут от контекста к изменению и доказательствам.