Your AI Coding Setup is a Complicated Tool. Your Codebase is Complex.
New AI coding tools promise to make agents more reliable. You see frameworks for skills, superpowers, and spec-driven development. These tools work. They help agents follow a process instead of guessing.
But there is a trap. People think a better setup for one task creates a coherent system. It does not.
To understand why, use the Cynefin framework. It separates problems into two types: Complicated and Complex.
Complicated Problems These have a knowable answer. You use analysis and skill to find it. Examples include refactoring a module or writing a validation function. Once you find the answer, you can repeat it. Most AI coding tools live here. They focus on the unit of work. They make tasks repeatable and verifiable.
Complex Problems These do not have a predictable answer. The system is a web of parts. Outcomes only appear after you act. Will forty merged changes break the architecture in six months? Will Agent A contradict Agent B? You cannot find these answers by looking at one file. They emerge from how parts interact.
The mismatch happens when you expect Complicated tools to solve Complex problems.
A tool might make an agent write a perfect function. But if one task uses userId and another uses user_id, the system breaks. Both tasks were "correct" in isolation. The failure is emergent. It lives in the interaction, not the unit.
Even massive context windows cannot solve this. A larger window helps you see more, but seeing is not the same as deducing. You can read an entire codebase and still not know if it will deadlock under production load. That is a runtime property.
How to handle both:
- For the Complicated layer: Use skills, specs, and TDD. These make the agent's individual output rigorous.
- For the Complex layer: Use probe-sense-respond. You cannot predict what will break. You must merge, deploy, and observe. Use integration tests and observability to sense what happens when pieces combine.
Do not fall for the promise that a better spec makes your system stable. Specs make the unit reliable. They do not make the system coherent.
Match your method to the domain. Use tools to perfect the unit. Use experimentation to understand the system.
Optional learning community: https://t.me/GyaanSetuAi