Known Limitations & Usage Boundaries

AI Agents can significantly improve development efficiency, but they are still limited by model capability, context, tools, workspace, network, and execution budget. Documentation should state these boundaries proactively, to avoid mistaking flow completion for reliable results.

Large Repositories

A large repository may exceed the model's context or retrieval capability. An Agent may see only some of the files, miss cross-module dependencies, or make wrong judgments based on a summary.

Recommendations:

• Define the task scope clearly;
• Provide entry files and relevant modules;
• Generate a repository-structure summary first;
• Execute and accept in stages;
• Run the full test suite for cross-module changes.

Unstable Structured Output

Different models follow JSON, Tool Calling, and schemas to different degrees. With thinking mode enabled, some models may return only reasoning_content and no parseable final content.

Handle such issues through model configuration, strict validation, and limited retries — don't treat reasoning text directly as the result.

Multi-Agent Conflicts

When multiple Agents modify the same file at the same time, you may get overwrites, duplicate implementations, conflict merges, or tests running against the wrong version.

Before using a Swarm, define the workspace mode, branch strategy, merge owner, and final test target.

Long Tasks & Recovery

Long tasks may be interrupted by model timeouts, network drops, service restarts, Sandbox reclamation, or queue anomalies. Whether the system can recover from an intermediate state depends on the current version and deployment configuration.

For critical tasks, keep staged commits, state snapshots, and repeatable verification commands.

Local vs. Cloud Differences

The same task may produce different results in local and cloud environments. Common causes include:

• Operating-system and architecture differences;
• Different dependency versions;
• Different network-access policies;
• Inconsistent environment variables and secrets;
• File-permission and path differences;
• Docker, VM, or Sandbox restrictions.

MCP Compatibility

An MCP Server can connect successfully, yet a specific tool may still fail due to protocol version, schema, authentication, response size, or transport method.

When integrating a third-party MCP, verify tools one by one rather than only checking that the server is online.

Test Trustworthiness

An Agent may misread test output, ignore skipped items, treat an environment failure as a code failure, or report a command that never ran as passing.

Final acceptance should check the real command, working directory, exit code, and test statistics.

Permissions & Security

The more file, shell, network, and credential permissions an Agent holds, the larger its potential blast radius. Skipping approval does not improve result accuracy — it only removes manual blocking.

High-risk permissions should be enabled only temporarily, in an isolated environment.

Cost Is Not Fully Predictable

Task cost is affected by context length, the number of Agents, model choice, tool calls, the number of retries, and execution-environment runtime. Complex tasks may significantly exceed the initial estimate.

Set limits on tokens, time, concurrency, retries, and cloud resources.

Results Require Manual Review

The following tasks should not rely on an Agent completing them automatically:

• Production database schema changes;
• Changes to authentication, payment, and permission systems;
• Infrastructure deletion or large-scale migration;
• Changes to secrets, certificates, and security policies;
• Legal, compliance, and privacy conclusions;
• Release tasks that cannot be verified in the target environment.

Current Documentation Boundary

This document describes general risks and recommendations; it does not mean that every feature is already implemented in the current Heicode version. For exact support, rely on the current version, deployment method, UI, and release notes.