AI Agent Design

AI Agent Design Extension

Overview

This extension augments the generic devforge-architecture-design skill with AI Agent-specific evaluation dimensions, anti-patterns, and architecture guidance. It is loaded automatically when the PRD contains tags like ai_agent, llm_orchestration, tool_use, or multi_agent.

Extension Mechanism

When devforge-architecture-design detects an AI Agent domain tag:

1. It reads this SKILL.md to understand the overlay rules
2. It reads references/dimensions.md for additional evaluation dimensions
3. It reads references/anti-patterns.md for domain-specific risks
4. These dimensions are ADDED to the generic pattern evaluation, not replacing it

When to Load

• PRD mentions: LLM, agent, ReAct, tool use, function calling, RAG, memory, planning, multi-agent
• Project characteristic tags include: ai_agent, llm_orchestration, tool_use

Overlay Rules

1. Additional Architecture Evaluation Dimensions

For each evaluated pattern, add these AI Agent-specific dimensions:

2. Pattern-Specific Guidance

Event-Driven Architecture

• Strength for AI Agents: Natural fit for asynchronous tool execution, streaming LLM responses
• Risk: Eventual consistency can cause agent state drift if not carefully managed
• Guidance: Use event sourcing for agent action history; ensure idempotent tool execution

Microservice Architecture

• Strength for AI Agents: Separate services for LLM inference, tool execution, memory retrieval
• Risk: Network latency between agent orchestrator and LLM service
• Guidance: Co-locate orchestrator and LLM service if latency is critical; use caching for frequent prompts

Hexagonal Architecture

• Strength for AI Agents: Isolate LLM provider adapters; swap OpenAI for Claude without touching core logic
• Risk: Over-abstraction of simple LLM calls
• Guidance: Ports for LLMClient, ToolRegistry, MemoryStore; adapters per provider

Plugin-Based Architecture

• Strength for AI Agents: Tool registry as plugin system; third-party tools load dynamically
• Risk: Tool sandboxing and permission model complexity
• Guidance: Implement strict tool capability declarations and runtime permission checks

3. Mandatory XML Additions

When generating architecture.xml for an AI Agent system, ensure these modules are considered:

• Orchestrator: ReAct loop, plan generation, agent delegation
• LLMGateway: Provider abstraction, prompt management, token tracking
• ToolRegistry: Tool discovery, parameter validation, execution routing
• MemoryStore: Vector search, conversation history, long-term memory
• SecurityJudge: Input classification, prompt injection detection, rate limiting

Add AI-specific StateModel entries:

• conversation_history: location, owner (Orchestrator), lifecycle
• agent_context_window: location (in-memory / Redis), owner (Orchestrator), lifecycle (per-session)
• tool_execution_cache: location (Redis), owner (ToolRegistry), lifecycle (TTL-based)

4. Interface Contract Additions

Every AI Agent system should define these cross-module interfaces:

References

• references/dimensions.md — Full evaluation dimension definitions and scoring guides
• references/anti-patterns.md — AI Agent architecture anti-patterns and mitigations

Source: lzj2819/DevForge-skill — distributed by TomeVault.