The AI Doesn't Replace Engineering Discipline. It Demands It.

I built Escribano 100% with AI agents in 3 weeks. Zero architectural rewrites. Two hallucinations caught in testing.

Most people think AI makes engineering easier. Here’s what I learned: AI doesn’t replace engineering discipline — it makes it MORE valuable.

An AI agent doesn’t share your history. Every session starts fresh. Everything you know — every pattern, every hard-won lesson — has to live somewhere it can read. Otherwise it guesses. And guesses compound into architectural drift.

The Docs the AI Actually Reads

My opencode.json loads three files at the start of every session:

"instructions": ["README.md", "AGENTS.md", "BACKLOG.md"]

AGENTS.md is the key one — not documentation for future engineers, but the AI’s onboarding doc. Architecture, conventions, pipeline flow. Every session, the agent reads it before writing a line. For deeper context, docs/architecture.md. For why decisions were made, ADRs in docs/adr/.

This is just how senior engineers work. You write things down so the next person doesn’t have to reconstruct intent from code. The AI is just the most extreme version of “next person” — zero memory, zero assumed context.

The feedback loop compounds:

Good docs → AI makes better decisions → AI updates docs → Better docs

Versus what happens without it:

No docs → AI guesses → Inconsistent code → Harder to fix → More guessing

The Multi-Model Strategy

One model for everything is the wrong mental model — for the same reason you don’t use a senior architect to write boilerplate.

This mirrors Escribano’s own architecture: VLM inference on MLX-VLM, LLM summary on Ollama. Different models, different tradeoffs, clean interfaces between them. The port/adapter pattern isn’t just in the product — it’s in how you build it.

The Numbers

• 3 weeks from zero to production-ready
• ~200 commits, ~5000 lines of code
• 0 architectural rewrites
• 2 hallucinations caught in testing (documented in ADRs)
• 6 VLM approaches benchmarked, each requiring one new adapter file

The key metric: zero business logic touched during any infrastructure swap. That’s the return on architectural discipline.

Subagents with Constrained Permissions

Two custom agents do specialized work:

• Researcher (deepseek-chat): Read-only research using Firecrawl. Can’t touch files.
• Reviewer (deepseek-reasoner): Read-only code review. Runs git diff, git log, grep. Cannot modify files.

The reviewer can’t write code. That’s the design. Giving a review agent write permissions is the same failure mode as giving one engineer both greenfield and review authority over their own work. Single responsibility applies to AI workflows too.

Every feature goes through a pull request — AI reviews first, then me. The AI catches what I miss under time pressure. I catch what the AI misses in domain context. This isn’t new process; it’s just PR discipline, which I’d follow anyway.

Why the Architecture Never Drifted

The port/adapter pattern made the whole thing work. I knew I’d be evaluating multiple VLM approaches — the architecture had to make swapping cheap.

I benchmarked six different VLM approaches. Each required one new adapter file. Zero business logic touched.

One convention kept the AI from drifting: 0_types.ts is the single source of truth for all domain types and interfaces. There’s only one place type definitions belong, so they can’t be scattered.

┌─────────────────────────────────────────────────────────────────┐
│                     INFRASTRUCTURE (Adapters)                   │
│   MLX-VLM │ Whisper │ FFmpeg │ Ollama │ Silero │ Capture        │
├─────────────────────────────────────────────────────────────────┤
│                     APPLICATION (Use Cases)                     │
│   ProcessRecording → SegmentActivities → GenerateSummary        │
├─────────────────────────────────────────────────────────────────┤
│                       DOMAIN (Core)                             │
│   Recording, Observation, TopicBlock, Artifact                  │
│   0_types.ts: single source of truth                            │
└─────────────────────────────────────────────────────────────────┘

The Bug That Became a Permanent Constraint

During testing I caught a hallucination. summary-v3.md had only 3 of 6 template variables filled — the LLM saw the empty placeholders, found an example block in the prompt, and invented matching details to fill them.

I documented it in architecture.md. Now every agent that reads it knows not to repeat that mistake. One testing catch became a permanent architectural constraint — which is exactly what ADRs are for.

The difference is the audience: it’s not future engineers. It’s the AI working on it right now.

What This Means for Teams

Junior engineers using AI will produce senior-level volume but junior-level architecture — unless you make the architecture explicit. The documentation burden shifts from “nice to have” to “critical infrastructure.”

Code review becomes more important, not less. The AI catches syntax and logic errors. You catch architectural drift and domain mismatches.

The engineers who thrive will be the ones who can articulate patterns clearly, not just implement them. AI turns tacit knowledge into a competitive advantage.

Where This Approach Fails

This isn’t a silver bullet:

• Greenfield projects with no existing patterns to encode — the AI has nothing to learn from
• Rapid prototyping where you don’t know the architecture yet — you’re exploring, not executing
• Novel domains where the AI lacks training data — it can’t extrapolate beyond its knowledge

For everything else, the pattern holds: explicit architecture + AI execution = consistent velocity.

Engineering discipline transfers to AI-assisted development. But only if you make it legible — written down somewhere a stateless agent can find it before it writes a single line.

Try it. Document your architecture for an AI audience. Then see if your code doesn’t drift.

Escribano is open-source — built 100% with AI agents, following Clean Architecture throughout.

• GitHub · Architecture docs · ADRs · AGENTS.md