Your Coding Agent Needs a Map, Not a Bigger Context Window — Part 2

Last year, I wrote that your coding agent needs a map, not a bigger context window. Since then, model vendors shipped 1M+ token windows (GPT-5.5 at 1M tokens in API, April 2026 [Source: https://openai.com/index/introducing-gpt-5-5/]) — and teams are still finding that bigger windows don’t fix production reliability. The question is not whether this demos well; it is whether it survives maintenance, handoff, and local constraints when your Jakarta prod cluster shrinks from six engineers to three and the Modoo Laravel SaaS projects still need to ship on Friday.

Context rot is real. A 5-minute task holds everything in context. A 3-day task cannot. When agents have free-roaming access to a codebase, they make connections that don’t exist, lose focus on the actual task, and waste tokens on irrelevant information [Source: https://cruxdigits.nl/blog/context-engineering-ai-agents-2026/]. The platform didn’t just catch up; it overtook the workarounds we’ve been shipping. Microsoft Conductor formalized three context modes — accumulate for planning, last_only for implementation, explicit for review — because uncontrolled context is a liability, not an asset [Source: https://sourcegraph.com/blog/context-engineering].

1. The Context Window Trap — Why More Tokens Is the Wrong Lever

Model vendors sell tokens. You buy reliability. These are different products.

A 1M token window (GPT-5.5) can ingest an entire medium-sized repository, dependency graphs, test suites, and documentation in a single pass [Source: https://chatgptaihub.com/the-big-ai-coding-agents-story-what-june-26-s-news-means-for-developers/]. But as context grows, irrelevant code competes for attention, and when the window fills, agents start compressing their own memory — often mid-task [Source: https://towardsdatascience.com/coding-agents-dont-need-bigger-context-windows-they-need-a-context-compiler/]. The failure mode is subtle: the agent appears to work, then silently drops a critical invariant because it was pushed out of the compressed context.

 1# What a big-context agent sees (100K tokens)
 2- 500 source files
 3- 200 test files  
 4- Full documentation
 5- Previous conversation history
 6- Dependency lockfiles
 7- CI configs
 8
 9# What it actually needs for a bug fix
10- 3 files: the buggy function, its caller, its test
11- The type signature of the return value
12- The assertion that failed in CI

The industry is converging on context engineering as a distinct discipline: carefully controlling what information an agent has access to at any given point [Source: https://cruxdigits.nl/blog/context-engineering-ai-agents-2026/]. This isn’t prompt engineering — it’s context budgeting with explicit manifests.

2. Code Graphs — The Map Your Agent Actually Needs

An agent asking through a code graph gets the same accuracy on 5 repositories or 500, whereas retrieval quality degrades as the codebase grows past what similarity ranking can cover [Source: https://bito.ai/blog/code-graphs-explained-for-ai-coding-tools-2026-guide/]. That’s the scale where enterprise systems actually live.

TypeScript Compiler Code Graph MCP exposes the compiler’s symbol, type, and import relationship graph via MCP. Instead of grep → open file → trace imports loops, the agent queries the compiler’s knowledge directly — reducing token usage by ~10x in early experiments [Source: https://github.com/samchon/ttsc/tree/master/packages/graph]. The same pattern applies to other languages: Go’s go/analysis, Rust’s rust-analyzer, Java’s OpenRewrite.

 1// TypeScript Code Graph MCP query — what the agent actually needs
 2interface CodeGraphQuery {
 3  symbol: string;           // "calculateShippingCost"
 4  depth: number;            // 2 hops: callers + callees
 5  includeTests: boolean;    // true
 6  includeTypes: boolean;    // true
 7}
 8
 9// Returns: exact files, line ranges, type signatures, test cases
10// Token cost: ~2K vs 50K+ for full repo context

Sourcegraph’s MCP server backed by SCIP indexing is one production-grade answer for teams running coding agents on large codebases [Source: https://sourcegraph.com/blog/context-engineering]. The pattern is consistent: query the structure, don’t read the volume.

1# Before: Agent reads 50 files to understand a change
2grep -r "calculateShippingCost" --include="*.ts" | head -50
3
4# After: Agent queries the code graph (single MCP call)
5# Returns: 3 callers, 2 callees, 1 test file, exact type signatures
6# Token delta: ~90% (~10x reduction)

3. Artifact Contracts — Proof Before Success Ping

Your cron job is not healthy because it exited zero. It is healthy when the expected artifact exists, is fresh, has substance, and passes a domain-specific assertion [Source: https://zemna.net/posts/your-cron-job-is-not-healthy-until-the-artifact-proves-it/ — author’s prior post]. The same principle applies to AI agent output.

An artifact contract answers four questions:

1. Path or handle — where the result must appear: file path, URL, database row, post ID, commit SHA
2. Freshness window — how new it must be relative to the schedule
3. Minimum substance — bytes, words, rows, records, IDs, or another non-empty signal
4. Domain assertion — the result is usable: JSON schema valid, HTTP 200, row state moved to done, generated HTML exists

 1// Artifact contract for an AI agent coding task
 2interface ArtifactContract {
 3  path: string;                    // "src/pricing/shipping.ts"
 4  freshness: string;               // "< 5 minutes from agent completion"
 5  minBytes: number;                // 500 (non-trivial change)
 6  assertions: ArtifactAssertion[]; // [{ type: "typescript-compile", pass: true }, { type: "test-suite", name: "shipping.test.ts", pass: true }]
 7}
 8
 9// Agent completion handler
10async function onAgentComplete(result: AgentResult): Promise<boolean> {
11  const contract = loadContract(result.taskId);
12  
13  // Verify artifact exists and is fresh
14  const stats = await fs.stat(contract.path);
15  if (Date.now() - stats.mtimeMs > contract.freshnessMs) return false;
16  if (stats.size < contract.minBytes) return false;
17  
18  // Run domain assertions
19  for (const assertion of contract.assertions) {
20    if (!await runAssertion(assertion, contract.path)) return false;
21  }
22  
23  // Only now: success ping
24  await pingHealthchecks(contract.healthcheckUrl);
25  return true;
26}

This extends [[silent-failure-detection]] and [[exit-zero-empty-output]] from error detection into a reusable implementation pattern: define the artifact contract first, then place the success ping behind the verifier [Source: https://zemna.net/posts/your-cron-job-is-not-healthy-until-the-artifact-proves-it/ — author’s prior post].

Heartbeat services like Healthchecks.io and Cronitor are still useful, but the success ping should happen after artifact verification. A ping before verification means the process ended; a ping after verification means the deliverable survived inspection.

4. Alerting as Code — The Missing Operational Layer

Alerting as Infrastructure as Code treats service alerts as reviewable, deployable, versioned code — not console clicks or personal settings [Source: https://engineering.ab180.co/stories/standardizing-alert-system-with-iac/]. AB180’s case study shows alert rules managed in Git, routed through Slack for visibility and PagerDuty for on-call escalation [Source: https://engineering.ab180.co/stories/aws-alert-iac/].

For AI agent pipelines, this is the missing operational layer. When an agent silently drifts (wrong context, compressed memory, skipped test), the alert rule catches what the artifact contract missed:

 1# alerts/agent-drift.yaml
 2groups:
 3  - name: agent-pipeline-drift
 4    rules:
 5      - alert: AgentContextCompressionDetected
 6        expr: |
 7          agent_context_tokens_used / agent_context_tokens_limit > 0.9
 8        for: 5m
 9        labels:
10          severity: warning
11          component: ai-agent-pipeline
12        annotations:
13          summary: "Agent {{ $labels.agent_id }} context at >90% — likely compression"
14          runbook: "https://runbooks.internal/agent-context-compression"
15          
16      - alert: AgentArtifactContractFailed
17        expr: |
18          increase(agent_artifact_contract_failure_total[15m]) > 0
19        for: 1m
20        labels:
21          severity: critical
22          component: ai-agent-pipeline
23        annotations:
24          summary: "Agent {{ $labels.agent_id }} artifact contract failed"
25          runbook: "https://runbooks.internal/agent-artifact-failure"
26          
27      - alert: AgentSilentFailure
28        expr: |
29          agent_heartbeat_timestamp < time() - 300
30          and agent_status != "completed"
31        for: 5m
32        labels:
33          severity: critical
34          component: ai-agent-pipeline
35        annotations:
36          summary: "Agent {{ $labels.agent_id }} no heartbeat for 5m — possible stall"
37          runbook: "https://runbooks.internal/agent-silent-failure"

This connects [[silent-failure-detection]], [[artifact-based-health-checks]], and [[autonomous-agent-cron-pipelines]] — alerts become code-reviewable operational assets. Especially for cron-based automation and AI agent operations, the alert itself must be a code-reviewable operational asset [Source: https://engineering.ab180.co/stories/standardizing-alert-system-with-iac/].

5. Structure-First Workflow — The Complete Pattern

The structure-first AI coding workflow treats context window as a budget, not architecture. The core pattern [Source: https://zemna.net/posts/your-coding-agent-needs-a-map-not-a-bigger-context-window/ — author’s prior post]:

Total: ~11K tokens vs 100K+ for full-context approach

 1graph TD
 2    A[Task: Fix shipping cost bug] --> B[Query Code Graph MCP]
 3    B --> C{Depth 2: callers + callees}
 4    C --> D[Read 3 files max]
 5    D --> E[Write patch + test]
 6    E --> F[Run test suite]
 7    F --> G{Artifact contract passes?}
 8    G -->|Yes| H[Success ping → Healthchecks]
 9    G -->|No| I[Alert: ArtifactContractFailed]
10    H --> J[Alert rule: ContextCompression / SilentFailure]

The pattern connects [[ts-compiler-code-graph-mcp]], [[artifact-based-health-checks]], [[alerting-as-iac]], and [[context-engineering]]. It reframes AI coding reliability away from “larger context window” debates and toward explicit maps, evidence, and operational coverage.

6. Zero-Cost Observability — Start Small, Stay Operational

Zero-cost observability means using SaaS free tiers (Sentry, PostHog) for error tracking and user behavior analysis before building custom monitoring infra [Source: Sentry pricing (5K events/mo free), PostHog pricing (1M events/mo free), Healthchecks.io pricing (20 checks free)]. The goal is closing the observability loop fast, not building the perfect dashboard.

For AI agent pipelines, this translates to:

The 2026-07-06 blog post Zero-Cost Observability for Agent Crons (https://zemna.net/blog/zero-cost-observability-agent-crons/) published the practical version: artifact verifier first, then Sentry Cron Monitoring, PostHog product signal, OpenTelemetry vocabulary, and a named rollback command [Source: internal wiki concept zero-cost-observability]. Cross-posted through Postiz to X and Threads — the X follow-up tested a no-link question: “Which proof do you check first?” shifting from blog promotion to concrete artifact choice: file, row, URL, or trace.

7. What You Can Delete from Your Agent Stack This Quarter

Just like the CSS migration that deleted 15–25 kB of JavaScript bundle, the context-window-maximalism stack has deletable components:

The LogRocket 2026 article demonstrated replacing 150+ lines of custom dropdown JavaScript with appearance: base-select [Source: https://blog.logrocket.com/css-in-2026/]. The parallel here: replacing 500+ lines of context-stuffing logic with a 20-line code graph query.

 1#!/bin/bash
 2# agent-stack-audit.sh — find context-window-maximalism patterns
 3# Usage: ./agent-stack-audit.sh [path]
 4
 5TARGET="${1:-.}"
 6echo "=== Agent Stack Audit ==="
 7echo "Scanning: $TARGET"
 8echo ""
 9
10echo "--- Full repo context stuffing (look for 'repository', 'codebase', 'all files') ---"
11grep -rE "repository|codebase|all files|full context" "$TARGET" --include="*.py" --include="*.ts" --include="*.js" | wc -l
12
13echo "--- Heuristic retrieval (similarity, embedding, vector search without graph) ---"
14grep -rE "similarity|embedding|vector.*search|retrieval" "$TARGET" --include="*.py" --include="*.ts" --include="*.js" | wc -l
15
16echo "--- Missing artifact contracts (no verification before success) ---"
17grep -rE "exit 0|success|complete" "$TARGET" --include="*.sh" --include="*.py" | grep -v "artifact\|contract\|verify\|assert" | wc -l
18
19echo "--- Console-click alerts (no alert-as-code) ---"
20if [ -d "$TARGET/.github/workflows" ]; then
21  grep -r "alert\|notification" "$TARGET/.github/workflows" | grep -v "prometheus\|alertmanager\|yaml\|yml" | wc -l
22fi
23
24echo ""
25echo "Run with a path argument to audit a specific directory."

What You Should Do Monday Morning

1. Audit your agent context strategy — Search your agent prompts and orchestration code for “full repository”, “codebase”, “all files”, “similarity search”, “embedding retrieval”. Tag each with the structure-first alternative (code graph query, explicit manifest, artifact contract).

2. Pick one code graph to pilot — For TypeScript: ttsc graph MCP. For Go: go/analysis. For Rust: rust-analyzer HTTP. For Python: pyright or ruff LSP. Expose it as an MCP tool or HTTP endpoint. Replace one “read 20 files” agent step with a graph query. Measure token delta and test pass rate.

3. Write one artifact contract — For your most critical agent task, define the four-contract questions (path, freshness, substance, assertion). Move the success ping behind the verifier. Deploy the contract and measure false-positive rate (agent claims success but contract fails).

4. Codify one alert rule — Take your most painful agent failure mode (context compression, silent stall, contract failure). Write it as a Prometheus/Alertmanager rule in Git. Route to Slack + PagerDuty. Require PR review for alert changes.

5. Activate zero-cost observability — If you don’t have Sentry/PostHog on your agent pipeline, add them today. Sentry free tier: 5K events/month. PostHog free tier: 1M events/month. Healthchecks.io free tier: 20 cron checks. Instrument: task start, task complete, token usage, contract pass/fail. Build the dashboard in PostHog — it takes 15 minutes.

6. Schedule the cleanup sprint — Once three agent tasks run on structure-first patterns with passing contracts and firing alerts, create a ticket to remove the context-stuffing code paths. Don’t leave dead retrieval logic in the orchestration — it confuses AI agents and junior devs alike.

7. Share the pattern — Document your migration in the team wiki. A structure-first workflow is only as good as the team’s ability to follow it. The next engineer who onboards should find the code graph query pattern, not the context-stuffing anti-pattern.

Further Reading

• Context Engineering: The 2026 Playbook for AI Agents — Practical token budgeting and context rot prevention
• Sourcegraph: Context Engineering — SCIP-backed MCP for production code graphs
• TypeScript Compiler Code Graph MCP — Reference implementation for compiler-backed graphs
• Zero-Cost Observability for Agent Crons — Artifact verifier, Sentry, PostHog, rollback command

Internal links: AI Agent Operations · Developer Tools · Start Here

Cover image: /covers/context-window-critique-2.png (to be generated)