AI Coding Agents: From Tool Calling to Spec-Driven Development

1. Introduction: Why Understand How Agents Work

As large language models become more capable, AI coding agents have evolved from basic code completion tools into complex systems that can understand requirements, call tools, execute commands, and modify code. However, many developers still interact with these tools only at the surface level: they enter a prompt and wait for the result, without understanding how the agent parses instructions, manages context, or orchestrates tool calls.

Although popular coding tools differ in how open or closed their implementations are, their core design patterns are highly similar. Input preprocessing, command routing, context injection, tool invocation, and result feedback form the basic pipeline behind most command-line agents.

Understanding this pipeline helps developers use existing tools more effectively. It also provides a practical blueprint for teams building internal agents or integrating private models into their development workflows.

2. The Core Processing Flow of a Command-Line Agent

2.1 Input Preprocessing: The First Layer of Intent Routing

Prompts entered into a command-line interface are not always sent directly to the language model. They typically pass through a preprocessing stage that distinguishes structured commands from natural-language conversations. This significantly reduces unnecessary model interactions and improves both response time and cost efficiency.

Typical routing rules include the following.

Slash command detection: When a prompt begins with /, the system treats it as a built-in command rather than conversational input. The command may trigger a local operation directly, or it may be replaced with a predefined prompt template before being sent to the model. For example, a command that resets the conversation or clears the context can usually be handled locally without model inference.

File path reference detection: When a prompt contains a pattern such as @ followed by a file path, the system checks whether the path exists. If it does, the agent reads the file and injects its contents into the context.

This mechanism provides several benefits:

• Users can explicitly control which files the model can see instead of allowing the agent to scan the entire repository.
• The agent can avoid multiple rounds of file discovery by receiving the required context in a single request.
• In large repositories, it can reduce token consumption and latency significantly.

This approach—explicit context declaration first, intelligent retrieval as a fallback—is widely used as a best practice in agent design.

2.2 Command Registration and Routing

Built-in commands are usually defined in a modular way. In a typical open-source agent architecture, command implementations are grouped in a CLI package or UI command directory. Each command is placed in its own file and follows a common interface that defines its name, description, argument parser, and execution function.

This design keeps extensions inexpensive. Adding a new command generally requires creating a new file and registering it, without modifying the core processing flow.

The command router parses the command name and arguments, finds the corresponding handler, and executes it. For commands that need to interact with the model—for example, custom prompt commands—the router combines a predefined template with the user’s arguments and forwards the resulting request to the model service.

At the configuration layer, agents commonly use a JSON file in the user’s home directory to manage extensions. For example, an external tool service can be connected through the STDIO protocol:

{
  "mcpServers": {
    "command-tools": {
      "command": "npx",
      "args": ["command-tools-server"]
    }
  }
}

This configuration specifies how the tool service should be started and which transport mechanism it uses. When the agent starts, it launches the corresponding process and communicates with it through JSON-RPC over standard input and output.

2.3 Designing a Replaceable Model Integration Layer

Another important architectural principle is decoupling the model integration layer from the agent’s core logic. Many agents are initially tightly coupled to a specific model provider. The community has addressed this limitation through compatibility layers that convert internal request formats into a broadly compatible OpenAI-style API format.

With this approach, an agent can switch to different model services that follow the same protocol, including privately deployed models used inside an organization.

The key lesson for enterprises is that model integration should be standardized and configurable when evaluating or building an agent. Separating built-in authentication from external model interfaces is an important engineering step toward supporting internal models.

3. Limitations of MCP-Based Tool Calling

MCP, or the Model Context Protocol, provides a unified way for agents to connect to external tools. However, relying on direct MCP tool calls for complex tasks creates several structural problems.

1. Context window waste. When an MCP service is connected, its tool definitions—including names, descriptions, and parameter schemas—are typically added to the system prompt. As the number of tools grows, these definitions can consume a significant portion of the context window, leaving less space for understanding the code itself and increasing the cost of each request.

