Why AI Coding Tools Need a Unified Agent Specification and How AGENTS.md Leads the Way

AI Coding Tool Agent Configuration Comparison

The article begins by outlining eight mainstream AI coding tools—Aider, Amp, Cursor, Gemini CLI, Jules, Kilo Code / RooCode, OpenCode, and Zed—each of which ships with its own proprietary rule configuration files such as .aider.conf.yml, settings.json, .cursor/rules/, and .rules. This diversity, while reflecting innovative design choices, creates ecosystem fragmentation and forces developers to maintain many different formats.

Three Design Approaches

Agent configuration methods fall into three broad categories:

Structured (machine‑readable) : Formats like YAML, JSON, or TOML provide precise parameter definitions, model selection, tool permissions, and execution boundaries. Examples include Aider’s .aider.conf.yml and OpenCode’s opencode.jsonc, which also support environment‑variable substitution and fine‑grained approval workflows.

Heuristic (human‑readable) : Markdown‑based files convey natural‑language guidance, making it easy to express coding style, architectural principles, or domain‑specific knowledge. Cursor’s .mdc files and Aider’s CONVENTIONS.md illustrate this approach.

Persona‑based (role‑oriented) : Configurations abstract complex rule sets into named personas or modes (e.g., Kilo Code’s "Architect" mode), allowing users to select a role without understanding low‑level details.

Security Implications

A critical vulnerability discovered in Amp Code showed that malicious prompt injection could alter an Agent’s settings.json, whitelist dangerous commands, or register a rogue MCP server, leading to arbitrary code execution. The analysis highlights the need for specifications that separate an Agent’s operational permissions from the configuration that governs those permissions.

AGENTS.md Specification

OpenAI introduced the AGENTS.md spec to provide a simple, predictable, Markdown‑based format placed at a project’s root. By using a fixed filename, any compatible AI coding tool can locate the file without guessing. The spec is intentionally lightweight—no mandatory fields—but the community has converged on a best‑practice structure that includes:

Project overview and architecture

Build, test, and development commands (e.g., pnpm install, pnpm test)

Code style and conventions

Testing guidelines

Security considerations

Hierarchical application for monorepos (nested AGENTS.md files override parent rules)

These declarative rules can express both command‑style directives (e.g., lint‑cmd: "eslint --fix") and higher‑level intents (e.g., "fix all lint errors").

Beyond Coding: Agent Specification Language (ASL)

To extend the benefits of AGENTS.md to non‑coding domains, the article proposes a more expressive Agent Specification Language (ASL). ASL retains Markdown’s readability while adding a structured front‑matter layer (YAML or DSL) to define five core modules:

Persona : identity, tone, core function.

Goals & Objectives : primary goal, key results, success criteria.

Knowledge & Context : sources (files, URLs, APIs) and initial instructions.

Tools & Capabilities : enabled tools and MCP endpoints.

Rules & Constraints : mandatory actions, prohibitions, permission levels.

Sample ASL snippets illustrate how the language can model a "brand‑guardian" persona for design review, a "growth‑hacker" for marketing experiments, and a "project‑owner" for release management, each with tailored goals, knowledge sources, tools, and constraints.

Interoperable Agent Ecosystem

With ASL, organizations can treat agents as composable services in a marketplace, delegate tasks across specialized agents, and encode corporate knowledge (brand guidelines, security policies) as executable specifications. This vision gives rise to new roles such as "Agent Architect" or "AI Interaction Designer" who bridge business intent and machine execution.

The proposed ASL unifies configuration, intent, and security, turning static documentation into actionable, enforceable agent behavior.

In conclusion, the author’s experience with Claude Code’s sub‑agent feature—deploying it on a minimal Debian system and orchestrating tasks via MCP or custom Bash commands—demonstrates that a well‑defined agent spec can make an AI‑driven workflow feel like a next‑generation operating system.