Introduction
What this wiki is, how it's organised, and why Aircury's engineering team built it.
This wiki started as a place for Aircury’s engineering team to document what we actually know about building software with AI — not as a set of rules to follow, but as a shared reference we can point to, challenge, and improve over time.
Working well with AI isn’t just about making the code meet its requirements. It also has to be maintainable, testable, and coherent enough that someone can still understand it a year from now. This wiki covers both sides.
Who this is for
Every engineer at Aircury — whether you’re just starting with AI coding assistants, or you’re already building LLM systems in production. You’ll find both how we work (methodology and good practices) and what we know (AI engineering fundamentals).
Three pillars
The wiki is organised around three complementary blocks:
🔌 Pillar 0 — Integrations
Practical guides for integrating AI capabilities into your stack. Language-specific implementations, SDKs, and frameworks that we use at Aircury.
| Page | What it covers |
|---|---|
| Overview | When to choose which stack and integration approach |
| TypeScript | AI SDK, Mastra, and the Vercel ecosystem |
| PHP | Neuron AI and Symfony AI for PHP applications |
| Python | Pydantic AI, LangGraph, and the Python AI stack |
🏗️ Pillar 1 — The Framework
Our extension of OpenSpec — Spec-Driven Development with quality criteria built in. This is how we build software at Aircury.
The problem it addresses: AI coding assistants are powerful, but without guidance they produce code that meets requirements and is architecturally a mess. The Framework gives the agent the context it needs — DDD, Hexagonal Architecture, SOLID, testing pyramid, conventional commits — so that generated code isn’t just correct, it’s solid.
| Page | What it covers |
|---|---|
| Methodology | The full OpenSpec Extended cycle and the spec-to-test idea |
| Architecture | DDD + Hexagonal Architecture and why they matter with AI |
| SOLID Principles | Five principles that steer the agent towards maintainable code |
| Testing Strategy | The testing pyramid, Gherkin/BDD, and the rebuildable codebase |
| Quality Guardrails | Conventional commits, determinism rules, and AI code review |
| Playbooks | Day-to-day workflows, agent configuration, troubleshooting |
🧠 Pillar 2 — AI Engineering
The foundational knowledge any engineer needs to work well with AI systems. This is what we know as a team.
| Page | What it covers |
|---|---|
| Foundations | What AI Engineering is, the LLM landscape, mental models |
| Prompt Engineering | Zero-shot, few-shot, CoT, role prompting, structured output |
| Evaluation & Evals | How to measure AI system quality systematically |
| AI Agents | Tool use, ReAct, multi-agent systems, reliable agent design |
| RAG | The full Retrieval-Augmented Generation pipeline |
| Fine-Tuning | When and how to customise models beyond prompting |
| Operations (LLMOps) | Monitoring, cost management, reliability patterns |
The thinking behind it
The problem with specs alone
If you only define what to build, AI will fulfil the specs — but may do so with a tangled, untestable implementation that’s hard to scale. Specs are necessary, but not sufficient on their own.
The answer is combining three layers:
Specs (the contract)
OpenSpec specs define what the system must do, not how. They’re the agreement between human intent and the agent’s implementation. Written well, they also become the input for the BDD test layer.
Tests (the validation)
A full testing pyramid — Unit, Integration, and Behavioural (Gherkin/BDD) — validates that specs are met. More importantly, tests mean the implementation can change without breaking the behaviour.
Rules (the architecture)
The quality guardrails — DDD, Hexagonal Architecture, SOLID, conventional commits — shape how AI builds the implementation. This is where determinism gets introduced into a tool that doesn’t have it by default.
The result is a codebase where specs + tests + rules makes the implementation less dependent on itself. If something needs to be rewritten — or heavily refactored — the contract is still there. Specs say what it does. Tests validate that it holds. Architecture defines how it’s built.
How to use this wiki
Start with the pillar most relevant to what you’re working on:
- Picking an AI stack? → Start with Integrations Overview
- New to the Framework? → Start with Methodology
- Reviewing AI-generated code? → Go to Quality Guardrails
- Building with LLMs? → Start with Foundations
- Implementing RAG? → Jump straight to RAG
Each page is a standalone reference, so you can read them in any order once you have the overview above.