Building Intent-Driven Architecture with Claude Code

Building Intent-Driven Architecture with Claude Code

How to implement WEGA-style orchestration using intent files and MCP in Claude Code

April 2026 · Developer Guide

Introduction

Modern AI-powered applications are moving away from rigid procedural logic toward intent-driven architectures — systems where you declare what you want to achieve, and an orchestration engine figures out how to do it. This pattern, popularized by frameworks like WEGA (Workflow Engine for Goal-based Automation), is now directly implementable in Claude Code using a combination of intent files, MCP (Model Context Protocol) servers, and Claude's built-in reasoning capabilities.

This article walks you through a practical implementation: how to structure your project, write intent files, configure MCP integrations, and wire it all together so Claude Code orchestrates complex multi-service workflows from high-level goal declarations.

Understanding the Architecture

Before writing any code, it helps to understand how the five layers map to Claude Code concepts:

Architecture layerClaude Code equivalentResponsible forIntent LayerIntent files (.intent.md)Declaring goals in natural languageWEGA Orchestration EngineClaude's reasoning loopPlanning and sequencing stepsShared Services LayerShared MCP toolsReusable capabilities (email, DB, payments)MCP / API Access LayerMCP server configConnecting Claude to external servicesExecution SystemsWix, Stripe, Salesforce, etc.Where actual work gets done

Step 1: Project Structure

Start by creating a Claude Code project with the following directory layout:

my-wega-app/ ├── .claude/ │ └── settings.json # Claude Code config + MCP servers ├── intents/ │ ├── process-order.intent.md │ ├── send-invoice.intent.md │ └── update-crm.intent.md ├── services/ │ ├── stripe.mcp.json │ ├── salesforce.mcp.json │ └── wix.mcp.json ├── shared/ │ └── capabilities.md # Shared service descriptions └── CLAUDE.md # Project-level instructions

The intents/ folder is the heart of the Intent Layer — each file declares a goal. The services/ folder maps to the MCP/API Access Layer. The CLAUDE.md file is Claude Code's project-level instruction file, where you define the orchestration rules.

Step 2: Writing Intent Files

Intent files are Markdown documents that describe what you want to accomplish — not how. Claude Code reads these files and reasons about which tools and steps to invoke.

Example: process-order.intent.md

# Intent: Process New Order ## Goal When a new order is placed on Wix, process payment via Stripe, update the CRM record in Salesforce, and send a confirmation email. ## Inputs - order_id: string - customer_email: string - cart_total: number - items: array of { sku, qty, price } ## Success Criteria - Payment is captured with a Stripe charge ID - Salesforce contact has updated purchase history - Customer receives a confirmation email within 60 seconds ## Constraints - If payment fails, do NOT update Salesforce - Log all steps to the audit trail - Retry failed email up to 3 times

Key insight: Notice there are no API calls, no function names, no if/else logic. The intent file describes the what — Claude Code's reasoning loop figures out the how using available MCP tools.

Step 3: Configuring MCP Servers

MCP servers are what give Claude Code the ability to call external services. Configure them in your .claude/settings.json file:

{ "mcpServers": { "stripe": { "command": "npx", "args": ["-y", "@stripe/mcp", "--tools=all"], "env": { "STRIPE_SECRET_KEY": "${STRIPE_SECRET_KEY}" } }, "salesforce": { "command": "npx", "args": ["-y", "@salesforce/mcp"], "env": { "SF_CLIENT_ID": "${SF_CLIENT_ID}", "SF_CLIENT_SECRET": "${SF_CLIENT_SECRET}" } }, "wix": { "command": "npx", "args": ["-y", "@wix/mcp-server"], "env": { "WIX_API_KEY": "${WIX_API_KEY}" } } } }

Each MCP server exposes a set of tools that Claude Code can discover and invoke. Claude doesn't need to know the Stripe SDK — it uses the MCP tools (charge_customer, create_payment_intent, etc.) that the server declares.

Step 4: Writing the CLAUDE.md Orchestration File

