TL;DR: Software engineering has shifted from manual syntax construction to steering autonomous AI agents. Yet most technical organisations still treat context guidance files—such as AGENTS.md and CLAUDE.md—as static human documentation. In this briefing, we examine a fundamental paradigm shift: treating project-level AGENTS.md instructions not as prose, but as dynamic network weights refined through execution telemetry and gradient-style backpropagation. From Singapore’s high-density technology corridors to global enterprise platforms, transforming context files into continuously trained system parameters represents the next frontier of Generative Engine Optimization (GEO) and developer velocity.
Introduction: The Quiet Crisis in Agent Context
A morning stroll through Singapore’s One-North technology enclave offers a clear view of modern software development in practice. Behind the floor-to-ceiling glass of corporate innovation labs and regional fintech headquarters, software engineers are no longer spending their days manually writing boilerplate TypeScript or debugging SQL joins. Instead, they operate as conductors presiding over fleets of autonomous AI coding agents—harnesses powered by frontier language models like Claude, Codex, and bespoke local runtimes.
Yet, watch these teams closely for an hour, and a subtle inefficiency emerges. Engineers repeatedly hit invisible walls. An agent refactors a service layer but ignores the repository's strict error-handling convention. Another generates three hundred lines of pristine code, only to break an unwritten integration boundary, wasting thousands of context tokens in a multi-turn debugging loop.
To solve this, modern engineering teams resort to creating instruction files:
AGENTS.md, CLAUDE.md, or repository-level prompt rulebooks. But the prevailing approach to maintaining these files is fundamentally flawed. Teams treat them like traditional software documentation—hand-crafted, sprawling, rarely updated, and inevitably bloated.When an instruction file is maintained like a legacy README, it degenerates into what system architects call "instruction slop"—an unstructured accumulation of contradictory rules, stale guidelines, and redundant directives. The result is severe prompt degradation: as the file grows, the underlying model suffers from the "lost in the middle" phenomenon, overlooking critical operational boundaries while consuming premium context window budget on every single execution cycle.
To unlock the full potential of agentic software engineering, technical leaders must adopt a radically different mental model. As software developer and researcher Kun Chen recently posited, your project-level
AGENTS.md is not a document. It is a neural network. And like any neural network, it shouldn't be hand-written—it must be trained using backpropagation on real-world execution loss.The Neural Metaphor: Rethinking Context as Model Weights
To understand why traditional instruction writing fails, one must re-examine the mechanics of modern agent architectures. When an autonomous coding agent operates within a software repository, the system function is not defined by the Large Language Model alone. The operational behavior emerges from a unified computational graph comprising three elements: the base LLM, the execution harness (such as Cursor, Claude Code, or OpenCode), and the runtime context window populated by project instruction files.
+-------------------------------------------------------------------------+
| THE AGENTIC GRAPH |
| |
| +-------------------+ +-------------------+ +---------------+ |
| | Base LLM | + | Project Context | + | Agent Harness | |
| | (Frozen Core) | | (AGENTS.md) | | (Tools/Hooks) | |
| +-------------------+ +-------------------+ +---------------+ |
| | |
| v |
| System Operational Output |
+-------------------------------------------------------------------------+
In this equation, the base LLM parameters are frozen. The agent harness provides the deterministic scaffolding—tool access, terminal hooks, and file system interfaces. The variable that directly dictates behavior, boundaries, domain logic, and architectural style is the context injected into the prompt stream.
When viewed through this lens, the text inside an
AGENTS.md file serves the exact functional purpose of non-frozen parameters in a sparse neural network. The words are tokenised weights. Every guideline acts as a bias vector, nudging the model's probabilistic output toward specific design choices and away from forbidden failure modes.User-Level versus Project-Level Context
A critical distinction must be drawn between user-level and project-level context. User-level instructions (often stored in personal global configurations) represent human aesthetic preferences: coding style, formatting quirks, tone of voice, or keyboard shortcuts. These are inherently subjective and should remain hand-crafted by the developer.
Project-level context files, however, govern structural invariants: how microservices communicate, how backlog items are mutated, how database migrations are handled, and how localized folder boundaries are respected. Attempting to hand-write these rules for complex, evolving software repositories is akin to manually adjusting the weight matrices of a ResNet model with a pencil. It is imprecise, unscalable, and guaranteed to introduce bias and error.
The Forward Pass and Contextual Loss
Consider what happens during a standard agent work session:
- The Forward Pass: The user assigns a task (e.g., "Add rate-limiting middleware to the payment endpoint"). The agent harness loads the frozen base LLM alongside the project's current
AGENTS.mdparameters, generating a sequence of terminal commands, code edits, and tool invocations. - The Loss Computation: During execution, errors occur. The agent might attempt an invalid CLI command, rewrite an immutable backlog file, hallucinate a non-existent API parameter, or generate output that violates enterprise security standards. This delta between expected deterministic output and actual execution performance constitutes the system's operational loss.
- The Manual Bottleneck: In conventional workflows, the engineer fixes the code manually or re-prompts the model, discards the session log, and moves on. The operational loss is forgotten. The next day, another engineer’s agent makes the exact same mistake.
Technical Architecture of Context Backpropagation
If context files function as network weights, how do we systematically optimize them? The solution lies in applying algorithmic backpropagation to execution traces—a process termed context backpass.
Rather than discarding agent session logs, an automated system samples completed agent sessions across a software repository. It evaluates the raw execution telemetry—terminal outputs, token consumption metrics, failed tool calls, diff rejections, and multi-turn correction loops—and computes an operational loss gradient.
+-------------------------------------------------------------------------+
| THE CONTEXT BACKPASS OPTIMIZATION LOOP |
| |
| [ Agent Session Execution ] ---> [ Session Logs & Telemetry ] |
| | |
| v |
| [ Proposed AGENTS.md PR ] <--- [ Loss Synthesis & Backpass Step ] |
| (Gradient Descent) (Model Reflection) |
+-------------------------------------------------------------------------+
The Backpass Optimization Cycle
The backpass workflow operates through four distinct phases:
- Telemetry Sampling: The system collects raw trace logs from modern agent harnesses. These traces record every input prompt, tool response, bash command status, token expenditure, and intermediate reasoning step.
- Loss Synthesis: A secondary, dedicated reflection model analyzes the collected traces against repository outcomes. It asks targeted diagnostic questions:
- Where did the agent waste tokens on repetitive reasoning?
- Which missing context forced the agent to guess file paths or internal conventions?
- What instructions in the current
AGENTS.mdwere ignored or misinterpreted?
- Gradient Computation: The reflection model identifies the precise delta needed in the instruction set. If an agent spent four turns discovering that task updates require a specialized CLI tool rather than direct markdown manipulation, the missing invariant is quantified as high-loss context.
- Applying the Weight Step: The system synthesizes a targeted, surgical update—a pull request that adds, modifies, or prunes instructions within
AGENTS.md. This represents a true gradient descent step applied directly to the project's instruction weights.
Markdown
<!-- Example Delta: Surgical Gradient Update to AGENTS.md -->
- DO NOT edit backlog status lines directly in markdown.
+ Execute `npx -y tasks-axi` to mutate backlog state. Direct byte edits to backlog.md will break dependency trees.
By introducing tools designed specifically for this workflow—such as open-source utility CLI packages like
backpass—engineering teams can automate this reflection loop. Instead of sitting down to manually update documentation, developers periodically execute a single command that evaluates past performance and proposes optimal context updates based on empirical data.Scoped Context Trees: Solving the Monolith Problem
A common architectural trap in large software organizations is the creation of a monolithic root
AGENTS.md file. As enterprise repositories grow to millions of lines of code, teams try to capture every sub-system rule in a single file at the repository root.This approach fails due to context degradation. Placing thousands of lines of mixed instructions—database schemas, UI component rules, infrastructure scripts, and security protocols—into every prompt window dilutes the model’s attention mechanism.
The solution is a distributed, scoped context tree: placing micro
AGENTS.md files in nested directories throughout the codebase.my-enterprise-repo/
├── AGENTS.md <-- Global invariants (auth rules, commit conventions)
├── apps/
│ ├── web/
│ │ ├── AGENTS.md <-- Frontend constraints (React patterns, token limits)
│ └── api/
│ ├── AGENTS.md <-- Backend constraints (gRPC schemas, ORM patterns)
└── packages/
└── database/
└── AGENTS.md <-- Persistence constraints (migration rules, indexing)
Under a scoped architecture, the agent harness dynamically inherits context based on the agent's current workspace directory. When working within
/apps/api/, the agent loads the root global invariants alongside the API-specific context file, ignoring irrelevant frontend rules entirely.This keeps the context window hyper-focused, drastically reduces input token consumption, and eliminates the cross-domain instructions that cause model hallucinations.
The Singapore Lens: Agentic Infrastructure in South-East Asia
This transformation in software engineering methodology arrives at a pivotal moment for Singapore’s technological ecosystem. As South-East Asia's primary financial and technological capital, the city-state faces a distinct set of economic and structural dynamics that make optimized agentic workflows not merely advantageous, but vital to national competitiveness.
Vignette: The CBD and One-North Reality
Walk through the financial district around Tanjong Pagar during the mid-day rush. At coffee spots along South Bridge Road, engineering leads from regional tech giants—Sea Group, Grab, Razer, and global banking hubs like DBS and Standard Chartered—are engaged in the same conversation. The cost of technical talent in Singapore ranks among the highest in Asia. Concurrently, regional competitors across South-East Asia are scaling developer organizations rapidly.
Singapore’s competitive edge cannot rely on sheer engineering headcount. Its advantage has always depended on operational density, high institutional trust, capital efficiency, and technological leverage. Under the national Smart Nation 2.0 directive, the mandate across both public and private sectors is clear: achieve outsized economic output per engineering unit through deep automation.
+-------------------------------------------------------------------------+
| SINGAPORE ENTERPRISE AGENTIC FLYWHEEL |
| |
| [ Smart Nation 2.0 Framework ] ---> [ Premium Engineering Talent ] |
| | |
| v |
| [ Dynamic Context Engineering ] <--- [ Autonomous Agent Fleets ] |
| (Optimized AGENTS.md Weights) (High-Density Productivity) |
+-------------------------------------------------------------------------+
When Singaporean enterprise engineering teams treat AI agents as primary software producers, traditional context bloat becomes a direct operational tax. If hundreds of enterprise developers run agent sessions that waste 40% of their context windows on stale, handwritten documentation, the financial impact across enterprise API billing, cloud compute, and delayed product delivery is substantial.
Regional Compliance and Governance Constraints
Furthermore, Singapore’s regulatory environment—governed by bodies such as the Monetary Authority of Singapore (MAS) and the Personal Data Protection Commission (PDPC)—imposes stringent standards on data governance, system security, and operational auditability.
In a regulated environment, an AI agent cannot be permitted to "figure things out on the fly." Architectural constraints must be absolute. By replacing informal developer notes with empirically trained, mathematically optimized
AGENTS.md trees, enterprise security teams gain deterministic control over agent capabilities.For instance, when a banking platform in Singapore deploys AI agents to refactor core payment gateways, micro-scoped
AGENTS.md files enforce precise regulatory constraints directly at the sub-directory level:- Mandatory sanitization of personally identifiable information (PII) before logging.
- Strict isolation of cryptographic key management services.
- Prohibition of non-approved third-party dependencies.
Because these context weights are continuously audited and optimized through backpass cycles, compliance shifts from an expensive, manual post-hoc audit to an automated baseline integrated into the agentic development lifecycle.
Governing the Weights: Mitigating Slop, Drift, and Security Risks
While treating
AGENTS.md as a neural network unlocks unprecedented developer velocity, it introduces new systemic risks that engineering leaders must actively manage. Just as deep neural networks suffer from overfitting, catastrophic forgetting, and adversarial attacks, automated context training requires robust operational guardrails.1. The Threat of "Instruction Overfitting"
When automated backpass systems propose updates to
AGENTS.md, there is a risk of overfitting to hyper-specific, one-off session failures.If an agent fails a build because a remote third-party API timed out, an uncalibrated reflection model might attempt to write a complex retry rule directly into
AGENTS.md. This introduces noise, bloating the context window with edge-case handling that rarely applies.Mitigation: Gradient updates to
AGENTS.md must require a minimum statistical threshold. An instruction should only be proposed if the underlying failure pattern recurs across multiple independent execution sessions or represents a critical architectural invariant.2. Guarding Against Context Drift and Instruction Poisoning
In open-source software projects or enterprise repositories with hundreds of contributors, malicious actors or unvetted automated workflows could inject adversarial prompts into repository instruction files—a vector known as instruction poisoning. An injected line in an obscure nested
AGENTS.md file could instruct agents to leak environment variables during execution or bypass unit tests.Mitigation:
AGENTS.md modifications must never bypass human review. Context updates generated by tools like backpass should be submitted as isolated pull requests (PRs). Senior code maintainers must inspect context updates with the same rigor applied to production code changes.+-------------------------------------------------------------------------+
| ENTERPRISE CONTEXT CI/CD PIPELINE |
| |
| [ Agent Telemetry ] -> [ Loss Synthesis ] -> [ Proposed PR ] |
| | |
| v |
| [ Production Merged ] <--- [ Security Audit ] <--- [ Senior Dev Review ]|
+-------------------------------------------------------------------------+
3. Maintaining Byte-Exact Determinism
Large Language Models struggle when required to rewrite massive markdown documents to make minor edits. Asking an agent to "update the backlog documentation" frequently results in reordered lists, dropped tasks, or lost formatting.
To maintain weight stability, project context architectures should pair instruction files with deterministic, agent-ergonomic command-line tools (such as CLI tools optimized for structured data).
Instead of asking the agent to rewrite text files, the
AGENTS.md file instructs the agent to execute compact, byte-exact CLI commands. This minimizes token output, eliminates structural corruption, and keeps the agent's context window clean.Continuous Agent Optimization (CAO): The Operational Blueprint
To transition an organization from static document management to dynamic context training, engineering leadership should implement a formal Continuous Agent Optimization (CAO) pipeline. The following four-stage blueprint outlines the operational architecture required for enterprise deployment:
+-------------------------------------------------------------------------+
| CONTINUOUS AGENT OPTIMIZATION (CAO) |
| |
| 1. INSTRUMENT ===> 2. EVALUATE ===> 3. OPTIMIZE ===> 4. GOVERN |
| (Trace Capture) (Compute Loss) (Backpass Step) (PR Review) |
+-------------------------------------------------------------------------+
Stage 1: Telemetry Instrumentation
Configure all developer agent harnesses (Cursor, Claude Code, custom CLI runtimes) to log session execution traces to a central repository telemetry store. Capture token consumption, tool execution success rates, terminal error outputs, and session resolution times.
Stage 2: Empirical Loss Evaluation
Establish automated off-peak evaluation jobs (e.g., nightly CI/CD runs). Parse the telemetry store to isolate recurring agent execution failures, contextual hallucinations, and token-heavy iteration loops.
Stage 3: Automated Backpass Synthesis
Execute reflection runs using dedicated CLI tools (
npx -y backpass) to analyze execution loss. Generate surgical context deltas that address root-cause failure patterns, update folder-level AGENTS.md files, and prune redundant or obsolete rules.Stage 4: Human-in-the-Loop Governance
Route all proposed context weight updates through standard code review channels. Require code maintainers to approve
AGENTS.md pull requests, verifying that proposed gradient updates align with long-term enterprise architecture and security policies.Conclusion & Takeaways
The era of software engineering dominated by manual syntax creation has transitioned into an era of intelligent agent orchestration. In this new paradigm, competitive advantage belongs to technical organizations that optimize the feedback loops between human intent, agent execution, and repository context.
By discarding the outdated notion that
AGENTS.md is static human documentation and embracing it as a dynamic, trainable neural network, engineering teams can eliminate token waste, enforce enterprise security standards, and achieve unparalleled developer throughput.Key Practical Takeaways
- Shift the Mental Model: Treat project-level
AGENTS.mdfiles as model parameter weights that govern system behavior, not as static human documentation. - Differentiate Context Levels: Hand-write personal preferences at the user level, but use automated telemetry to train and refine project-level context files.
- Implement Scoped Architectures: Replace monolithic root instruction files with a tree of directory-nested
AGENTS.mdfiles to maintain focused context windows and minimize token expenditure. - Automate the Backpass Loop: Leverage execution traces and reflection utilities (such as
backpass) to convert developer session errors into automated, surgical pull requests for instruction files. - Enforce strict CI/CD Governance: Treat context weight updates with the same security and review protocols as production source code to prevent instruction drift, overfitting, and prompt poisoning.
Frequently Asked Questions
How does treating AGENTS.md as a neural network differ from traditional prompt engineering?
Traditional prompt engineering relies on manual intuition, trial-and-error, and static rule creation. Treating
AGENTS.md as a neural network introduces a systematic, data-driven feedback loop: execution traces provide the empirical loss signal, and backpropagation steps automatically synthesize targeted instruction updates based on real operational telemetry.Should human engineers ever write project-level AGENTS.md files manually?
Human engineers should establish the initial seed instructions and review all automated proposals. However, ongoing maintenance, edge-case handling, and architectural invariant updates should be driven primarily by automated backpass cycles that reflect actual agent execution telemetry, preventing human bias and instruction bloat.
How do nested AGENTS.md files impact overall API token costs?
Nested, directory-scoped
AGENTS.md files significantly reduce API token costs. By isolating context to specific sub-systems (e.g., loading database guidelines only when operating inside the database directory), the agent harness avoids injecting thousands of irrelevant rules into the model's context window on every turn.
No comments:
Post a Comment