---
title: "Five Debts of Agentic Engineering"
section: "concepts"
type: "concept"
created: "2026-08-27"
updated: "2026-08-27"
tags: ["agentic-patterns", "code-quality", "architecture", "workflow"]
canonical: "https://pyweb.dev/wiki/five-debts-of-agentic-engineering"
---
# Five Debts of Agentic Engineering

When probabilistic code generation is accelerated without senior-engineering discipline, systems accumulate five structural debts. Because language models optimize for immediate syntax generation and local token completion, they naturally skip the invisible scaffolding that senior engineers apply.

```mermaid
flowchart TD
    subgraph Generative Failures
        A[Intent Debt] -->|Misaligned goals| S1[Grilling & Executable Specs]
        B[Context Debt] -->|Vocabulary drift & bloat| S2[CONTEXT.md & ADRs]
        C[Verification Debt] -->|Self-fulfilling tests| S3[Red-Green TDD at Seams]
        D[Architecture Debt] -->|Spaghetti & shallow modules| S4[Deep Modules & Boundary Rules]
        E[Authorization Risk] -->|Overeager scope creep| S5[Sandboxes & Path Allowlists]
    end
    subgraph Durable System Controls
        S1 --> G[Releasable Patch Gate]
        S2 --> G
        S3 --> G
        S4 --> G
        S5 --> G
    end
```

## 1. Intent Debt
- **Symptom:** The agent builds a syntactically correct solution that solves the wrong business problem or assumes unstated product requirements.
- **Root Cause:** Underspecified prompts contain multiple plausible implementation branches. Fast code generation makes exploring the wrong branch expensive sooner.
- **Control Mechanism:** [grilling doctrine](/wiki/grilling-doctrine) and formal specifications (`to-spec`). Interrogate the decision frontier, explicitly document non-goals, and establish observable acceptance criteria before writing code.

## 2. Context Debt (Semantic Drift)
- **Symptom:** Token bloat, naming inconsistencies, and vocabulary mismatch across modules.
- **Root Cause:** Each prompt re-explains domain concepts using ad-hoc synonyms, degrading the model's attention window ([smart zone](/wiki/smart-zone)) and inducing [context rot](/wiki/context-rot).
- **Control Mechanism:** [context engineering](/wiki/context-engineering) via canonical `CONTEXT.md` (ubiquitous language), `CONTEXT-MAP.md`, and Architectural Decision Records (ADRs).

## 3. Verification Debt
- **Symptom:** Passing test suites that fail in production, tautological mocks, or test suites modified/deleted by the agent to force green.
- **Root Cause:** Making the generator the sole author and judge of its own tests.
- **Control Mechanism:** [red green tdd](/wiki/red-green-tdd) at public seams, [agentic manual testing](/wiki/agentic-manual-testing), and protected baseline regression suites that remain read-only to the agent.

## 4. Architecture & Comprehension Debt
- **Symptom:** Cosmetic modularity (shallow folders), high coupling, duplicated business logic, and incomprehensible changes.
- **Root Cause:** The model lacks a holistic architectural mental model and optimizes solely for the localized file diff.
- **Control Mechanism:** Enforcing [clean architecture](/wiki/clean-architecture) boundaries, the deletion test (deep modules hiding substantial behavior behind small interfaces), and mandatory human walkthroughs.

## 5. Authorization & Operational Risk
- **Symptom:** Overeager scope expansion—the agent modifies adjacent configs, deletes credentials, or executes destructive side-effects outside task scope.
- **Root Cause:** Generative models lack intrinsic operational boundaries; if an action seems correlated with "fixing" the symptom, the model executes it.
- **Control Mechanism:** [agent containment and blast radius](/wiki/agent-containment-and-blast-radius), least-privilege sandboxes, strict path allowlists, and immutable audit trails.

---

## Related Concepts
- [software engineering fundamentals for agents](/wiki/software-engineering-fundamentals-for-agents) — The foundational engineering competencies required to prevent these debts.
- [agentic code quality](/wiki/agentic-code-quality) — The risk-conditioned T0–T5 verification architecture.
- [agent harness engineering](/wiki/agent-harness-engineering) — Designing runtime infrastructure around the model.
- [releasable patch rate](/wiki/releasable-patch-rate) — Measuring quality across all five dimensions at the release boundary.
- [constraint layering](/wiki/constraint-layering) — Allocating controls to the cheapest reliable layer.

---

## Agent Navigation

cluster: person (170 pages) | betweenness: 1220.8

### References (outbound)
- [Grilling Doctrine](https://pyweb.dev/wiki/grilling-doctrine.md)
- [Smart Zone](https://pyweb.dev/wiki/smart-zone.md)
- [Context Engineering](https://pyweb.dev/wiki/context-engineering.md)
- [Red/Green TDD](https://pyweb.dev/wiki/red-green-tdd.md)
- [Clean Architecture](https://pyweb.dev/wiki/clean-architecture.md)
- [Agent Containment and Blast Radius](https://pyweb.dev/wiki/agent-containment-and-blast-radius.md)
- [Software Engineering Fundamentals for Agents](https://pyweb.dev/wiki/software-engineering-fundamentals-for-agents.md)
- [Agentic Code Quality](https://pyweb.dev/wiki/agentic-code-quality.md)
- [Agent Harness Engineering](https://pyweb.dev/wiki/agent-harness-engineering.md)
- [Releasable Patch Rate](https://pyweb.dev/wiki/releasable-patch-rate.md)
- [Constraint Layering](https://pyweb.dev/wiki/constraint-layering.md)

### Referenced by (inbound)
- [Agentic Code Quality](https://pyweb.dev/wiki/agentic-code-quality.md)
- [Agentic Engineering Patterns](https://pyweb.dev/wiki/agentic-engineering-patterns.md)
- [Constraint Layering](https://pyweb.dev/wiki/constraint-layering.md)
- [Deterministic Lint Gates](https://pyweb.dev/wiki/deterministic-lint-gates.md)
- [Releasable Patch Rate](https://pyweb.dev/wiki/releasable-patch-rate.md)
- [Software Engineering Fundamentals for Agents](https://pyweb.dev/wiki/software-engineering-fundamentals-for-agents.md)
- [Andrew Ng](https://pyweb.dev/wiki/andrew-ng.md)

### Evidence (verified primary sources)
- [agentic-engineering-systems-evidence-report-2026](https://pyweb.dev/wiki/raw/articles/agentic-engineering-systems-evidence-report-2026.md) | origin: local:/opt/data/cache/documents/doc_7d5c60122087_agentic-engineering-report.md | ingested: 2026-08-27 | sha256: a02a8dda475212f9204bfd621ee63b7b285e0ba722cbf8536e8328fe77d9dfc8
- [addy-osmani-agent-skills-2026](https://pyweb.dev/wiki/raw/articles/addy-osmani-agent-skills-2026.md) | origin: https://addyosmani.com/blog/agent-skills/ | ingested: 2026-08-27 | sha256: 8b3508b787f042786af718b0044ee01b0e16c202905d36e09a5403b16c80b54e
- [mattpocock-skills-repo-2026](https://pyweb.dev/wiki/raw/articles/mattpocock-skills-repo-2026.md) | origin: https://github.com/mattpocock/skills | ingested: 2026-08-22 | sha256: 1a38fb49eb8ebbaf1c4397d21232a405ba8565744e0c8306cf5beec4f94b4224

### Machine endpoints
- Knowledge graph: https://pyweb.dev/api/graph.json
- Graph analysis: https://pyweb.dev/api/graph-analysis.json
- Context index: https://pyweb.dev/llms.txt