The CLAUDE.md file is where you define how Claude Code should behave as an orchestration engine. Think of this as the WEGA Orchestration Engine layer — it tells Claude how to read intent files, which tools are available, and how to sequence work.

# Orchestration Engine Instructions You are an intent-driven orchestration engine. ## How to process an intent 1. Read the intent file from the intents/ directory 2. Identify all inputs required 3. Plan the sequence of MCP tool calls needed 4. Execute each step, checking success criteria as you go 5. If a constraint is violated, halt and report the failure state 6. Return a structured result with step outcomes ## Available capabilities - Stripe MCP: payments, refunds, customers, invoices - Salesforce MCP: contacts, opportunities, cases, activities - Wix MCP: orders, products, members, site data ## Execution rules - Always validate inputs before calling any external service - Log each step with a timestamp and status - Never expose API keys or secrets in output - If a step fails, check the intent's Constraints before continuing

Step 5: Running an Intent from the Command Line

With everything configured, you can trigger intent execution directly from the Claude Code CLI:

claude --intent intents/process-order.intent.md \ --input order_id=ORD-12345 \ --input customer_email=jane@example.com \ --input cart_total=149.99

Claude Code will read the intent file, plan the execution, call the appropriate MCP tools in sequence, and return a structured log of what happened. You get full transparency into the reasoning and each tool call — without having written a single line of orchestration code.

Pro tip: You can also invoke intents programmatically using the Claude SDK in Node.js or Python. Pass the intent file contents as your system prompt and the inputs as user message content.

Step 6: Adding Shared Services

The Shared Services Layer is implemented as a capabilities.md file that describes reusable tools available across all intents. Claude reads this alongside the specific intent file:

# Shared Capabilities ## Email notifications Use the `send_email` tool from the email MCP server. Always include: to, subject, body (HTML supported), reply_to. Retry up to 3 times on failure with 5 second backoff. ## Audit logging Write every external call to the audit log using `log_event`. Format: { intent, step, service, status, timestamp, payload_hash } ## Data validation Before any payment call, validate: email format, amount > 0, required fields present. Reject and report invalid inputs.

Reference this file in your CLAUDE.md with: "Always read shared/capabilities.md before executing any intent." This ensures every workflow has access to the same base capabilities without duplicating logic in each intent file.

Putting It All Together: A Full Execution Trace

Here is what a complete execution trace looks like when Claude Code processes the process-order intent with all layers working together:

Reading intent: intents/process-order.intent.md Reading shared capabilities: shared/capabilities.md Plan: 1. Validate inputs (order_id, customer_email, cart_total) 2. Call stripe.create_payment_intent({ amount: 14999, currency: 'usd' }) 3. Call stripe.confirm_payment({ payment_intent_id: ... }) 4. If payment succeeds: call salesforce.update_contact({ ... }) 5. Call email.send_email({ to: customer_email, ... }) 6. Log all steps to audit trail Executing step 1: Inputs valid Executing step 2: payment_intent pi_3ABC created Executing step 3: Payment captured — charge_id ch_3ABC Executing step 4: Salesforce contact updated Executing step 5: Confirmation email sent Executing step 6: Audit log written Intent fulfilled. All success criteria met.

Why This Pattern Matters

The power of this approach is the clean separation between declaring goals and implementing them. Your business stakeholders can read and even write intent files — they describe business logic in plain language. Your developers configure the MCP servers once. Claude handles the orchestration.

This also makes your system remarkably adaptable. Want to swap Stripe for Braintree? Update the MCP server config and the shared capabilities description — the intent files don't change at all. Want to add a new workflow? Write a new intent file, no orchestration code required.

As MCP server ecosystems grow across Wix, Salesforce, Stripe, Kafka, and beyond, intent-driven architecture with Claude Code becomes a genuinely practical pattern for building complex, multi-service workflows without the traditional overhead of writing and maintaining integration code.

Tags: intent-driven architecture · claude code · MCP · WEGA · AI orchestration · Wix · Stripe · Salesforce