# Running AI Agents on a Production Codebase [Tomas Parizek](https://www.strv.com/blog/authors/tomas-parizek) iOS Engineer --- ## TL;DR AI agents can handle serious work on a production mobile codebase. The difference between agents that deliver and agents that frustrate comes down to architecture. After a year of building production apps at STRV with AI agents, we distilled what works into three layers: agent setup, verification and agent-driven planning. Get all three right and agentic development becomes a repeatable workflow. Most teams approach agentic development as a prompting problem. Write a better prompt, get better code. That framing isn't wrong, but it's incomplete. The teams doing this well in production have engineered a system around the agent: what it knows, how it verifies its own work and how they decide what to build before handing off to it. At STRV, we've spent the past year running agents on [production iOS and KMP codebases](https://www.strv.com/blog/kotlin-multiplatform-in-production-what-worked-what-didn-t). Real apps, real clients, real deadlines. What follows is what we learned. ## The Agent Only Knows What You Gave It The agent's context window is its entire world: user prompt, project instructions, skill definitions, connected tools, environment info. If your [AGENTS.md](http://agents.md) doesn't define your architecture patterns, the agent will invent its own. If it doesn't specify platform boundaries in a KMP monorepo, the agent will make changes where it guesses they make sense. If it doesn't include mandatory steps like running a build after changes, the agent will skip them. The right response isn't dumping more context in. Give an agent too much and it deprioritizes the things that matter most. We saw this directly: a 10-page AGENTS.md where critical rules on page three were consistently ignored. The approach that works is layered context. AGENTS.md stays loaded in every session, kept under 100 lines, written like a job description rather than a README. A README explains what the project is. A job description tells someone how to operate inside it. Architecture docs, domain entity definitions and coding conventions live in separate files, each referenced with a one-line trigger so the agent pulls them in only when relevant. Tools for Figma, issue trackers and databases connect at runtime, queried when needed rather than sitting passively in context. The behavioral shift that makes this compound: when the agent does something you don't like, fix the instructions rather than the output. That correction then applies to every future session automatically. ## Speed Without Verification Is a Different Kind of Problem When an agent makes changes and nothing closes the loop, it's generating code in one direction with no feedback. The situation that sharpened this for us: an agent made a change, the diff looked clean, code review passed. We ran the app, and it didn't work. The agent had verified the code. It hadn't verified the product. That distinction defines what you can and can't automate. What you can automate: compilation, tests, formatting. These should never require a human to catch. In practice, this means three things enforced in AGENTS.md: - build and test verification after every change (the single most impactful rule we've added) - automatic lint and format on every change - an AI-powered PR review via [CodeRabbit](https://www.coderabbit.ai/) on a "chill" profile: correctness only, no style opinions. For UI work, snapshot tests against Figma designs surface visual regressions before a PR is ever opened. The goal is that by the time a diff reaches you, every mechanical error is already gone and the only thing left to review is the product decision. ## How Should You Plan a Feature Before Handing It to an Agent? Layers 1 and 2 make agents better at executing tasks. Layer 3 moves the agent upstream before the task is fully defined. The standard workflow (ticket arrives, agent writes code) puts the entire burden of requirements clarity on a description that's almost never complete enough to produce the right implementation on the first pass. What we do instead: PRD -> Tech Spec -> Tasks -> Orchestrated Implementation. A feature starts with a product requirements document written with the agent, focused on user stories, objectives and scope. No code. Keeping the conversation at the product level forces ambiguity to surface early when it's cheap to resolve. From there, the agent analyzes the actual codebase and produces a technical specification grounded in the real project rather than the abstract. That spec breaks into dependency-ordered tasks, each scoped to a single agent session. Independent tasks execute in parallel using worktree isolation, with task waves gating on build and test completion before the next begins. The practical implication: when agent output is wrong, the fix is almost always in the spec, not the code. Regenerating from a corrected spec is faster than patching misaligned implementation. That only works if you have a spec to correct. ## What Changes When All Three Are in Place Each layer is doing distinct work. Setup gives the agent the knowledge it needs to operate in your specific codebase. Verification catches mechanical problems before they reach you. Planning ensures the agent is solving the right problem before writing a single line. Remove any one of them and the friction comes back somewhere else. The entry point depends on where you are. AGENTS.md is the highest-leverage hour you can spend if you haven't started yet. Mandatory build verification is the single-line change with the biggest immediate return if you're already using agents but spending too much time on cleanup. The planning workflow is where the real shift in productivity happens once your setup is solid. Build toward all three. The compounding effect is what makes it worthwhile. *Agents run fast. Your job is to point them the right way, one layer at a time.* --- ## Don't miss anything