Why AI Coding Agents Stall: The Context Engineering Gap No One Talks About

The Factory Mirage: When the Agent Starts Hallucinating

You wire up a coding agent to a linear ticket. The prompt looks bulletproof. You’ve defined the acceptance criteria, linked the relevant files, and set a temperature of 0.1. The agent spins up, reads the codebase, and produces a pull request in 90 seconds. You open the diff and see a beautifully formatted disaster. It invented a library that doesn’t exist. It refactored a module you explicitly told it to leave alone. It solved a problem adjacent to the ticket but not the ticket itself.

This is not a model capability problem. The model is smart enough. The failure is upstream—in what the agent was allowed to see and what it was forced to ignore. We call this the context engineering gap, and it is the single largest silent killer of autonomous coding workflows in production.

The GitHub repository humanlayer/advanced-context-engineering-for-coding-agents lays out this failure mode bluntly. The authors argue that most teams treat coding agents like a smarter linting tool, feeding them a diff and a prayer. The result is a software factory that looks impressive in a demo and collapses the moment ambiguity enters the chat.

As an engineer, you already know this intuitively. You don’t onboard a junior developer by handing them a Jira ticket and a link to the repo. You give them context: why this change matters, which customers are screaming, what the last three attempts looked like, and which senior engineer will review the PR with a flamethrower. Coding agents need the same treatment, but the industry is still stuck in the “better prompt” phase when the real leverage is in the information architecture surrounding the prompt.

The Dirty Secret: Harness Engineering vs. Context Engineering

The repo draws a sharp distinction that every forward deployed engineer needs to internalize: harness engineering is not context engineering.

Harness engineering is the plumbing. It’s the CI/CD integration, the agent loop, the tool definitions, the sandbox. It’s what lets the agent execute code, read files, and open PRs. Most teams spend 90% of their energy here because it feels like real infrastructure work. It’s satisfying to build.

Context engineering is the signal. It’s the deliberate curation of what the agent sees in its context window before it writes a single line. This includes:

• The full stack trace from the last production incident related to this module.
• The Slack thread where the product manager clarified that the “quick fix” actually needs to handle three edge cases.
• The git blame annotations showing who touched this file last and why.
• The architectural decision record that explains why the database schema looks weird.
• The test suite output from the last three CI runs, not just the current one.

When you skip context engineering, you are asking the agent to operate with a massive information deficit. The model will fill that deficit with statistically plausible hallucinations. It will guess the intent. It will assume the codebase follows conventions that it doesn’t. It will produce code that passes unit tests and fails reality.

This maps directly to the Forward Deployed Engineer workflow. When you embed with a customer, your superpower isn’t writing code faster. It’s understanding the customer’s context deeply enough that the code you write is correct the first time. You don’t ship a feature by reading the API docs alone. You ship it by sitting in their standups, reading their incident reports, and understanding the political landscape of their engineering org. A coding agent without context engineering is like an FDE who only reads the API docs and never talks to the customer.

The Signal Architecture: What the Agent Actually Needs

Let’s get concrete. The source material describes a pattern where context is layered, not flattened. The worst thing you can do is dump 50,000 tokens of raw repository text into the prompt and hope the attention mechanism sorts it out. It won’t. The agent will latch onto the most recent or most repetitive tokens and miss the critical signal buried in the middle.

Instead, build a context architecture with deliberate layers:

Layer 1: The Intent Signal. This is more than the ticket title. It’s the “why” distilled into two sentences. A human wrote the ticket while context-switching between three meetings. Distill it. If the ticket says “update the billing endpoint to handle prorated charges,” the intent signal might be: “We are losing $12k/month because customers who downgrade mid-cycle get charged the full amount. The fix must handle partial-month calculations and backfill existing subscriptions. The finance team will validate the output manually for the first 30 days.”

Layer 2: The Relevant Surface Area. Do not feed the agent the entire repository. Use a retrieval step—sparse vector search, AST-aware chunking, or even a simple grep for the symbols mentioned in the ticket—to pull in only the files that matter. The goal is high precision, not high recall. The agent can always request more files if it needs them.

Layer 3: The Historical Context. This is where most factories fail. The agent needs to know what happened the last time someone touched this code. Pull the last 10 commits on the relevant files. Include the commit messages. If there’s an incident report that mentions this module, include a summary. If a previous PR was reverted, include the revert reason. This layer prevents the agent from repeating mistakes that the team already paid for.

Layer 4: The Constraints. Coding standards, architectural patterns, library version pins, and testing requirements. This is not optional. If your team has a rule against using any in TypeScript, state it explicitly in the constraints layer. The model knows the rule exists in the abstract but doesn’t know your team enforces it with extreme prejudice.

The assembly step stitches these layers into a prompt where the most critical information appears first and last—the primacy and recency positions in the context window. Everything in the middle is supporting material. This is not superstition; it’s a well-documented behavior of transformer attention mechanisms.

Try It Today: A Practical Context Injection Loop

You don’t need to rebuild your entire CI pipeline to start engineering context. Here’s a lightweight loop you can run in an afternoon using tools you already have:

Step 1: Fork the agent’s pre-prompt. If you’re using something like Cursor, Copilot, or a custom agent loop, find where the system prompt or initial context is assembled. It’s usually a template string in a configuration file or a Python script.

