Designing More Reliable Programming Tools for AI Agents

The Complexity Trap in Agentic Programming

Over the last few months, the artificial intelligence ecosystem has made giant leaps forward. However, when working with agents like Claude Code or Cursor, it is common to observe a recurring failure pattern: the agent performs three steps correctly, gets lost on the fourth, and ends up exhausting its context window with useless log files. The solution does not lie in making the model smarter, but in changing our philosophy of skill design.

As we explored in The Rebirth of Technology: ESP32, Open Source and the Charm of the Unfinished, the key lies in the robustness of the tools we put into the hands of the AI.

Limit the Tool, Not the Agent

A common mistake is to add restrictive rules to the prompt in an attempt to control the model. The winning strategy is to restrict the tool. By turning each task into a deterministic script, we delegate complex logic to tested code, allowing the agent to focus solely on reasoning about intent and sequence.

Architecture of a Reliable Workflow

For a programming agent to work predictably, we must structure its capabilities under a clear contract:

• Modular Scripts: Each step is an independent script (e.g., step_01_convert.py) with a defined input and output interface.
• Structured Outputs: Using JSON allows any model, even a basic one, to process results without ambiguity.
• Context Management: Instead of saturating the agent's memory with large blocks of text, we use temporary files on disk (artifacts). The agent only handles the file path.

"Do not make the agent smarter. Make its tools more predictable. Let the agent reason about intent and let deterministic scripts perform the action."

The Importance of Explicit Errors

A professional system must be able to "fail loudly." Instead of generic messages, each script should return specific exit codes that indicate the next logical step to the agent. For example:

1. Code 0: Success, continue to the next step.
2. Code 1: Conversion error, check input.
3. Code 2: Authentication error, verify credentials.

This level of detail allows the agent to perform self-correction without the need for constant human intervention, something vital in modern software development and in the security of open source projects, where bot management is increasingly critical, as we have seen in cases like Botnet Targeting Open Source Developers Taken Down.

Security and Persistence

Finally, secret management must be external to the agent's context. Using .env files loaded directly by the scripts ensures that credentials are never exposed in the model's memory. Likewise, maintaining a work-log with timestamps allows for the auditing of every action, creating a long-term memory that the agent can consult in future executions.

In conclusion, when the workflow is linear and requires precise results, a script-based structure beats any attempt at improvisation by the model. The true power of javascript or Python agents does not lie in the model itself, but in the quality of the infrastructure we build around it.