# Learn AI-Engineering — ship production software with agents

Source: https://www.openmercato.com/learn-ai-engineering

# Learn AI-Assisted Engineering

A practical guide to building production-grade software with AI agents using Open Mercato as your foundation.

## How to Master AI-Assisted Coding with Open Mercato

## The roadmap to mastering AI-assisted coding

### Understand the "Context First" Architecture

Standard AI coding often fails because the LLM loses context in large, fragmented codebases. Open Mercato solves this through its structural choices.

- Mono-repo Advantage: By keeping the core and modules in a mono-repo, you allow agents (like Cursor or Claude) to see the full relationship between entities, APIs, and the UI.

- Modular Monolith: Instead of chasing microservices, you work within a modular structure where AI can easily "reason" about dependencies via our Dependency Injection (Awilix).

> "A mono repository structure simplifies AI-assisted engineering by making context management easier."

### Use AGENTS.MD as Your AI’s North Star

The most critical file for any developer in Open Mercato is agents.md. This is the "manual" you feed your LLM.

- The Content: It contains coding conventions, architectural decisions, and the Extensibility Contract (OCP).

- The Practice: Before starting a task, point your agent (e.g., via @agents.md in Cursor) to this file. It prevents the AI from "hallucinating" patterns and ensures it uses our built-in helpers.

> "The agents.md file specifies guidelines for agent encoding, architecture decisions, coding conventions, and patterns."

Source: Open Mercato website content

### Mastering the "Specification Loop"

Do not start by asking the AI to "write code." Start by asking it to challenge your logic.

- Logical Auditing: Use high-reasoning models (like Claude 3.5 Sonnet or Codex) to find gaps in your feature request.

- Example: When implementing an "Order Status History," first ask the AI: "Based on the existing Action Log pattern in Open Mercato, how should I track status changes without duplicating data?"

- Markdown API Specs: Open Mercato provides markdown specifications of the API. Pasting these into an LLM saves tokens and ensures the AI understands the exact authorization and data requirements.

### Leveraging the Overlay System (The "Safety Net")

One of the biggest risks with AI code is breaking the core system. Open Mercato uses an Overlay System based on the Open-Closed Principle (OCP).

- How it works: You never modify the core files (distributed via NPM). Instead, you instruct the AI to create overrides in the overlay directory.

- Learning Point: Practice telling the AI: "I need to change the validation logic for the Contact entity. Use the Overlay pattern to override the core service without modifying the original package."

> "Open Mercato is not a 'code generator'; it is a foundation framework… AI is used to accelerate the population of this proven structure, not to reinvent the wheel every time."

Source: Open Mercato FAQ

### Technical Guardrails: Types and Commands

To ensure the AI produces production-grade code, Open Mercato enforces strict technical patterns:

- Zod & TypeScript: The AI is forced to adhere to strict schemas. If the AI generates a field that doesn't exist, the TypeScript compiler (and the AI itself) will catch it immediately.

- Command Pattern: Every write operation is a "Command." This makes it easy for the AI to implement "Undo/Redo" and "Audit Logs" automatically, as the pattern is consistent across the entire framework.

### Implementation Workflow (The "Pro" Routine)

To learn effectively, follow this 4-step workflow:

- Initialize: Run yarn mercato init to have a living, breathing system with sample data.

- Prompt the Pattern: Ask the AI to find an existing pattern (e.g., "How does the CRM module handle many-to-many relationships?").

- Generate with Overlay: Have the AI generate the new module or field in the overlay layer.

- Verify via Playwright: Use AI to generate E2E tests in Playwright to verify the new feature works as expected.

## What AI-assisted engineering requires from you

AI-assisted coding with Open Mercato significantly reduces "commodity" work, but it requires a developer who understands Software Architecture. If you don't understand Dependency Injection or the Open-Closed Principle, you might still struggle with complex customizations. We recommend studying our Architecture Webinar notes to understand the "Request Flow" before deep-diving into AI generation.

## Software is about to be built completely differently.