BoundaryML has discovered that the primary barrier to adoption for their BAML language isn't the syntax or the compiler, but the sheer messiness of code produced by AI agents. While GPT-6.1-Sol with Codex can write functional BAML, it defaults to the same spaghetti logic it produces in other languages when left to its own devices. To fix this, the team overhauled their 'skill' documentation, moving away from simple feature lists to a rigorous set of 27 best-practice guidelines modeled after the C++ Core Guidelines.

The Problem with Feature Lists

Previously, BAML's skill documentation simply enumerated features like match statements, type unions, and reflection. The team found that agents knew these tools existed but had no idea when to use them. In a test involving a chess move generator, zero out of ten Codex runs opted to use an enum, instead relying on fragile string comparisons for piece types. This resulted in single functions nested seven levels deep with a cognitive complexity score of 50, creating code that works but is impossible to maintain.

Guidelines Over Features

The new approach explicitly bans anti-patterns and mandates specific structures. For example, the new skill instructs agents to use closed types (enums) for fixed sets of values to prevent typos, and to prefer match statements over if chains to ensure exhaustive checking. The results were immediate: nine out of ten subsequent Codex runs successfully implemented enums in the same chess generator task. This shift proves that agents need prescriptive rules for style, not just descriptive docs for syntax.

Quantifying the Improvement

BoundaryML integrated a baml codequality command into their toolchain to measure metrics like Cognitive Complexity, Cyclomatic Complexity, and NPath. They ran a comprehensive eval across four tasks, including a POSIX regex engine and the RealWorld Conduit API. The data shows a clear downward trend in complexity with each iteration. For the Conduit API task, the mean cognitive complexity dropped from 129 with no skill to just 8 when agents were instructed to run the codequality command during development.

Key Takeaways

  • Feature-rich documentation is insufficient for agents; they require explicit style guidelines and anti-pattern warnings.
  • Integrating quality metrics directly into the agent's workflow loop yields the highest maintainability scores.
  • The new BAML skill reduces cognitive complexity in agent-generated code by up to 90% on practical tasks.

The Bottom Line

If you are building a new language for the AI era, assume the agents will write terrible code by default. You have to actively engineer the 'skill' context to force them into your idioms, or you'll just end up with Python-style spaghetti in a Rust-like syntax.