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."
Source: Ai coding om short.txt
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.