DEV Community

Rodrigo Oliveira
Rodrigo Oliveira

Posted on

The AI Productivity Paradox: Fighting LLM Over-Engineering with Decision Ladders, Deterministic Debt Ledgers, and YAGNI Semantic Sensors in Go

#go #ai #architecture #opensource

There is a quiet paradox inside engineering teams that have adopted AI coding agents at scale: we have never generated so many lines of code per minute, and at the same time, we have never accumulated so much accidental complexity so fast.

Ask a frontier LLM to implement a simple persistence layer for financial wallets in Go. Without strict architectural guardrails, in less than thirty seconds it will likely hand you:

  • A WalletRepository interface with a single concrete implementation in the producer package (violating the classic Go idiom where interfaces belong to the consumer);
  • An AbstractStorageFactory with a Strategy pattern for a database that will never change;
  • Three hallucinated domain structs (CreditCard, VoucherBalance, WeeklyEnvelope) that were already unified inside a single domain.Wallet entity;
  • A custom wrapper around database/sql and half a dozen vague // TODO: optimize later comments scattered along the way.

Does it compile? Sometimes not even that — when it hallucinates types that don't match your domain package. And when it does compile, you have just inherited 800 lines of speculative over-engineering to solve a 120-line problem.

In this 5th technical article on the architecture of Pipeline-AI — celebrating the release of version v0.11.0 (deliveries DEL-032 through DEL-035) —, I share how we attacked the root cause of LLM additive bias by combining Decision Ladders in the cognitive workflow, a deterministic Debt Ledger in pure Go 1.24 (internal/debt), and a Calibrated YAGNI Semantic Sensor (pipeline-ai eval -preset yagni), along with a real-world production case study from the gestao-financas project.

1. Why Do LLMs Suffer from Chronic Additive Bias?

Large Language Models are trained on billions of lines of public repositories and enterprise tutorials where "clean architecture" is frequently conflated with excessive layers of indirection. Furthermore, Reinforcement Learning from Human Feedback (RLHF) tends to reward long, elaborate, and seemingly sophisticated answers.

In day-to-day software engineering, this manifests as four recurring pathologies:

  1. Premature Abstraction (YAGNI Violation): Creating generic interfaces, event buses, and configuration options for hypothetical future requirements nobody asked for.
  2. Domain Type Duplication & Hallucination: Instead of inspecting existing structs in internal/domain, the agent invents parallel local structs that fragment the system's domain model.
  3. Reimplementing the Standard Library: In Go, where the standard library (net/http, database/sql, encoding/json, context, io) solves 90% of infrastructure needs, LLMs insist on building wrappers or pulling unnecessary dependencies into go.mod.
  4. Invisible Technical Debt (Orphaned TODOs): When an agent takes a legitimate engineering shortcut (such as an in-memory map or JSONB column serialization), it leaves a vague // TODO: fix later — or no comment at all — without documenting what the operational limit of that shortcut is or what objective trigger requires upgrading it.

2. Architectural Inspiration & Evolution: From Prompt Rules (ponytail) to Deterministic Governance + System 1 (pipeline-ai v0.11.0)

Recently, the open-source project dietrichgebert/ponytail brilliantly distilled a philosophy every senior engineer knows by heart:

"The best code is the code you never wrote."

ponytail introduced three strong conceptual ideas to guide coding agents: a Decision Ladder, strict minimalism discipline, and structured inline shortcut comments.

However, when we analyzed this approach through the architectural lens of Pipeline-AI, we identified a structural limitation: rules that live solely inside prompt text (System 2) suffer from attention degradation (context drift). As the context window grows during a multi-step TDD session, the LLM simply forgets the prompt instruction or ignores the // shortcut: comments buried across source files.

To turn good prompt intentions into deterministic, auditable engineering, pipeline-ai v0.11.0 evolved these concepts across three new dimensions:

  • From Passive Prompt to Deterministic Go Parser & Scanner (internal/debt): // shortcut: comments are no longer dead text in your codebase. They are extracted, validated, and inventoried by a pure Go 1.24 engine (pipeline-ai debt), exposed via CLI, MCP server (pipeline_list_debt), and rendered automatically in the Generative UI Dashboard.
  • Blocking Vague TODOs While Auditing Deliberate Shortcuts: In Pipeline-AI, pipeline-validate already blocks orphaned TODO/FIXME markers. Now we cleanly separate forgotten tasks (blocked) from deliberate architectural shortcuts (tracked with explicit limits and upgrade triggers).
  • From Slow "LLM-as-a-Judge" to Calibrated System 1 Semantic Sensor (Jev): We built the native pipeline-ai eval -preset yagni preset, allowing agents and CI pipelines to pipe any git diff into a sub-100ms calibrated binary sensor (/v1/noul) to catch over-engineering before human code review.

