Topic: Part 15. Agent Replaceability
Difficulty level: Medium
Estimated study time: 4-6 hours (theory + practice)
Prerequisites: Understanding of SDD (Specification-Driven Development) fundamentals
Experience with Markdown and basic project structure
Familiarity with at least one AI agent for development (Qwen Code, Claude Code, Cursor, etc.)
Basic Git knowledge and repository operations
Understanding of JSON formats and configuration files
Learning objectives: Create and maintain AGENTS.md and QWEN.md as portable contracts for AI agents, ensuring project memory independence from any specific tool
Audit skills (SKILL.md) for decoupling from interface-specific features of a particular agent and successfully migrate them between different AI tools
Critically evaluate the need for MCP server connections, distinguishing between scenarios that enhance efficiency and those that unnecessarily expand the risk surface
Perform the "new agent" check for replaceability validation: launch an agent without chat history and confirm correct determination of the next safe action based on project artifacts
Understand ACP protocol compatibility when integrating agents with IDEs and resolve typical versioning issues
Overview: Agent replaceability is a fundamental characteristic of a mature SDD process, ensuring the ability to continue development with any AI agent or in any IDE without losing project memory. In modern development, teams periodically migrate between tools: today it's Qwen Code CLI, tomorrow it's Codex, Claude Code, Gemini CLI, Cursor, Kiro, or GitHub Spec Kit. If intent is captured in Markdown files and process is formalized as skills and commands, the specific agent becomes a replaceable execution environment. This module systematizes approaches to creating agent-independent artifacts, organizing contracts through AGENTS.md, transferring skills, responsible MCP usage, understanding ACP integrations, and practical replaceability verification.
Key concepts: Agent replaceability: The ability to continue the development process with another agent or in another environment without losing project memory. Achieved by extracting all decisions, intents, and processes into human-readable repository files rather than the interface or history of a specific tool.
Agent-independent artifacts: Files that must contain all information necessary to continue work: README.md, AGENTS.md/QWEN.md, specs/ with mission.md, tech-stack.md, roadmap.md, feature specifications, CHANGELOG.md, tests and scripts. These artifacts are understandable by any agent without additional context.
Agents.md: A universal contract for any AI agent describing the rules for working with a project: mandatory specifications, file reading order, branching rules, pre-merge checks, limitations. Forms the basis of portability between tools.
Qwen.md: A thin agent-specific file containing only Qwen Code tool-specific features (using /clear, references via @file, commands via !). Must reference AGENTS.md rather than duplicate general rules.
Skill.md and skill portability: Qwen Code skills format built on Markdown instructions with optional scripts. When migrating between agents, SKILL.md content is transferred with minimal edits to tool details, preserving the essence of the process.
Mcp (model context protocol): Protocol for connecting external tools and data sources to an agent. Configured in settings.json or via CLI. Each connected MCP server expands the agent's action surface — and therefore the surface of potential risks.
Acp (agent client protocol): Protocol for standard interaction between an agent and client/IDE. Allows replacing the interface while keeping the process in the repository. Version compatibility is critical: ACP v1/v2 mismatch broke Qwen Code integration with JetBrains in early 2026.
Github spec kit: External SDD framework formalizing the process: intent → specification → plan → tasks → implementation → verification. Not tied to a specific agent, serves as a reference for standardizing your own processes.
"New agent" check: A practical replaceability experiment: clearing history (/clear), simulating an agent without context, reading key files, and verifying the ability to correctly determine the next safe action without modifying files.
Important dates: 2026, beginning of year: JetBrains 2025.3+ switched to ACP v2 with prompt.turn format, causing incompatibility with Qwen Code which only supported v1
2026: Compatibility restored in PR #1521 of the qwen-code repository after issue #1502. Critical event for understanding the importance of version control for integration protocols
Practice exercises: Name: Creating a two-level contract system
Problem: Your project has accumulated mixed documentation: some rules in QWEN.md, some in README.md, some only in your head. Create a clean two-level system: universal AGENTS.md and thin QWEN.md. QWEN.md must contain no more than 8 lines and reference AGENTS.md via the "First read @AGENTS.md" construct.
Solution: 1. Analyze current QWEN.md and extract universal rules (do not implement features without spec, read mission/tech-stack/roadmap, branches by specs/YYYY-MM-DD-feature, npm test before merge, no secrets in repo). 2. Transfer universal rules to AGENTS.md with clear structure: heading, list of rules with markers. 3. Create new QWEN.md: line 1 — reference to AGENTS.md, lines 2-8 — only Qwen Code specifics (/clear between phases, @file for specs, ! for local commands). 4. Remove duplication. 5. Verify: launch qwen, give command "read @QWEN.md" and ensure the agent correctly resolves @AGENTS.md.
Complexity: intermediate
Name: Skill portability audit
Problem: You have a feature specification skill in .qwen/skills/feature-spec/SKILL.md. Conduct an audit: find all ties to the Qwen Code interface (mentions of /clear, @file, !, qwen-specific commands) and determine which can be generalized and which must remain in the agent-specific layer.
Solution: 1. Read SKILL.md and identify every tool detail. 2. Classify: (a) process essence — find phase in roadmap, ask boundaries, decisions, context, create requirements/plan/validation — this remains; (b) invocation method — /clear, @file, ! — this is agent-specific. 3. Restructure SKILL.md: "Process" section without ties, "Tool Details for Qwen Code" section with note "adapt when transferring to target agent". 4. Create test transfer: copy SKILL.md to conditional .cursor/skills/ directory and describe what changes for Cursor (Cmd+K instead of /clear, @ for context instead of @file).
Complexity: intermediate
Name: MCP connection risk assessment
Problem: Your team wants to connect three MCP servers: (1) local project documentation server via stdio, (2) external HTTP code analytics server, (3) third-party MCP from an unverified repository "for convenience". Conduct a risk assessment and form a recommendation.
Solution: 1. Analyze each server by criteria: necessity, source trustworthiness, action surface, auditability. 2. Server 1 (local stdio, node ./tools/mcp-server.js): high trust, limited surface, necessary for project documentation — recommend with 15000ms timeout. 3. Server 2 (external HTTP): check authentication, HTTPS, limit scope, consider VPN/IP whitelist — recommend conditionally with caveats. 4. Server 3 (unverified third-party): reject, arguing with the principle "don't connect MCP just in case" — each tool expands the agent's action surface, and therefore the surface of potential errors and threats. 5. Document the decision as an entry in AGENTS.md: MCP evaluation rule and list of approved servers.
Complexity: intermediate
Name: "New agent" check in action
Problem: Conduct a full replaceability verification cycle for your project. Simulate a situation where a developer went on vacation and a new team member (or different agent) must continue work without personal contact.
Solution: 1. Execute /clear in Qwen Code to reset context. 2. Formulate prompt: "Imagine you are a new agent without chat history. Read @AGENTS.md, @QWEN.md, @specs/mission.md, @specs/tech-stack.md, and @specs/roadmap.md. Tell me what the next safe action in the project is. Do not modify files." 3. Record the agent's response. 4. Check correctness: compare with your understanding of priorities — it should identify the active roadmap phase, find an incomplete specification, suggest reading the corresponding requirements.md. 5. If the response is incorrect — identify the documentation gap (insufficient roadmap details? no explicit priorities? AGENTS.md doesn't describe the process for determining "next action"?). 6. Fix and repeat until stable success.
Complexity: intermediate
Name: ACP integration diagnostics
Problem: Qwen Code integration with JetBrains suddenly stopped working after IDE update. Using knowledge of ACP versioning, conduct diagnostics and form a recovery plan.
Solution: 1. First diagnostic step — check versions: qwen --version and JetBrains IDE version (Help → About). 2. Compare with historical context: JetBrains 2025.3+ use ACP v2 (prompt.turn), older Qwen Code versions only supported v1 — issue #1502. 3. If Qwen Code version predates PR #1521 (2026) — update to current version. 4. If versions are compatible — check agent_servers configuration in IDE settings: correct path, --acp argument, environment variables. 5. Check logs: in IDE (Help → Show Log in Explorer/Finder) and in qwen --acp --verbose output. 6. Form plan: (a) update agent, (b) rollback IDE, (c) temporary CLI mode usage, (d) wait for patch. 7. Document the incident in project documentation for future replaceability.
Complexity: advanced
Case studies: Name: Startup migration from Qwen Code to Claude Code without context loss
Scenario: A technology startup of 12 people used Qwen Code CLI for 8 months to develop a SaaS platform. Project structure included specs/, SKILL.md for feature specification, QWEN.md with detailed instructions. The team needed to switch to Claude Code due to better integration with their CI/CD and enterprise security requirements.
Challenge: Main problem: QWEN.md contained 200+ lines, mixing universal SDD rules with deep ties to the Qwen Code interface (/clear, @file, !, specific workflows). New developers accustomed to Claude Code were lost in inapplicable instructions. Skills in .qwen/skills/ contained direct references to qwen-specific commands. Project memory was effectively embedded in the "language" of one tool rather than the repository structure.
Solution: The team conducted a two-week audit using the agent replaceability methodology: 1) Extracted universal rules from QWEN.md into new AGENTS.md — specification process, mandatory checks, branch structure. 2) Reduced QWEN.md to a 6-line reference file. 3) Created CLAUDE.md with similar structure for Claude Code (Cmd+Enter instead of /clear, contextual mentions instead of @file). 4) Restructured all SKILL.md: "Process" section (portable) and "Tool Details" section (agent-specific). 5) Conducted "new agent" check for both tools — verified that Claude Code correctly determines next steps from AGENTS.md + specs/.
Result: Migration took 2 weeks preparation + 3 days team switchover. Project memory fully preserved. New developers onboarded in 1-2 days instead of previous 1-2 weeks. After 3 months the team experimented with Cursor for frontend development using the same AGENTS.md — adaptation time reduced to several hours.
Lessons learned: Early investment in AGENTS.md pays off exponentially when switching tools — it's insurance, not overhead
Skills must explicitly separate process essence and tool details; otherwise each migration requires re-engineering
"New agent" check should be a regular routine, not a one-time exercise — it reveals "degradation" of documentation during development
Multi-agent environment (different tools for different tasks) is becoming reality; architecture must anticipate this
Related concepts: AGENTS.md and QWEN.md
SKILL.md skill portability
"New agent" check
Agent-independent artifacts
Name: MCP server incident: when "convenience" became a threat
Scenario: A team of 5 developers connected an MCP server for automatic API documentation generation from an external service. The server required access to the internal network and had broad repository read permissions "for context analysis". After 2 months a leak was discovered: the server was logging code fragments to a third-party analytics server.
Challenge: The problem was in the fundamental approach: MCP was added "just in case" without risk surface assessment. Configuration in settings.json was not documented in AGENTS.md. When the first developer who set up MCP left, knowledge about its existence and risks was lost. New team members didn't understand why the agent had access to the internal network.
Solution: After the incident the team implemented strict MCP policy: 1) Each MCP requires an entry in AGENTS.md with necessity justification, action surface description, and risks. 2) Local MCP via stdio preferred over external HTTP. 3) External MCP requires security audit and IP/VPN restriction. 4) Regular review: quarterly check of all MCPs for relevance. 5) Removed unused documentation server; replaced with local script generating Markdown in repository without external calls.
Result: The incident didn't lead to production compromise but cost 2 weeks of audit and policy review. The new system prevented 3 similar "convenient" connections in the following 6 months. The team realized that agent replaceability includes replaceability/removability of its tools without process loss.
Lessons learned: The principle "don't connect MCP just in case" has a concrete violation cost — each tool expands the agent's action surface and potential attack surface
Undocumented integrations are an anti-pattern of replaceability; they create hidden dependencies that "kill" project memory when people or tools change
Local alternatives (scripts, Markdown generation) are often preferable to external services if the goal is long-term replaceability
Regular review of integrations should be part of the process, not a reaction to incidents
Related concepts: MCP as external tool layer
MCP security rule
Agent-independent artifacts
AGENTS.md as contract
Name: ACP v1/v2 compatibility: lesson from JetBrains integration
Scenario: An enterprise team of 20 developers used Qwen Code through ACP integration with JetBrains IDE (IntelliJ IDEA, PyCharm). In early 2026 after a planned IDE update to version 2025.3 the integration stopped working: agent wouldn't connect, commands wouldn't execute, logs showed protocol errors.
Challenge: Diagnosis was complicated by lack of explicit ACP versioning documentation in project artifacts. The team didn't know it was using ACP v1 while the new IDE required v2 with prompt.turn format. Finding a solution took 3 days of downtime: reading GitHub issues, analyzing PRs, experimenting with IDE downgrade and various qwen flags. Knowledge about the incompatibility wasn't captured in project documentation, so it repeated for every workstation update.
Solution: After restoring compatibility through Qwen Code update (PR #1521) the team: 1) Added an "Integrations and Protocols" section to AGENTS.md with explicit ACP, MCP, and other protocol version specifications. 2) Created environment check script (check-env.sh) outputting agent, IDE, protocol versions and compatibility flags. 3) Set up monitoring of qwen-code repository issues for critical protocol changes. 4) Documented rollback procedure: temporary switch to CLI mode upon IDE incompatibility.
Result: The next JetBrains update (2026.2) required adaptation, but the team responded in 2 hours instead of 3 days. Environment check became part of new developer onboarding. The "process in repository, interface replaceable" architecture got concrete embodiment: when ACP broke, the team switched to CLI without losing productivity.
Lessons learned: Protocol version matching is a critical but often ignored component of replaceability; it must be explicitly documented
IDE integration dependency creates a single point of failure; CLI mode as fallback is a mandatory strategy
Monitoring upstream protocol changes should be part of DevOps process, not ad-hoc activity
Environment check ("health check") is a practical tool for ensuring replaceability: it makes hidden dependencies visible
Related concepts: ACP and IDE
Protocol version compatibility
"New agent" check
Process in repository, interface replaceable
Study tips: Start practice with your own project: take your current repository and conduct a replaceability audit using the checklist from practical assignments — theory sinks deeper through personal context
Use the "parallel agent" method: work with one tool for a week, recording all implicit dependencies in notes, then try to repeat the task with another agent using your AGENTS.md — the gap will show real documentation gaps
Create templates, not ready files: prepare boilerplate AGENTS.md, QWEN.md, SKILL.md for quick start of new projects — this turns replaceability from effort into habit
Keep a "replaceability incident journal": record every case where changing agent, IDE, or developer caused friction — over 3-6 months patterns will reveal systemic problems in documentation architecture
Study GitHub Spec Kit as a benchmark: even if not implementing, compare your .qwen/skills/feature-spec with their process — this calibrates understanding of "mature" replaceability
Practice "black box": ask a colleague unfamiliar with the project to read only AGENTS.md + specs/ and describe what they would do next — external perspective reveals what's "obvious" to you but not to others
Document failures: when "new agent" check gives incorrect result, don't fix immediately — first record what exactly went wrong, this teaches recognizing problem categories
Additional resources: qwen-code repository and issue #1502/#1521: https://github.com/QwenLM/qwen-code/issues/1502 — primary source of the ACP v1/v2 incident, essential for understanding real protocol dynamics
Github spec kit: https://github.com/github/spec-kit — external SDD framework for comparing with your own processes, study the intent→specification→plan→tasks→implementation→verification structure
Mcp (model context protocol) documentation: https://modelcontextprotocol.io — protocol specification, server examples, security best practices
Acp specification: Internal JetBrains and Qwen Code documentation on Agent Client Protocol — track changelogs for version control
agents.md starter template: Create your own based on the course example, adapt to team stack and publish as internal template
Open source project skill.md catalog: Analyze .qwen/skills/ in public repositories using Qwen Code to collect portability patterns
Markdown static analysis tools: markdownlint, vale — for maintaining quality and consistency of project documentation, critical for understanding by any agent
Summary: Agent replaceability is not a technical luxury but a necessity in a world of rapidly evolving AI tools. Key principles: process lives in repository, agent is a replaceable execution environment. Practical pillars: AGENTS.md as universal contract, thin agent-specific files (QWEN.md, CLAUDE.md), portable skills with explicit separation of essence and tool details, justified MCP usage with documented risks, understanding protocol versioning (ACP), regular "new agent" checks. Successful replaceability is measured not by the number of supported tools, but by the speed and completeness of transferring project memory between any agents and people without context loss.