Beyond Copy-Paste: Why AI Agents Need a "Compiler" and Governance Flow
Recently, I built a small open-source tool and enthusiastically shared it with a senior architect friend. I pitched it like this:
"Simply put, it flattens a subagent into a markdown file, making it portable to any runtime at any time."
His response was very grounded: "Too professional, I don't get it... I haven't done technical design in this area..."
That reply made me pause. I realized that in today's exploding AI Agent ecosystem, developers who immerse themselves in it daily have created too many buzzwords that alienate traditional software engineers. But if we strip away the jargon, what we are actually facing is a very classic software engineering problem.
Today, I want to share a real story from the trenches—the story of why we recently built the open-source repository subagent-harness.
Phase 1: Context & Pain Point — Fast-Evolving "Living Software" and Definition Drift
Recently, our team has been developing Magpie. To enable Magpie to accurately extract insights from massive amounts of casual conversation, a simple prompt isn't enough. We run a batch of specialized AI Agents in our backend, and each contains highly structured configurations: hundreds of words of deep system instructions, a suite of bound external APIs (Skills), and specific runtime parameters like confidence thresholds and penalty factors.
This system runs smoothly in production. However, for testing and rapid iteration, developers prefer to install the agent from the repository into their local AI IDE (like Cursor) so they can summon it for testing at any time while writing code.
Here is a crucial characteristic of advanced AI development: Agents are highly "living" artifacts. If you follow industry trends, you'll know that top teams are no longer just manually tweaking prompts. A new generation of self-optimization techniques is emerging:
- DeepMind's Promptbreeder treats prompts as organisms, using LLMs to mutate and breed better prompts through evolutionary selection.
- EvoSkill goes further—it discovers entirely new skills for agents based on failure patterns and applies Pareto selection to balance competing objectives.
- The Opus Self-Evolving Agent experiment demonstrated an agent that learned to reflexively delete its own code as part of structural evolution.
- Frameworks like Genetic Prompt Programming and DSPy provide ready-to-use pipelines where prompts are scored, diagnosed, and mutated automatically against test corpora.
This means the system constantly mutates, crosses over, and eliminates prompts and parameters based on real user feedback—evolving daily or even hourly. In the future, they might continuously self-iterate based on global corpora.
In today's AI-native workflow, developers rarely copy and paste manually anymore. The most common approach is to open an LLM and say: "Help me pull the latest Agent definition from the repo and install it into my local IDE for testing." This sounds elegant. But when the same Agent is being iterated at high frequency—sometimes by humans, sometimes by automated evolution pipelines—the lack of a forced synchronization mechanism causes production configurations and local IDE files to quickly fall out of sync.
This is what we call Definition Drift.
A few days later, when a colleague ran a local agent in the IDE, it hallucinated and outputted the wrong format. After troubleshooting, we found that the local IDE agent was still using an older prompt that hadn't undergone the latest optimization.
As long as the same Agent's definition is physically split across two places, divergence is inevitable during high-frequency iteration. The Agent you see in your local IDE becomes a lie compared to production.
Phase 2: The Solution — SSOT and a Complete Governance Flow
To solve this, we went back to first principles. In frontend development, we write TypeScript once and use a compilation chain to output code for different browsers. Why couldn't we write an Agent in a unified format and use an automated compilation flow to distribute it to different runtimes?
To address this synchronization and coordination issue, we introduced the concept of a Single Source of Truth (SSOT) and built a complete management workflow around it:
1. Establishing a Single Data Source
We abandoned scattered configuration definitions across the backend code. Instead, we established a standard rich-text format using Markdown with a YAML header. This single file contains all the configurations required by production alongside the raw prompt. This is the sole "gene pool" for the Agent in the universe.
2. Automated Audit and Composition
We designed a lightweight pipeline. When a developer—or a self-evolving algorithm—updates this source file, running a single command triggers the pipeline. It first performs an audit to validate formatting and check for missing fields. Then it composes the output: acting like a smart translator, it flattens and trims the complex source, discards backend-specific configurations the local tool doesn't understand, and generates a perfectly clean file tailored for the IDE.
3. Reverse Empowerment: Giving AI a Governance Skill
This is perhaps the most exciting part. Since AI is iterating on Agents every day, why should humans be the only ones managing the governance?
We embedded a dedicated Governance Skill within the repository. Now, when you ask the LLM in your IDE to "tune this agent," it no longer blindly edits or creates files. It actively calls this Skill, modifies the single source file according to the established protocol, and automatically triggers the underlying compilation and smoke tests. With this harness, we taught the AI how to elegantly manage itself.
4. Direct Reads Across All Environments
Simultaneously, our production backend directly reads and parses this exact same source file.
From then on, whether it's a manual tone adjustment or an algorithmic logic optimization, all modifications happen in one flat file. The local IDE and production environment are tightly bound by the pipeline, maintaining pixel-perfect consistency.
Phase 3: Abstraction and Open Source — Paving the Way for Multiple Runtimes
After successfully running this workflow internally, we realized something important: this centralized governance approach—flattening and standardizing complex Agent definitions—is highly reusable across the entire iteration lifecycle, from development to testing to production.
Today, your Agent runs in your backend and your IDE. Tomorrow, your team might introduce a new CLI tool like Claude Code. The day after, you might need to package this Agent and embed it into a brand-new terminal product.
If we locked this compilation and governance flow inside our business code, we'd have to rewrite the synchronization logic every time we switch environments. So we extracted the core parsing, validation, and compilation logic into a lightweight, open-source component with zero business dependencies: subagent-harness.
Its ambition is simple: to serve as a portable Agent compiler. No matter how many runtimes you integrate in the future, you only need to maintain one flat, metadata-rich source file. Any iteration on the source instantly compiles and syncs to all downstream runtimes, completing the developer experience loop from dev to prod.
If your team is struggling with sharing standard AI assistants, or dealing with inconsistent Agent behavior across different environments, we welcome you to try it out.
Top comments (0)