Prompt-Based AI Agents: Designing Systems Where Plain Text Is the Architecture
Software architecture usually treats code as the source of truth and natural language as documentation. Prompt-based AI agents flip this model entirely: the workflow, domain rules, and decision-making logic live in plain English Markdown files, while code acts solely as an execution engine.
By paring an agent down to its essentials, you can build a flexible system around two core primitives: * The Playbook (The Instructions): A natural language document defining goals, step-by-step reasoning, constraints, and output formats. * The Runtime (The Engine): A lightweight script that feeds the playbook to a Large Language Model (LLM) and executes any actions the model requests.
Architectural Breakdown: Separating Logic from Code
In traditional software, adding a feature requires writing explicit if/else logic, custom functions, and output parsers. In a prompt-based architecture, control flow is emergent—the LLM decides the steps dynamically based on the playbook.
- Code as a Dumb Pipe: The underlying code knows nothing about business domains, databases, or specific APIs. It simply passes user input and playbook instructions to the model, executes generic requests (like making an HTTP call), and returns raw responses back to the model.
- The Autonomous ReAct Loop: The agent operates on a continuous Reason -> Act -> Observe cycle. The model evaluates user intent against the playbook, decides whether to trigger an action, observes the result, and repeats until it can construct a final answer.
- Instant Domain Swapping: Because domain knowledge is completely decoupled from the codebase, changing the agent's entire function requires only pointing the runtime at a different Markdown file. The code stays identical whether the agent is querying a database, auditing system health, or managing internal tickets.
Conceptual Parallels: Playbooks vs. Claude Code Skills
This design pattern closely mirrors how Claude Code Skills operate. Both treat structured natural language as executable code:
| Concept | Prompt-Based Agent | Claude Code Skills |
|---|---|---|
| Logic Layer | Playbook (.md file) |
Custom Skill (SKILL.md) |
| Action Layer | Generic HTTP Tool | OS Primitives (Bash, Read, Write) |
| Runtime | Custom LLM Script | Claude Code CLI Engine |
- Declarative Capabilities: Instead of writing Python or TypeScript modules to expand what the agent can do, you write clear instructions describing how to perform a task.
- General-Purpose Primitives: Both systems avoid bespoke, single-use tools. Instead, they give the LLM broad execution primitives (like raw API requests or shell commands) and rely on the instruction file to guide how those tools are used safely and effectively.
- Adaptive Control Flow: If an action fails—such as an API returning an error—the LLM uses the playbook's guidance to interpret the failure and dynamically adjust its strategy without crashing the application.
High-Level Trade-offs
Pros
- Zero-Code Expansion: Adding new capability requires writing Markdown, not code.
- Human-Readable Logic: Non-engineers can review and audit agent behavior easily.
- Minimal Maintenance: Very small codebase footprint with minimal wrapper boilerplate.
Cons
- Non-Deterministic Output: Models may occasionally deviate from instructional paths.
- Prompt Brittleness: Unclear prompt wording can trigger unexpected tool calls or formats.
- Higher Cost & Latency: Multi-step tool loops send prompts back and forth across every iteration.
When to Use This Pattern
- Ideal Use Cases: Internal automation tools, rapid prototyping, and flexible domains where requirements change rapidly and non-engineers need to tune behavior without redeploying code.
- Poor Use Cases: Safety-critical or financial operations requiring strict determinism, or high-throughput microservices where LLM round-trip latency is unacceptable.
Explore the Codebase
To see how a minimal runtime script and Markdown playbooks work together in practice, check out the repository on GitHub:
- GitHub Repository: Prompt-Based AI Agent Codebase
