# Часть 15. Заменяемость агента Заменяемость агента — это способность продолжить процесс другим агентом или в другой IDE без потери проектной памяти. В SDD это естественная цель: если намерение записано в Markdown-файлах, а процесс оформлен как навыки и команды, конкретный агент становится заменяемой исполнительной средой. Сегодня вы используете Qwen Code CLI. Завтра часть команды может использовать Codex, Claude Code, Gemini CLI, Cursor, Kiro или GitHub Spec Kit. Чем меньше решений живёт только в интерфейсе одного инструмента, тем устойчивее процесс. ## Что должно быть независимым от агента ```text README.md QWEN.md / AGENTS.md specs/ mission.md tech-stack.md roadmap.md YYYY-MM-DD-feature/ requirements.md plan.md validation.md CHANGELOG.md tests/ скрипты package.json ``` Если эти файлы понятны, другой агент сможет продолжить работу. ## QWEN.md и AGENTS.md Qwen Code использует `QWEN.md`, но также может читать `AGENTS.md`. Если вы хотите переносимость, заведите `AGENTS.md` как общий контракт, а `QWEN.md` сделайте тонким указателем. `AGENTS.md`: ```markdown # Инструкции для агента В этом репозитории используется SDD. - Не реализуй продуктовые фичи без спецификации фичи. - Перед планированием прочитай specs/mission.md, specs/tech-stack.md и specs/roadmap.md. - Ветка каждой фичи должна содержать specs/YYYY-MM-DD-feature-name/. - Держи правки в границах активной спецификации. - Перед слиянием запускай npm test и npm run typecheck. - Не храни секреты в репозитории. ``` `QWEN.md`: ```markdown Сначала прочитай @AGENTS.md. Примечания для Qwen Code: - Используй /clear между планированием, реализацией и проверкой. - Ссылайся на спецификации через @file. - Используй команды через ! для локальной проверки. ``` ## Переносимость навыков Навыки Qwen Code используют `SKILL.md`. Этот формат похож на общее соглашение для навыков агента: Markdown-инструкции плюс необязательные скрипты и шаблоны. Даже если другой агент хранит навыки в другом месте, содержимое можно перенести. При переносе: ```text .qwen/skills/feature-spec/SKILL.md ``` можно скопировать в каталог навыков другого агента и поправить только инструментальные детали. Суть процесса остаётся прежней: найти фазу в дорожной карте, спросить границы, решения и контекст, создать `requirements.md`, `plan.md` и `validation.md`. ## MCP как внешний слой инструментов MCP позволяет подключать внешние инструменты и источники данных. В Qwen Code MCP настраивается в `settings.json` или через `qwen mcp add`. Пример локального MCP через stdio: ```json { "mcpServers": { "projectTools": { "command": "node", "args": ["./tools/mcp-server.js"], "timeout": 15000 } } } ``` Пример команды: ```bash qwen mcp add --transport http docs http://localhost:3000/mcp qwen mcp ``` Правило безопасности: не подключайте MCP «на всякий случай». Каждый инструмент расширяет поверхность действий агента. ## MCP против CLI: экономика инструментов MCP — это не замена API, а prompt-управляемая обёртка вокруг внешнего сервиса. Агент обращается к сервису «по смыслу», а не вручную складывает запросы. Пример: Supabase MCP позволяет вытащить нужные данные или выполнить SQL прямо на стороне базы, без копипасты результатов туда-сюда. Удобство обёртки стоит контекста. Для большинства внешних сервисов, вокруг которых строят MCP, уже есть зрелые CLI — GitHub (`gh`), Supabase, Vercel, Railway. MCP по сути оборачивает эти же команды. Если инструмент нужен лишь изредка, дешевле обернуть нужные функции CLI в навык или команду, чем держать MCP постоянно загруженным. Пример. Вместо постоянно включённого GitHub MCP заведите навык или команду `gh-pr` поверх `gh pr create` с нужными опциями (база, шаблон описания, метки): ```text .qwen/skills/gh-pr/SKILL.md -> запускает: gh pr create --base main --fill --label feature ``` Важно различать две статьи расходов. Ленивая загрузка навыка решает проблему контекста: навык грузится по требованию, а не висит в системном промпте всё время. Но стоимость токенов на сам вызов он не убирает — это отдельная экономия, ради которой CLI-подход и остаётся выгодным даже при ленивой загрузке. Практическое правило окупаемости: ```text MCP оправдан, если инструмент нужен в значимой доле запросов. Для редких обращений дешевле CLI + навык. ``` Эта развилка усиливает главную мысль части. Навык поверх CLI — обычный артефакт в репозитории: он переносится между агентами и не привязывает процесс к тому, что у конкретного агента включён конкретный MCP. Чем больше возможностей живёт в виде команд и навыков, а не в наборе включённых MCP-серверов, тем легче заменить агента. ## ACP и IDE Agent Client Protocol (ACP) нужен, чтобы агент и клиент/IDE могли взаимодействовать стандартно. Qwen Code умеет работать с JetBrains через ACP-режим: ```json { "agent_servers": { "qwen": { "command": "/path/to/qwen", "args": ["--acp"], "env": {} } } } ``` Даже если вы используете CLI, полезно понимать направление: процесс должен жить в репозитории, а интерфейс должен быть заменяемым. Историческое примечание: в начале 2026 года JetBrains 2025.3+ перешли на ACP v2 (`prompt.turn`), а Qwen Code некоторое время поддерживал только v1, что ломало интеграцию (issue [QwenLM/qwen-code#1502](https://github.com/QwenLM/qwen-code/issues/1502)). Совместимость восстановлена в PR #1521 ещё в 2026 году. Если интеграция с JetBrains внезапно перестаёт работать, первое, что стоит проверить, — версия Qwen Code и версия IDE: они должны говорить на одной версии ACP. ## GitHub Spec Kit как внешний SDD-фреймворк GitHub Spec Kit предлагает более формальный процесс: описать намерение, спланировать, разбить на задачи, реализовать. Он не привязан к конкретному агенту и может работать с разными агентами, которые пишут код. Его не обязательно внедрять в AgentClinic, но полезно знать, что ваш ручной цикл SDD совпадает с общим направлением: ```text намерение → спецификация → план → задачи → реализация → проверка ``` Если команда хочет больше стандартизации, можно сравнить ваш `.qwen/skills/feature-spec` с Spec Kit и решить, нужен ли отдельный фреймворк. ## Проверка заменяемости Проведите эксперимент: ```text /clear Представь, что ты новый агент без истории чата. Прочитай @AGENTS.md, @QWEN.md, @specs/mission.md, @specs/tech-stack.md и @specs/roadmap.md. Скажи, какое следующее действие в проекте безопасно. Файлы не изменяй. ``` Если ответ правильный, проектная память работает. ## Практика 1. Создайте `AGENTS.md`. 2. Сделайте `QWEN.md` коротким файлом только для Qwen Code. 3. Проверьте, что навык спецификации фичи не содержит лишних деталей, привязанных к Qwen Code. 4. Опишите MCP только для реально нужных инструментов. 5. Запустите проверку «новый агент». ## Контрольные вопросы 1. Какие артефакты делают процесс переносимым? 2. Почему навыки лучше не привязывать к одному интерфейсу? 3. Когда MCP полезен, а когда он только добавляет риск?