3. The Three Anti-Overengineering Pillars in pipeline-ai v0.11.0

3.1. Pillar 1: The 5-Step Decision Ladder in Core Skills (architecture-guardrails, dev-implementation, code-reviewer)

Before writing a single line of code or proposing a new package, the architecture-guardrails skill now enforces an explicit walk through the 5-Step Decision Ladder:

  1. Step 1 — YAGNI (You Aren't Gonna Need It): Is this change strictly required for the current delivery scope, or are we designing for a hypothetical future? If speculative, cut it immediately.
  2. Step 2 — Internal Repo Reuse: Does a struct, function, or type already exist in internal/domain or another internal package? Never create mirrored structs or duplicate domain types.
  3. Step 3 — Go 1.24+ Standard Library: Does the Go standard library (net/http, database/sql, encoding/json, slices, maps, sync, context) already provide the primitive? Use it directly without wrappers.
  4. Step 4 — Existing go.mod Dependencies: If the stdlib doesn't cover it, can we solve it with an already approved dependency in go.mod?
  5. Step 5 — Minimal Viable New Code: Only when steps 1–4 are exhausted, write the smallest concrete code that passes the tests — without single-implementation interfaces in the producer package.

Next, dev-implementation enforces strict minimalism during coding, and code-reviewer audits the git diff specifically targeting speculative abstractions and unnecessary interfaces.

3.2. Pillar 2: The Deterministic Debt Ledger (internal/debt, pipeline-ai debt, and MCP pipeline_list_debt)

Minimalism does not mean pretending a simple implementation scales infinitely. When we consciously choose a simple design (e.g., an in-process mutex or JSONB column storage), we must record that deliberate shortcut with two mandatory fields:

  • What is the known operational limit of the current solution? (<limit>)
  • What is the objective, measurable trigger to upgrade it in the future? (<trigger>)

We standardized this annotation directly in Go comments:

// shortcut: <known limit> | upgrade: <objective upgrade trigger>
Enter fullscreen mode Exit fullscreen mode

To parse and audit these annotations across any Go repository without complex regular expressions (avoiding catastrophic backtracking / ReDoS risks), we built internal/debt in pure Go 1.24:

// internal/debt/debt.go
package debt

// ShortcutItem represents a deliberate engineering shortcut tracked by limit and upgrade trigger.
type ShortcutItem struct {
    File           string `json:"file"`
    Line           int    `json:"line"`
    Limit          string `json:"limit"`
    UpgradeTrigger string `json:"upgrade_trigger"`
    Raw            string `json:"raw"`
}

// ParseComment extracts the known limit and upgrade trigger from comments formatted as:
// "// shortcut: <limit> | upgrade: <trigger>" or "// shortcut: <limit>, <trigger>"
func ParseComment(line string) (limit string, trigger string, ok bool) {
    idx := strings.Index(line, "//")
    if idx == -1 {
        return "", "", false
    }

    comment := strings.TrimSpace(line[idx+2:])
    if len(comment) < len("shortcut:") || !strings.EqualFold(comment[:len("shortcut:")], "shortcut:") {
        return "", "", false
    }

    rest := strings.TrimSpace(comment[len("shortcut:"):])
    if pipeIdx := strings.Index(rest, "|"); pipeIdx != -1 {
        limit = strings.TrimSpace(rest[:pipeIdx])
        right := strings.TrimSpace(rest[pipeIdx+1:])
        if len(right) >= len("upgrade:") && strings.EqualFold(right[:len("upgrade:")], "upgrade:") {
            trigger = strings.TrimSpace(right[len("upgrade:"):])
        } else {
            trigger = right
        }
    } else if commaIdx := strings.Index(rest, ","); commaIdx != -1 {
        limit = strings.TrimSpace(rest[:commaIdx])
        right := strings.TrimSpace(rest[commaIdx+1:])
        if len(right) >= len("upgrade:") && strings.EqualFold(right[:len("upgrade:")], "upgrade:") {
            trigger = strings.TrimSpace(right[len("upgrade:"):])
        } else {
            trigger = right
        }
    } else {
        return "", "", false
    }

    if limit == "" || trigger == "" {
        return "", "", false
    }
    return limit, trigger, true
}
Enter fullscreen mode Exit fullscreen mode

The directory scanner debt.ScanDir(rootDir):

  • Walks the repository tree recursively via filepath.WalkDir;
  • Deterministically skips test files (*_test.go), hidden directories (.git, .agents), vendor, and node_modules;
  • Ignores plain // TODO: comments or incomplete // shortcut: lines missing an upgrade trigger;
  • Sorts items deterministically by File and Line and has been hardened with over 6.5 million native Fuzz Testing executions (FuzzParseComment) with zero panics.

Engineers and AI agents can inspect the Debt Ledger via CLI or MCP at any time:

$ pipeline-ai debt
Atalhos Deliberados (Debt Ledger): 2 encontrado(s)
- internal/storage/postgres.go:68 | Limite: serialização JSONB de recurrence e sub_items na coluna da carteira | Gatilho de evolução: extrair para tabelas relacionais se houver query analítica por sub-item
- internal/storage/storage.go:48 | Limite: MemoryStore guarda estado apenas em RAM com RWMutex local | Gatilho de evolução: usar PostgresStore quando DATABASE_URL estiver configurado em produção
Enter fullscreen mode Exit fullscreen mode

And pipeline-ai dashboard automatically renders the "Atalhos Deliberados (Debt Ledger)" section inside the Generative UI HTML cockpit alongside DORA and Jev telemetry.

3.3. Pillar 3: The YAGNI Semantic Preset in Jev (pipeline-ai eval -preset yagni)

In internal/sensor/semantic, we added ResolvePreset (yagni, with aliases minimalism and ponytail), which configures a calibrated binary evaluation (EvalNoul at /v1/noul) with our anti-overengineering audit prompt:

// internal/sensor/semantic/presets.go
const yagniQuestion = "Este código respeita estritamente o princípio YAGNI e minimalismo, sem overengineering, interfaces de implementação única desnecessárias, tipos duplicados do domínio ou abstrações especulativas não solicitadas?"

func ResolvePreset(name string) (mode string, question string, err error) {
    switch strings.ToLower(strings.TrimSpace(name)) {
    case "yagni", "minimalism", "ponytail":
        return "noul", yagniQuestion, nil
    default:
        return "", "", ErrInvalidPreset
    }
}
Enter fullscreen mode Exit fullscreen mode

Auditing a diff in CI or during an autonomous agent run is now a single one-liner:

git diff | pipeline-ai eval -preset yagni -threshold 0.80
Enter fullscreen mode Exit fullscreen mode

4. Production Case Study: The internal/storage Layer in gestao-financas

To validate this governance in a real application, we applied pipeline-ai v0.11.0 to the persistence layer (internal/storage) of gestao-financas (a Go + Wails v3 + PostgreSQL personal finance platform managing weekly budget envelopes, credit cards, and meal/food vouchers).

  • Before the Decision Ladder: An earlier draft generated without the Decision Ladder hallucinated parallel structs (CreditCard, VoucherBalance, WeeklyEnvelope, MonthlySummary) that did not exist in internal/domain, causing go vet ./... to fail with over 15 compilation errors.
  • With the Decision Ladder + Debt Ledger (DEL-002): architecture-guardrails enforced 100% reuse of domain.Wallet, domain.Transaction, and domain.CalculateDashboard, using pure Go sync.RWMutex (MemoryStore) and database/sql + encoding/json (PostgresStore). The two conscious shortcuts (MemoryStore in storage.go:48 and JSONB sub-item serialization in postgres.go:68) were tracked in the Debt Ledger and surfaced automatically in the Generative UI Dashboard.

5. Conclusion: Simplicity Is Governed Architecture

In the era of autonomous AI coding agents, writing code is no longer the bottleneck; preventing AI from writing unnecessary code is the true engineering discipline.

Pipeline-AI v0.11.0 is 100% open-source (MIT License) and available on GitHub:
🔗 Official Repository: https://github.com/rodrigodosanjosoliveira/pipeline-ai

Top comments (0)