Step 2: Add a context retrieval step. Before the agent runs, execute a script that:

1. Parses the ticket or task description.
2. Extracts file paths, function names, and class names mentioned.
3. Runs git log --oneline -10 -- <file> for each relevant file.
4. Searches your incident management tool for recent alerts mentioning those files.
5. Dumps all of this into a structured context block.

Here’s a minimal Python sketch:

import subprocess
import json

def build_context_block(ticket_text: str, relevant_files: list[str]) -> str:
    context = ["## Historical Context\n"]
    for f in relevant_files:
        log = subprocess.run(
            ["git", "log", "--oneline", "-5", "--", f],
            capture_output=True, text=True
        )
        if log.stdout.strip():
            context.append(f"### {f}\n```\n{log.stdout.strip()}\n```\n")
    
    # Add incident context (pseudo-code for your incident tool)
    # incidents = search_incidents(module=extract_module(ticket_text))
    # if incidents:
    #     context.append(f"### Recent Incidents\n{incidents[0].summary}\n")
    
    return "\n".join(context)

Step 3: Inject the context block into the agent’s prompt. Place it after the system instructions but before the task description. The agent should see the historical context before it sees what you’re asking it to do. This frames the task in the reality of the codebase.

Step 4: Run a before-and-after comparison. Take a non-trivial ticket that the agent previously got wrong. Run it with the default context. Run it again with your injected context block. Compare the diffs. You will likely see the agent stop making the same category of mistakes—inventing APIs that don’t exist, violating architectural boundaries, or ignoring recent changes.

This is not a theoretical exercise. Teams that implement even this basic context loop report a 30-50% reduction in agent-generated PRs that require significant human rework. The cost is a few hundred lines of glue code and a slight increase in latency before the agent starts coding. The latency is worth it.

For a deeper dive into building agents that interact with real-world systems, see our guide on building a calendar-scheduling agent that negotiates meeting times over email. The same context engineering principles apply: the agent’s success depends entirely on how much situational awareness you give it before it starts sending emails on your behalf.

The Balanced Take: When Factories Win, When They Crash

Let’s not throw the factory model out entirely. There are scenarios where a low-context, high-throughput agent loop works brilliantly:

• Boilerplate generation: Creating a new CRUD endpoint that follows an existing pattern exactly.
• Well-specified migrations: Database schema changes where the desired state is unambiguous.
• Greenfield prototypes: When there’s no legacy code to misunderstand, the agent can generate freely.

In these cases, the context is naturally low-entropy. The agent doesn’t need to know the history because the task is self-contained. A factory approach—ticket in, code out—works fine.

The factory collapses when the task is high-entropy:

• Bug fixes in legacy modules: The bug exists because of a complex interaction between three subsystems built by different teams. The agent needs to understand all three.
• Feature work with ambiguous requirements: The ticket says “improve performance.” The agent needs to know which queries are slow, what the SLO is, and what the last optimization attempt broke.
• Cross-cutting changes: Modifying an interface that 12 services depend on. The agent needs to know which services exist and which ones are actually maintained.

In these high-entropy scenarios, context engineering is not optional. It is the difference between an agent that ships a working fix and an agent that ships a plausible-looking regression. The FDE skill set maps perfectly here: the ability to triage ambiguity, extract signal from noisy customer environments, and translate that signal into precise technical work is exactly what makes a human FDE effective and exactly what a context-unaware agent lacks.

FAQ: Context Engineering for Working Engineers

Q: Isn’t this just prompt engineering with extra steps?

No. Prompt engineering is about phrasing the instruction. Context engineering is about curating the information the instruction references. A perfectly phrased prompt with bad context will produce perfectly phrased wrong code. The distinction matters because the fix is in your retrieval and assembly pipeline, not in your choice of words.

Q: How do I know if my agent’s failures are context problems or model capability problems?

Run the same task with a human engineer. Give the human the exact same context you gave the agent. If the human also fails, it’s a context problem. If the human succeeds easily, the agent’s context window might be missing critical information that the human inferred from experience. Add that information explicitly to the context block.

Q: Won’t longer context windows solve this automatically?

Longer context windows help, but they are not a substitute for curation. Models with 1M-token context windows still exhibit degraded attention in the middle of the window. Dumping more raw text into the prompt increases the probability that the critical signal gets buried. Curation matters more as windows get larger, not less.

Q: How does this relate to Forward Deployed Engineering?

Forward Deployed Engineers are human context engineers. Their entire value proposition is embedding with a customer, absorbing the unwritten rules, the political constraints, and the operational reality, and then shipping code that actually works in that environment. If you want to build agents that can do FDE-style work, you need to give them FDE-style context. Our case study on deploying an LLM feature at an enterprise customer in 10 days shows exactly how context gathering determines whether a deployment succeeds or fails.

Q: What’s the simplest thing I can do today to improve my agent’s output?

Add the last 10 commits on the files you’re asking the agent to modify into the prompt. That’s it. It takes five minutes to implement and it will immediately reduce the rate at which the agent proposes changes that conflict with recent work. Once you see the impact, you’ll start hunting for more context sources to inject.