Let’s be honest: the first time you used an AI coding agent, you thought it was magic. Then you saw the code it produced and reconsidered your definition of “magic.” Black magic, perhaps.

But wait — before you throw everything out and go back to writing everything by hand, there’s a secret that changes everything. And no, it’s not some super-secret prompt copied from a shady Reddit forum. It’s something more subtle, and once you understand it, your relationship with coding agents will change forever.

The Coding Agent Is Not a Worker — It’s a Blind Sculptor

Think of a coding agent as a sculptor working at the speed of light. It can make thousands of “chisel strikes” per second on the marble block of your code. Impressive, right?

The problem is that if this sculptor is blind — meaning it can’t see the outcome of each strike — it ends up crumbling the marble instead of creating a statue. And that’s where things fall apart.

The real secret to making a coding agent work well is simple to say and a bit harder to do: make sure its attempts are always informed by results. AI has legendary persistence — it will retry endlessly without getting tired — but if it doesn’t “see” what went wrong in the previous attempt, that persistence becomes nothing but chaotic noise.

Clear on the “What”, Flexible on the “How”

Here’s the first golden rule, the one that separates those who get decent code from those who get masterpieces:

Be extremely precise about what you want to achieve. Be flexible about how to achieve it.

This sounds almost philosophical, but it’s very practical. When you write a prompt to a coding agent, you have two distinct parts to manage:

1. The specification (the “what”): No room for ambiguity here. The model needs to know exactly what the expected outcome is. Without clarity, the AI’s attempts will be crude and inconclusive — like trying to describe a color to someone with their eyes closed.

2. Design intuitions (the “how”): Here you can and should use non-binding language. Share your idea on how to solve the problem, but present it as a suggestion, not a hard order. Something like: “you might consider a dictionary-based approach for the lookup” instead of “use a dictionary, period”.

Why this distinction? Because your intuitions, however good, might not be the most efficient approach. If you force the AI to follow them to the letter, you strip it of its ability to find a better path. And it, with its speed, might find that better path in three seconds.

Chain of Thoughts: Your Gift to the AI

When you prepare a prompt for a coding agent, you’re essentially building an external chain of thoughts for it. It’s like leaving a map for an explorer instead of giving them a GPS that shouts commands every ten seconds.

This map must be:

• Curated: no walls of text, no useless details. Every word must earn its place.
• Concise: the less noise there is, the better the model can navigate the “semantic space” of the problem.
• Non-binding: suggest a direction, not a mandatory route with guardrails.

Done well, this approach allows the AI to “navigate” the problem intelligently, discarding your intuitions if they prove wrong during testing, and embracing them if they work. It’s AI working for you, not despite you.

The Clean Codebase: The Foundation Everything Rests On

OK, the prompt matters. But there’s something even more fundamental that most people ignore completely: the quality of the codebase the coding agent works on.

Imagine a perfect sphere. If the initial core of the code is solid, clean, well-structured, every new piece the AI adds slots in organically — the sphere grows while maintaining its harmonious shape. But if the core is irregular, unbalanced, full of unnecessary dependencies? Every addition the AI makes will inherit those flaws, and the “sphere” will become increasingly deformed.

The three golden rules for an AI-friendly codebase are:

1. Minimalism: less code, the better. Every line must have a reason to exist.

2. Sparse dependencies: every external library is an added complexity point. The model struggles to navigate intricate environments, and your prompts will have to compensate for this extra effort. Fewer dependencies = less “noise” = more effective AI.

3. Comments on fundamental tensions: this is the masterstroke that few people use. Don’t comment on what the code does — comment on why you made certain choices and what trade-offs you’re managing.

Commenting on Tensions: The Hidden Superpower

What does it mean to comment on “fundamental tensions”? It means leaving context breadcrumbs that explain the deep logic of the system. A few practical examples:

// Fundamental tension: we use a dictionary instead of a list to optimize
// lookup speed, accepting higher memory consumption.
// Do not modify this structure without re-evaluating performance.

# Design choice: validation happens at ingress, not during processing.
# This keeps internal code simple. Respect this pattern in every addition.

// Intentionally avoided dependency: this function doesn't use external libraries
// to keep the bundle lightweight. Implement any additions natively.

These comments do something magical: they remove the blindfold from the sculptor’s eyes. When the AI re-reads the code to modify or extend it, it doesn’t act blindly — it has a clear view of where it can and cannot go, and why. Its attempts become targeted instead of random.

And when an attempt fails the tests? The AI has all the information to understand why and retry in the right direction. This is the virtuous cycle that transforms a mediocre coding agent into an extraordinary tool.

Forcing AI to Document Like You

