主题: Часть 15. Заменяемость агента
难度等级: 中等
预计学习时间: 4-6 часов (теория + практика)
前置要求: Понимание основ SDD (Specification-Driven Development)
Опыт работы с Markdown и базовой структурой проектов
Знакомство с хотя бы одним AI-агентом для разработки (Qwen Code, Claude Code, Cursor и т.д.)
Базовые знания Git и работы с репозиториями
Понимание форматов JSON и конфигурационных файлов
学习目标: Создавать и поддерживать AGENTS.md и QWEN.md как переносимые контракты для AI-агентов, обеспечивая независимость проектной памяти от конкретного инструмента
Проводить аудит навыков (SKILL.md) на предмет отвязки от интерфейсных особенностей конкретного агента и успешно мигрировать их между различными AI-инструментами
Критически оценивать необходимость подключения MCP-серверов, различая сценарии повышения эффективности и избыточного расширения поверхности рисков
Выполнять проверку «новый агент» для валидации заменяемости: запускать агента без истории чата и подтверждать корректность определения следующего безопасного действия по проектным артефактам
Разбираться в совместимости ACP-протоколов при интеграции агентов с IDE и устранять типичные проблемы версионирования
概述: Заменяемость агента — фундаментальная характеристика зрелого SDD-процесса, обеспечивающая способность продолжить разработку любым AI-агентом или в любой IDE без потери проектной памяти. В современной разработке команды периодически мигрируют между инструментами: сегодня используется Qwen Code CLI, завтра — Codex, Claude Code, Gemini CLI, Cursor, Kiro или GitHub Spec Kit. Если намерение зафиксировано в Markdown-файлах, а процесс оформлен как навыки и команды, конкретный агент становится заменяемой исполнительной средой. Данный модуль систематизирует подходы к созданию агент-независимых артефактов, организации контрактов через AGENTS.md, переносу навыков, ответственному использованию MCP, пониманию ACP-интеграций и практической проверке заменяемости.
关键概念: Заменяемость агента: Способность продолжить процесс разработки другим агентом или в другой среде без потери проектной памяти. Достигается через вынесение всех решений, намерений и процессов в человекочитаемые файлы репозитория, а не в интерфейс или историю конкретного инструмента.
Агент-независимые артефакты: Файлы, которые должны содержать всю необходимую информацию для продолжения работы: README.md, AGENTS.md/QWEN.md, specs/ с mission.md, tech-stack.md, roadmap.md, спецификации фич, CHANGELOG.md, тесты и скрипты. Эти артефакты понятны любому агенту без дополнительного контекста.
Agents.md: Универсальный контракт для любого AI-агента, описывающий правила работы с проектом: обязательность спецификаций, порядок чтения файлов, правила ветвления, проверки перед слиянием, ограничения. Является основой переносимости между инструментами.
Qwen.md: Тонкий агент-специфичный файл, содержащий только инструментальные особенности Qwen Code (использование /clear, ссылки через @file, команды через !). Должен ссылаться на AGENTS.md, а не дублировать общие правила.
Skill.md и переносимость навыков: Формат навыков Qwen Code, построенный на Markdown-инструкциях с необязательными скриптами. При миграции между агентами содержимое SKILL.md переносится с минимальными правками инструментальных деталей, сохраняя суть процесса.
Mcp (model context protocol): Протокол для подключения внешних инструментов и источников данных к агенту. Настраивается в settings.json или через CLI. Каждый подключённый MCP-сервер расширяет поверхность действий агента — следовательно, поверхность потенциальных рисков.
Acp (agent client protocol): Протокол стандартного взаимодействия между агентом и клиентом/IDE. Позволяет заменять интерфейс, сохраняя процесс в репозитории. Версионная совместимость критична: несоответствие версий ACP v1/v2 ломало интеграцию Qwen Code с JetBrains в начале 2026 года.
Github spec kit: Внешний SDD-фреймворк, формализующий процесс: намерение → спецификация → план → задачи → реализация → проверка. Не привязан к конкретному агенту, служит ориентиром для стандартизации собственных процессов.
Проверка «новый агент»: Практический эксперимент заменяемости: очистка истории (/clear), имитация агента без контекста, чтение ключевых файлов и проверка способности корректно определить следующее безопасное действие без изменения файлов.
重要日期: 2026, начало года: JetBrains 2025.3+ перешли на ACP v2 с форматом prompt.turn, что вызвало несовместимость с Qwen Code, поддерживавшим только v1
2026 год: Восстановление совместимости в PR #1521 репозитория qwen-code после issue #1502. Критическое событие для понимания важности версионного контроля протоколов интеграции
练习题: 名称: Создание двухуровневой системы контрактов
问题: В вашем проекте накопилась смешанная документация: часть правил в QWEN.md, часть в README.md, часть только в вашей голове. Создайте чистую двухуровневую систему: универсальный AGENTS.md и тонкий QWEN.md. При этом QWEN.md должен содержать не более 8 строк и ссылаться на AGENTS.md через конструкцию «Сначала прочитай @AGENTS.md».
解决方案: 1. Проанализируйте текущий QWEN.md и выделите универсальные правила (не реализовать фичи без спеки, читать mission/tech-stack/roadmap, ветки по specs/YYYY-MM-DD-feature, npm test перед merge, никаких секретов в репо). 2. Перенесите универсальные правила в AGENTS.md с чёткой структурой: заголовок, перечень правил с маркерами. 3. Создайте новый QWEN.md: строка 1 — ссылка на AGENTS.md, строки 2-8 — только специфика Qwen Code (/clear между фазами, @file для спек, ! для локальных команд). 4. Удалите дублирование. 5. Проверьте: запустите qwen, дайте команду «прочитай @QWEN.md» и убедитесь, что агент корректно резолвит @AGENTS.md.
难度: intermediate
名称: Аудит навыка на переносимость
问题: У вас есть навык спецификации фичи в .qwen/skills/feature-spec/SKILL.md. Проведите аудит: найдите все привязки к интерфейсу Qwen Code (упоминания /clear, @file, !, qwen-specific команды) и определите, какие из них можно обобщить, а какие должны остаться в агент-специфичном слое.
解决方案: 1. Прочитайте SKILL.md и выделите каждую инструментальную деталь. 2. Классифицируйте: (а) суть процесса — находить фазу в дорожной карте, спрашивать границы, решения, контекст, создавать requirements/plan/validation — это остаётся; (б) способ вызова — /clear, @file, ! — это агент-специфика. 3. Реструктурируйте SKILL.md: раздел «Процесс» без привязок, раздел «Инструментальные детали для Qwen Code» с пометкой «при переносе адаптируйте под целевой агент». 4. Создайте тестовый перенос: скопируйте SKILL.md в условный каталог .cursor/skills/ и опишите, что поменяется для Cursor (Cmd+K вместо /clear, @ для контекста вместо @file).
难度: intermediate
名称: Оценка рисков MCP-подключения
问题: Ваша команда хочет подключить три MCP-сервера: (1) локальный сервер документации проекта через stdio, (2) внешний HTTP-сервер аналитики кода, (3) сторонний MCP из непроверенного репозитория «для удобства». Проведите оценку рисков и сформируйте рекомендацию.
解决方案: 1. Проанализируйте каждый сервер по критериям: необходимость, доверенность источника, поверхность действий, возможность аудита. 2. Сервер 1 (локальный stdio, node ./tools/mcp-server.js): высокая доверенность, ограниченная поверхность, необходим для проектной документации — рекомендовать с таймаутом 15000мс. 3. Сервер 2 (внешний HTTP): проверить аутентификацию, HTTPS, ограничить scope, рассмотреть VPN/белый список IP — условно рекомендовать с оговорками. 4. Сервер 3 (непроверенный сторонний): отказать, аргументируя принципом «не подключайте MCP на всякий случай» — каждый инструмент расширяет поверхность действий агента, а значит, поверхность потенциальных ошибок и угроз. 5. Оформите решение в виде записи в AGENTS.md: правило оценки MCP и перечень одобренных серверов.
难度: intermediate
名称: Проверка «новый агент» в действии
问题: Проведите полный цикл проверки заменяемости своего проекта. Симулируйте ситуацию, когда разработчик ушёл в отпуск, а новый участник команды (или другой агент) должен продолжить работу без личного контакта.
解决方案: 1. Выполните /clear в Qwen Code для сброса контекста. 2. Сформулируйте промпт: «Представь, что ты новый агент без истории чата. Прочитай @AGENTS.md, @QWEN.md, @specs/mission.md, @specs/tech-stack.md и @specs/roadmap.md. Скажи, какое следующее действие в проекте безопасно. Файлы не изменяй.» 3. Зафиксируйте ответ агента. 4. Проверьте корректность: сравните с вашим пониманием приоритетов — должен определить активную фазу roadmap, найти незавершённую спецификацию, предложить чтение соответствующего requirements.md. 5. Если ответ неверен — идентифицируйте пробел в документации (недостаточно деталей в roadmap? нет явных приоритетов? AGENTS.md не описывает процесс определения «следующего действия»?). 6. Исправьте и повторите до стабильного успеха.
难度: intermediate
名称: Диагностика ACP-интеграции
问题: Интеграция Qwen Code с JetBrains внезапно перестала работать после обновления IDE. Используя знания о версионировании ACP, проведите диагностику и сформируйте план восстановления.
解决方案: 1. Первый шаг диагностики — проверить версии: qwen --version и версию JetBrains IDE (Help → About). 2. Сравнить с историческим контекстом: JetBrains 2025.3+ используют ACP v2 (prompt.turn), старые версии Qwen Code поддерживали только v1 — issue #1502. 3. Если версия Qwen Code предшествует PR #1521 (2026 год) — обновить до актуальной версии. 4. Если версии совместимы — проверить конфигурацию agent_servers в настройках IDE: корректность пути, аргумент --acp, переменные окружения. 5. Проверить логи: в IDE (Help → Show Log in Explorer/Finder) и в выводе qwen --acp --verbose. 6. Сформировать план: (а) обновление агента, (б) откат IDE, (в) временное использование CLI-режима, (г) ожидание патча. 7. Зафиксировать инцидент в проектной документации для будущей заменяемости.
难度: advanced
案例研究: 名称: Миграция стартапа с Qwen Code на Claude Code без потери контекста
场景: Технологический стартап из 12 человек использовал Qwen Code CLI в течение 8 месяцев для разработки SaaS-платформы. Структура проекта включала specs/, SKILL.md для спецификации фич, QWEN.md с подробными инструкциями. Команде потребовалось перейти на Claude Code из-за лучшей интеграции с их CI/CD и требований enterprise-безопасности.
挑战: Основная проблема: QWEN.md содержал 200+ строк, смешивая универсальные правила SDD с глубокими привязками к интерфейсу Qwen Code (/clear, @file, !, специфичные workflow). Новые разработчики, привыкшие к Claude Code, терялись в неприменимых инструкциях. Навыки в .qwen/skills/ содержали прямые ссылки на qwen-специфичные команды. Проектная память фактически была заложена в «язык» одного инструмента, а не в структуру репозитория.
解决方案: Команда провела двухнедельный аудит по методологии заменяемости агента: 1) Выделила универсальные правила из QWEN.md в новый AGENTS.md — процесс спецификации, обязательные проверки, структура веток. 2) Сократила QWEN.md до 6 строк ссылочного файла. 3) Создала CLAUDE.md с аналогичной структурой для Claude Code (Cmd+Enter вместо /clear, контекстные упоминания вместо @file). 4) Реструктурировала все SKILL.md: раздел «Процесс» (переносимый) и «Инструментальные детали» (агент-специфичный). 5) Провела проверку «новый агент» для обоих инструментов — убедилась, что Claude Code корректно определяет следующие шаги по AGENTS.md + specs/.
结果: Миграция заняла 2 недели подготовки + 3 дня переключения команды. Проектная память сохранена полностью. Новые разработчики включались за 1-2 дня вместо прежних 1-2 недель. Через 3 месяца команда экспериментировала с Cursor для фронтенд-разработки, используя тот же AGENTS.md — время адаптации сократилось до нескольких часов.
经验教训: Раннее вложение в AGENTS.md окупается экспоненциально при смене инструментов — это страховка, а не оверхед
Навыки должны явно разделять суть процесса и инструментальные детали; иначе каждая миграция требует реинжиниринга
Проверка «новый агент» должна быть регулярной рутиной, а не разовым упражнением — она выявляет «деградацию» документации в процессе разработки
Мультиагентная среда (разные инструменты для разных задач) становится реальностью; архитектура должна это предполагать
相关概念: AGENTS.md и QWEN.md
Переносимость навыков SKILL.md
Проверка «новый агент»
Агент-независимые артефакты
名称: Инцидент с MCP-сервером: когда «удобство» стало угрозой
场景: Команда из 5 разработчиков подключила MCP-сервер для автоматической генерации документации API из внешнего сервиса. Сервер требовал доступа к внутренней сети и имел широкие права на чтение репозитория «для анализа контекста». Через 2 месяца обнаружилась утечка: сервер логировал фрагменты кода на сторонний сервер аналитики.
挑战: Проблема была в принципиальном подходе: MCP добавлялся «на всякий случай» без оценки поверхности рисков. Конфигурация в settings.json не была задокументирована в AGENTS.md. При уходе первого разработчика, настроившего MCP, знания о его существовании и рисках были утеряны. Новые члены команды не понимали, почему агент имеет доступ к внутренней сети.
解决方案: После инцидента команда внедрила строгую политику MCP: 1) Каждый MCP требует записи в AGENTS.md с обоснованием необходимости, описанием поверхности действий и рисков. 2) Локальные MCP через stdio предпочтительнее внешних HTTP. 3) Внешние MCP требуют аудита безопасности и ограничения по IP/VPN. 4) Регулярный пересмотр: раз в квартал все MCP проверяются на актуальность. 5) Удалён неиспользуемый сервер документации; заменён на локальный скрипт, генерирующий Markdown в репозиторий без внешних вызовов.
结果: Инцидент не привёл к компрометации production, но стоил 2 недель аудита и пересмотра политик. Новая система предотвратила 3 аналогичных «удобных» подключения в последующие 6 месяцев. Команда осознала, что заменяемость агента включает и заменяемость/удаляемость его инструментов без потери процесса.
经验教训: Принцип «не подключайте MCP на всякий случай» имеет конкретную цену нарушения — каждый инструмент расширяет поверхность действий агента и потенциальную поверхность атаки
Недокументированные интеграции — антипаттерн заменяемости; они создают скрытые зависимости, которые «убивают» проектную память при смене людей или инструментов
Локальные альтернативы (скрипты, генерация Markdown) часто предпочтительнее внешних сервисов, если цель — долгосрочная заменяемость
Регулярный пересмотр интеграций должен быть частью процесса, а не реакцией на инциденты
相关概念: MCP как внешний слой инструментов
Правило безопасности MCP
Агент-независимые артефакты
AGENTS.md как контракт
名称: Совместимость ACP v1/v2: урок из интеграции с JetBrains
场景: Корпоративная команда из 20 разработчиков использовала Qwen Code через ACP-интеграцию с JetBrains IDE (IntelliJ IDEA, PyCharm). В начале 2026 года после планового обновления IDE до версии 2025.3 интеграция перестала работать: агент не подключался, команды не выполнялись, логи показывали ошибки протокола.
挑战: Диагностика затруднялась отсутствием явной документации о версионировании ACP в проектных артефактах. Команда не знала, что использует ACP v1, а новая IDE требует v2 с форматом prompt.turn. Поиск решения занял 3 дня простоя: чтение issue на GitHub, анализ PR, эксперименты с downgrade IDE и различными флагами qwen. Знание о несовместимости не было зафиксировано в проектной документации, поэтому повторялось для каждого обновления рабочей станции.
解决方案: После восстановления совместимости через обновление Qwen Code (PR #1521) команда: 1) Добавила в AGENTS.md раздел «Интеграции и протоколы» с явным указанием версий ACP, MCP и других протоколов. 2) Создала скрипт проверки окружения (check-env.sh), выводящий версии агента, IDE, протоколов и флаги совместимости. 3) Настроила мониторинг issue репозитория qwen-code для критических изменений протоколов. 4) Документировала процедуру отката: временный переход на CLI-режим при несовместимости IDE.
结果: Следующее обновление JetBrains (2026.2) потребовало адаптации, но команда реагировала за 2 часа вместо 3 дней. Проверка окружения стала частью onboarding новых разработчиков. Архитектура «процесс в репозитории, интерфейс заменяем» получила конкретное воплощение: при поломке ACP команда переключалась на CLI без потери работоспособности.
经验教训: Версионное соответствие протоколов — критическая, но часто игнорируемая составляющая заменяемости; она должна быть явно документирована
Зависимость от IDE-интеграции создаёт единую точку отказа; CLI-режим как fallback — обязательная стратегия
Мониторинг upstream-изменений протоколов должен быть частью DevOps-процесса, а не ad-hoc активностью
Проверка окружения («health check») — практический инструмент обеспечения заменяемости: он делает скрытые зависимости видимыми
相关概念: ACP и IDE
Версионная совместимость протоколов
Проверка «новый агент»
Процесс в репозитории, интерфейс заменяем
学习建议: Начинайте практику с собственного проекта: возьмите текущий репозиторий и проведите аудит на заменяемость, используя контрольный список из практических заданий — теория усваивается глубже через личный контекст
Используйте метод «параллельного агента»: на неделю работайте с одним инструментом, фиксируя все неявные зависимости в заметках, затем попробуйте повторить задачу с другим агентом по вашему AGENTS.md — разрыв покажет реальные пробелы
Создавайте шаблоны, а не готовые файлы: подготовьте boilerplate AGENTS.md, QWEN.md, SKILL.md для быстрого старта новых проектов — это превращает заменяемость из усилия в привычку
Ведите «журнал инцидентов заменяемости»: фиксируйте каждый случай, когда смена агента, IDE или разработчика вызывала трение — через 3-6 месяцев паттерны покажут системные проблемы в архитектуре документации
Изучайте GitHub Spec Kit как эталон: даже если не внедряете, сравните ваш .qwen/skills/feature-spec с их процессом — это калибровка понимания «зрелой» заменяемости
Практикуйте «чёрный ящик»: попросите коллегу, не знакомого с проектом, прочитать только AGENTS.md + specs/ и описать, что бы он сделал дальше — внешняя перспектива выявляет «очевидное» для вас, но не для других
Документируйте отказы: когда проверка «новый агент» даёт неверный результат, не исправляйте сразу — сначала запишите, что именно пошло не так, это обучает распознавать категории проблем
附加资源: Репозиторий qwen-code и issue #1502/#1521: https://github.com/QwenLM/qwen-code/issues/1502 — первоисточник инцидента ACP v1/v2, обязателен для понимания реальной динамики протоколов
Github spec kit: https://github.com/github/spec-kit — внешний SDD-фреймворк для сравнения с собственными процессами, изучите структуру намерение→спецификация→план→задачи→реализация→проверка
Документация mcp (model context protocol): https://modelcontextprotocol.io — спецификация протокола, примеры серверов, лучшие практики безопасности
Acp specification: Внутренняя документация JetBrains и Qwen Code по Agent Client Protocol — отслеживайте changelogs для версионного контроля
Шаблон agents.md для старта: Создайте собственный на основе примера из курса, адаптируйте под стек команды и публикуйте как внутренний шаблон
Каталог skill.md проектов с открытым кодом: Анализируйте .qwen/skills/ в публичных репозиториях, использующих Qwen Code, для сбора паттернов переносимости
Инструменты статического анализа markdown: markdownlint, vale — для поддержания качества и консистентности проектной документации, критичной для понимания любым агентом
摘要: Заменяемость агента — это не техническая роскошь, а необходимость в мире быстро эволюционирующих AI-инструментов. Ключевые принципы: процесс живёт в репозитории, агент — заменяемая исполнительная среда. Практические опоры: AGENTS.md как универсальный контракт, тонкие агент-специфичные файлы (QWEN.md, CLAUDE.md), переносимые навыки с явным разделением сути и инструментальных деталей, обоснованное использование MCP с документированием рисков, понимание версионности протоколов (ACP), регулярная проверка «новый агент». Успешная заменяемость измеряется не количеством поддерживаемых инструментов, а скоростью и полнотой передачи проектной памяти между любыми агентами и людьми без потери контекста.