Skip to main content

Common issues and how to solve them

Agent works unstably, doesn't complete the task​

This is a general problem that can depend on many parameters. Try the following solutions:

  • Break down the task into subtasks:
    1. Switch to Plan mode and provide your task for decomposition into subtasks
    2. Create a new chat
    3. Ask the agent in Agent mode to solve subtasks based on the obtained PLAN.md
  • Feedback loop: explicitly describe the stop criteria to the agent
    • For example, "do until all tests from the e2e folder pass"
    • To prevent the agent from "hacking" the stop criteria (not adjusting tests to fit their code), you can prevent them from changing certain files by adding them to .writeignore
  • Add a new rule, for example, "Always check your solution by running project compilation"
  • If you're working with frontend (writing or testing it), connect Chrome MCP or PlayWright MCP in the MCP menu of the plugin, the agent will be able to "see" the resulting UI and work better

Agent invents things that don't exist in the project (hallucinates)​

Explicitly point the agent to files they should look at via @file or #file

Agent gets confused in the project​

Create AGENTS.md: in a new chat, call #workflow:init.md

Agent switched to a previous cancelled task and started making edits​

Start a new task in a new chat: to do this, click + New Chat in the top right corner of the chat

Agent is too proactive, overengineers, or does things you didn't ask for​

Create a new rule as described here, and write in it:

Don't be proactive, don't overengineer, i.e. don't do things you weren't explicitly asked to do, for example, don't write additional tests when you're asked to write only code

Agent generates too many comments in the code​

Create a new rule as described here, and write in it:

Don't write comments unless you're directly asked to

Plugin stops with an error like "This model's maximum context length is X"​

  • Update the plugin to a version at least 5.4.0
  • Manually trigger chat compression, check the box so it's triggered automatically in the future

Agent cannot read data from my knowledge base​

To extend the agent's capabilities, connect MCP servers and select the needed integrations.

It's unclear how to use the plugin​

To show colleagues the main steps, use Onboarding and complete the introductory scenario.

The agent performs poorly on a specific task​

To describe an approach once and reuse it, create a Skill with step-by-step instructions.

I asked to edit only one file, but the agent edited others​

To focus edits, configure Edit Scope and leave only the files you need.

It is hard to review generated code all the time​

To automatically find issues in generated code, run Auto Review and apply the recommendations.

It's unclear how to change a small code fragment in the editor​

To quickly insert code without rewriting the file, use inline code generation.

It's unclear how to connect agent work with tasks in a TMS​

To pull tasks and statuses, connect TMS systems support.

The agent cannot write unit tests​

If the agent cannot write unit tests, your code may be too complex for that. In that case, you can generate unit tests from e2e tests, as described here.

Test coverage is low​

To close uncovered branches, enable Increase Test Coverage and set a goal.

Tests are flaky and fail intermittently​

To find the source of flaky tests, run flaky test analysis.

It's unclear how to find information on the internet or verify an external source​

To let the agent search the internet and read websites, enable Web search & Web fetch.

What's the difference between Rules, Skills, Workflows, Agent modes, AGENTS.md​

EntityPurposeNotesExample
AGENTS.mdProject contextApplied to all chats in the project."Project context"
RulesGlobal behavior settingsApplied to all user chats."Write briefly"
SkillsInstructions for specific tasksUsed by agents"Generate tests"
WorkflowsInstructions for specific tasksWill be replaced by Skills."Generate tests"
AgentsDomain specialistsSet of tools and available Skills for a specific role."Tech writer"