Once you’ve established this standard in your core code, you can (and should) force the AI to respect and continue it. How? In two ways:

In the prompt: explicitly include the requirement to document fundamental tensions as a non-negotiable requirement. Something like: “Every function must include a comment explaining the architectural choices and trade-offs managed.”

By example: if the existing code already follows this standard, the AI will naturally imitate it to maintain consistency. “Leading by example” works with machines too.

Create Your Personal Agent: The System Prompt That Changes Everything

So far we’ve talked about how to write better individual prompts. But if you use a modern IDE that supports AI agents, you can take a further leap in quality: create a custom agent with a fixed system prompt that applies all these rules automatically, every time, without you having to rewrite them from scratch.

You’re no longer rewriting guidelines every time. You’re setting an operational standard.

It’s not a universal law — it needs to be adapted to the context and type of project — but it works like an architectural guardrail: it maintains consistency, reduces ambiguity and drastically lowers the probability of structural errors.

Tools like Cursor, TRAE, GitHub Copilot (in recent versions with agent support), Zed with its AI extensions, and JetBrains AI Assistant let you configure an agent with permanent instructions that act as the “character” of your assistant. In practice, it’s like hiring a collaborator and giving them the company manual on day one — from that point on, they already know how to behave without you having to repeat it every time.

Here’s a concrete example of a system prompt you can use as a base for your agent:

# CORE RULES
- SOLID principles are mandatory
- Context-appropriate design patterns
- Minimal, clean, production-grade code
- Generate only necessary code (no future technical debt)

# ARCHITECTURE
- Docker-only environment (no local dependencies)
- Strict separation of concerns (Domain / Application / Infrastructure)
- Prefer Hexagonal / Clean Architecture
- No business logic in controllers
- Interface-based design for every component
- Dependency Injection everywhere
- Zero hardcoded values
- Configuration exclusively in external YAML/JSON files

# CONFIGURATION
- No configuration inside application logic
- No duplicated configuration
- All parameters injected from external files
- No default parameters in application code

# ERROR HANDLING
- Fail-fast approach (explicit errors > silent failures)
- No complex or nested fallback logic
- No generic try-catch blocks
- Context-specific error handling only
- Structured logging (JSON-friendly, compatible with Loki/ELK)

# CODE QUALITY
- No magic numbers
- No magic strings
- No hidden side effects

- Each function must include a brief comment explaining:
  - Architectural choice
  - Trade-offs handled
  - Fundamental tension addressed (e.g. performance vs memory,
    simplicity vs flexibility, isolation vs reuse)

- Comments must explain WHY a decision was made
- When a structural constraint exists, explicitly document what must NOT be changed
  without revisiting architectural assumptions

# TESTABILITY
- Testability-first design
- Every component must be testable in isolation
- No logic without testability
- Clear boundaries to enable unit and integration testing

Note: this is not a wish list — it’s an operational contract. The agent reads it before every response and uses it as an architectural compass. It’s not “trying to write good code”: it’s respecting precise structural constraints.

The result? You stop receiving code that “works now but in six months nobody understands anymore” and start receiving code with layer separation, external configuration, explicit errors and zero hidden magic. In other words: code that can grow without collapsing on itself.

The most powerful part isn’t a single rule, but the whole: fail-fast, zero hardcoded values, testability-first and mandatory architectural comments. When you require every function to explain the choices made and the trade-offs managed, the agent doesn’t just generate code — it generates the decision context too. This means less ambiguity in future iterations and fewer “why was this done this way?” questions in code reviews.

You’re transforming AI from a snippet generator into a disciplined technical collaborator.

A few minutes of configuration today saves you hours of refactoring tomorrow — and above all avoids invisible technical debt that explodes when the project grows.

The Competitive Advantage of AI: Actually Using It

To summarize, AI has two superpowers compared to any human programmer:

• Speed: tests solutions in seconds, not hours.
• Persistence: never gets tired, never gets demoralized, never goes for coffee right when you’re about to find the bug.

But these superpowers are worth zero if the agent is blind. Every attempt not informed by results is wasted energy. Every overly rigid prompt is a leash that strangles the machine’s creativity.

Your job, as a coding agent tamer, is simple in theory and refined in practice: create the conditions for AI to use its speed to make targeted attempts. Clean codebase, prompt clear on the result, flexible suggestions on the method, comments that illuminate the system’s logic.

Do all this, and your coding agent stops being a blind sculptor crumbling marble. It becomes your most precise chisel.

And you? Have you started commenting on the fundamental tensions in your code yet? If the answer is no, well… at least now you know what to do this weekend instead of watching another series on Netflix. You’re welcome.