Часть 15. Заменяемость агента

Заменяемость агента — это способность продолжить процесс другим агентом или в другой IDE без потери проектной памяти. В SDD это естественная цель: если намерение записано в Markdown-файлах, а процесс оформлен как навыки и команды, конкретный агент становится заменяемой исполнительной средой.

Сегодня вы используете Qwen Code CLI. Завтра часть команды может использовать Codex, Claude Code, Gemini CLI, Cursor, Kiro или GitHub Spec Kit. Чем меньше решений живёт только в интерфейсе одного инструмента, тем устойчивее процесс.

Что должно быть независимым от агента

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:

# Инструкции для агента

В этом репозитории используется SDD.

- Не реализуй продуктовые фичи без спецификации фичи.
- Перед планированием прочитай specs/mission.md, specs/tech-stack.md и specs/roadmap.md.
- Ветка каждой фичи должна содержать specs/YYYY-MM-DD-feature-name/.
- Держи правки в границах активной спецификации.
- Перед слиянием запускай npm test и npm run typecheck.
- Не храни секреты в репозитории.

QWEN.md:

Сначала прочитай @AGENTS.md.
Примечания для Qwen Code:
- Используй /clear между планированием, реализацией и проверкой.
- Ссылайся на спецификации через @file.
- Используй команды через ! для локальной проверки.

Переносимость навыков

Навыки Qwen Code используют SKILL.md. Этот формат похож на общее соглашение для навыков агента: Markdown-инструкции плюс необязательные скрипты и шаблоны. Даже если другой агент хранит навыки в другом месте, содержимое можно перенести.

При переносе:

.qwen/skills/feature-spec/SKILL.md

можно скопировать в каталог навыков другого агента и поправить только инструментальные детали. Суть процесса остаётся прежней: найти фазу в дорожной карте, спросить границы, решения и контекст, создать requirements.md, plan.md и validation.md.

MCP как внешний слой инструментов

MCP позволяет подключать внешние инструменты и источники данных. В Qwen Code MCP настраивается в settings.json или через qwen mcp add.

Пример локального MCP через stdio:

{
  "mcpServers": {
    "projectTools": {
      "command": "node",
      "args": ["./tools/mcp-server.js"],
      "timeout": 15000
    }
  }
}

Пример команды:

qwen mcp add --transport http docs http://localhost:3000/mcp
qwen mcp

Правило безопасности: не подключайте MCP «на всякий случай». Каждый инструмент расширяет поверхность действий агента.

ACP и IDE

Agent Client Protocol (ACP) нужен, чтобы агент и клиент/IDE могли взаимодействовать стандартно. Qwen Code умеет работать с JetBrains через ACP-режим:

{
  "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). Совместимость восстановлена в PR #1521 ещё в 2026 году. Если интеграция с JetBrains внезапно перестаёт работать, первое, что стоит проверить, — версия Qwen Code и версия IDE: они должны говорить на одной версии ACP.

GitHub Spec Kit как внешний SDD-фреймворк

GitHub Spec Kit предлагает более формальный процесс: описать намерение, спланировать, разбить на задачи, реализовать. Он не привязан к конкретному агенту и может работать с разными агентами, которые пишут код. Его не обязательно внедрять в AgentClinic, но полезно знать, что ваш ручной цикл SDD совпадает с общим направлением:

намерение → спецификация → план → задачи → реализация → проверка

Если команда хочет больше стандартизации, можно сравнить ваш .qwen/skills/feature-spec с Spec Kit и решить, нужен ли отдельный фреймворк.

Проверка заменяемости

Проведите эксперимент:

/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 полезен, а когда он только добавляет риск?