A coding-agent guide says bad context and weak checks cause most failures

The two failures that keep recurring

As dev.to reported, a new practical guide on AI coding agents boils the subject down to one idea: an agent is only as good as the context it receives and the verification it is held to. It then names two failures that show up again and again in real work.

The first is under-context. When an agent does not know what an interface really looks like, it does not stop and ask. It guesses, and it may invent fields that do not exist. The second is over-trust. The agent reports it is finished after a clean run on the developer's own machine, even though nobody exercised the real flow a customer would use.

Our editors see this as useful framing rather than news. It is a guide, not a release or an announcement. But the framing is clear enough to take away.

Give the agent the contract, not a pile of docs

The guide is blunt about a common habit: pasting a command or a dump of documentation into the chat. It calls this a lossy way to inform an agent. Details get dropped, and the agent fills the gaps with plausible-sounding inventions.

The better design, it says, is to connect the agent to the real contract through tools. The contract here is the written description of what an API accepts and returns, often kept in a format called OpenAPI. The tool link is an MCP server. MCP, the Model Context Protocol, is a standard way to give an AI assistant access to tools and data. With that link in place, the agent calls documented operations instead of working from memory.

The guide adds two related points. If the contract is unknown, it is better for the agent to say so than to make one up. And when you need structured data back from a model, enforce its shape with a schema rather than parsing free-form text.

Designing for machines as well as people

One short section makes a point that is easy to miss. An interface that is pleasant for a human developer is not automatically easy for an agent. According to the guide, agents need operations they can discover, errors that are clearly typed, and identifiers that stay stable.

That is a request to the people who build services, not only to those who use agents. If your team exposes an API internally, the guide suggests that agent-friendliness is now a design goal worth planning for.

What 'done' should actually mean

The most quotable idea is that an agent's 'done' is a claim, not evidence. The guide wants it replaced by something checkable: a command anyone can run that passes in CI. CI, short for continuous integration, is the automated check that runs on shared infrastructure rather than on one person's laptop.

It also warns against shallow proof. A response code that says the request worked is not enough, and the guide argues the agent should run the actual business scenario. A green build after an AI-driven refactor, meaning a cleanup of existing code, can also miss things.

In its FAQ, the guide sets a minimum bar. Run the relevant tests and the real business flow in CI, and confirm the change fails without the fix. A test that cannot fail proves nothing.

A checklist of agent mistakes

The guide lists habits that autonomous agents repeat, and says each comes from a real case. Reviewers can scan for them:

• Unit tests pass, but the app is never actually run.
• Everything is green locally but red in CI.
• A type error is silenced with as any, or new types are mostly any.
• A broad try-catch block hides failures.
• A handoff keeps the decision but loses the reason for it.
• A rename misses a place where the name appears as plain text.
• Development servers are left running after the work is called finished.

Another item covers changing tools without reintroducing the API. Teams move between coding agents and editors as the market shifts, and the guide says to keep the contract stable across moves rather than rebuilding the connection each time.

Read it with the sales pitch in mind

The guide closes by pointing to Powerduck, which it describes as a local-first, OpenAPI-first workspace covering debugging, testing, mocking and agent tools. That is the guide's own product, so the advice and the pitch are intertwined.

The core ideas do not depend on that product. Autonomy should scale with how fast you can verify results. A person should stay on decisions that change the contract or touch money and sign-in security. Those are habits, not purchases.