You know the story. An AI project starts as a Jupyter notebook. Then it becomes a Python script. Then a folder of scripts. Then a monorepo with a vague directory structure. After three months a new developer asks "where does the business logic live?" and nobody can answer.
This is not an inevitable fate. It is the result of not thinking about repo structure at the moment it matters most: the beginning.
The problem
AI agent projects are inherently complex. You have agent logic (prompts, tools, flows). You have integrations (channels, APIs, databases). You have infra (deployment, monitoring, secrets). You have shared utilities (logging, auth, config). And you have more and more agents as the project grows.
Without structure, this grows organically. Agent A has its own logger. Agent B has a copy of the same logger with a minor tweak. The email integration lives half in the agent directory and half in a utils directory. The Kubernetes configs sit in a folder called "deploy" that nobody dares to touch anymore.
After six months the codebase is a mess. Not because anyone did bad work, but because there was no structure that anticipated growth.
What good structure means for agent projects
An agent repo has different needs than a typical web app. The structure needs to account for:
Multiple agents that evolve independently. Agent A gets updated more often than agent B. They need to be independently deployable, with their own versioning and their own CI/CD pipelines. But they share the same foundation: the same auth layer, the same logging, the same channel adapters.
Shared logic that does not get duplicated. Config handling, logging, LLM client wiring, auth — these are things that are identical across all agents. They belong in a shared package, not copied into every agent directory.
Infra that scales with you. With one agent, a single Dockerfile is enough. With five agents, you need Helm charts with per-agent values, shared runtime configs, and CI/CD that knows which agent needs rebuilding when shared logic changes.
Clear boundaries. At any point it should be obvious: this is agent logic, this is platform logic, this is infra. Those boundaries prevent changes in one domain from having unexpected effects in another.
How we structure it
Our platform generates a repo structure that fits how multi-agent platforms actually grow:
The root contains platform-level configuration: CI/CD workflows, Kubernetes base charts, and shared environment configuration. Nothing agent-specific lives here.
A packages layer contains shared logic: the SDK with logging, auth, channel adapters, LLM clients, and vector store helpers. This changes rarely and is the foundation for everything above it.
Each agent lives in its own workspace with its own dependencies, its own Dockerfile, its own Helm values, and its own CI/CD trigger. Agents are first-class citizens in the repo, not subdirectories of a monolith.
Infra is separated from application code. Kubernetes charts, Docker configs, and deploy workflows live apart. They reference agents but are not part of agent code.
Why this difference matters
On day one, repo structure does not matter. Everything fits in a single folder. You notice the difference on day ninety.
When you want to add a third agent and it takes twenty minutes instead of two days. When a junior developer opens the codebase and understands what lives where within an hour. When you want to update one agent without risk to the others. When your CI/CD pipeline knows that only the changed agent needs rebuilding, not everything.
Structure is not exciting. It does not land demos and it does not impress stakeholders. But it is the difference between a project that can still be developed after six months and a project that needs a rewrite after six months.
And in AI projects, where the technology moves fast and you regularly want to swap models, prompts, and tools, that difference is everything.