2. Inefficient multi-round interactions. Complex tasks often require several tools to be called in sequence. Each call can involve a complete round trip to the model. The model must reason over intermediate results before deciding what to do next, which increases latency and makes the transfer of intermediate state more error-prone.

3. Difficult tool granularity decisions. If tools are too fine-grained, the model must perform extensive reasoning to coordinate the call sequence. If they are too coarse-grained, their parameters become complicated and error rates may increase. Finding the right balance is difficult, and no single granularity works well for every scenario.

4. Limited accumulation of business knowledge. MCP tools provide capabilities, but they do not explain how those capabilities should be used effectively. Team-specific engineering standards, coding conventions, and operational practices cannot be fully conveyed through tool definitions alone.

4. Skills and Code Execution: Responses to These Limitations

To address these problems, modern agent architectures commonly introduce two important improvements. Their underlying design ideas are broadly applicable.

4.1 Skills

The core idea behind a skills system is progressive context loading. Domain knowledge and operational procedures are organized as structured documents. The system prompt contains only a concise skills index, such as each skill’s name and one-sentence description.

When the model determines that a task matches a particular skill, it loads the detailed documentation on demand.

This approach prevents tool definitions and domain knowledge from occupying the entire context window. It also gives teams a standardized way to capture engineering knowledge. In practice, a skill document functions as an operational guide that the model can follow.

4.2 Code Execution with MCP

Another improvement is to let the model write code that calls tools instead of issuing individual tool-call requests one at a time.

In this model, tools are exposed through lightweight API descriptions. The model generates a script, which runs in a restricted execution environment. The script can chain multiple tool calls internally and return only the final result to the model.

The advantages are clear:

• Intermediate data moves through the code rather than through the model context, significantly reducing token usage.
• Control flow such as loops, conditions, and error retries is expressed through deterministic code, which is generally more reliable than asking the model to make a decision at every step.
• A single model request can complete a compound task that would otherwise require multiple round trips.

The trade-off is the need for a secure sandbox and sufficient code-generation quality. This makes sandbox isolation and permission control essential infrastructure for agent design.

5. Spec-Driven Development: Making Collaboration More Predictable

As agents become more deeply integrated into software development, a new question emerges: how can collaboration between humans and agents become predictable and traceable?

Spec-driven development provides a structured answer. A typical workflow consists of three stages.

1. Specification stage: Requirements are converted into structured specification documents that define goals, scope, constraints, and acceptance criteria. A specification is not simply a one-time narrative. It is a layered documentation system that can progress from project-level conventions to the detailed design of an individual change.

2. Clarification stage: Before implementation begins, the agent uses the specification to identify open questions. It works with the developer to confirm technology choices, the scope of impact, compatibility requirements, and other important decisions. The result is a clear implementation plan.

3. Task decomposition and execution stage: The implementation plan is divided into small, verifiable tasks. The agent executes them one by one and uses the specification’s acceptance criteria to determine whether each task is complete. This prevents misunderstandings from expanding during implementation.

The value of this approach is that it brings traditional software engineering practices—documentation, review, and acceptance testing—back into the agent collaboration process.

The agent no longer relies primarily on vague natural-language hints. Instead, it operates within clearly defined contractual constraints.

Several engineering challenges remain open: reducing the effort required to write specifications, automatically checking consistency between specifications and code, and keeping specifications up to date as the system evolves.

6. Conclusion

AI coding agents are evolving from tool-call orchestrators into engineering collaboration systems that combine knowledge loading, code execution, and specification-based constraints.

Their core design principles can be summarized as follows:

• Explicit context is better than implicit context.
• On-demand loading is better than injecting everything at once.
• Deterministic code is better than relying on repeated model reasoning.
• Structured contracts are better than unconstrained conversation.

These principles are useful both for working more effectively with existing coding agents and for designing agent solutions around internal models and private codebases.

As skills systems and spec-driven practices mature, agents will move closer to becoming engineering collaborators that are systematic, predictable, and trustworthy.