--- number: 123 lang: en title: "Works as Designed: Why Repo Structure and Architecture Matter" date: 2026-10-16 stability: stable review_by: 2028-10-16 author: "Stefan Wendel" coauthor: "Claude Opus 5.5" coauthor_id: claude-opus-5-5 --- # Works as Designed: Why Repo Structure and Architecture Matter **The 1-n rule: one business repo, n working repos, and every working repo points back to the business repo.** 2026-10-16 · Stefan Wendel · Claude Opus 5.5 ---
A living room: a freshly assembled wardrobe leans clearly to one side. Next to it lies a heap of leftover parts, half as tall as the wardrobe: stacked boards, a whole door, a shelf, a bag of screws, screws and dowels everywhere. A couple stands arm in arm in front of it, looking contentedly at their work.
“It works. The leftover parts were probably just architecture.”
At 1001lessons.io several agents work on the code every day: analysis, new features, fixes, quality scans. So that they don't have to guess every time where to find something or how something works, our repo setup is deliberately simple. **One business repo for everything cross-cutting**, structured like a small company: - `product/` – specification, architecture, prototypes, runbooks, decisions - `marketing/` – positioning, audiences, copy, videos - `strategy/` – operating model, principles, stances, risks **One working repo per subdomain and/or component**: backend core, frontend, API contracts (OpenAPI), infrastructure, landing page, blog. Each of these working repos has its own `CLAUDE.md`: what is this repo, which docs live here (and not in the business repo), and where does the agent find everything else? The last point is the "link-back" from [#0120](/en/120). **Docs belong in the working repos.** There is a simple rule of thumb: everything that changes in the same pull request as the code belongs in that repo. That is why all of our nearly 60 ADRs (Architecture Decision Records) live in the core repo: they are decisions about the core. The frontend has its own ADRs, because they concern only the frontend. Coding guidelines, threat model, IAM docs: each lives where its code lives. This is what [Shift Into](/en/101) means: docs become part of the code, and ultimately they have to live with the code. The business repo follows the same rule. What changes with no single piece of code – product decisions, specification, marketing, strategy – belongs there. **Structure your repos by domain, so agents find their way more easily.** What makes life easier for us humans makes it easier for agents too. Domain-Driven Design gave us good ideas on how to cut complex software products so that you can find your way around them. We apply these principles here as well, against the claim that AI will soon write binaries directly and structure won't matter ([Elon Musk, early 2026](https://hackernoon.com/elon-wants-ai-to-skip-code-and-spit-out-binaries-thats-not-progress)). Good architecture principles help to set up a clean structure and – almost more important – to keep to it consistently during development. The more code AI generates, the more a clear, consistently enforced basic structure matters. Ours is written down in our coding guidelines and checked by [ArchUnit](https://www.archunit.org/) on every build; step by step, module by module, currently for billing, pricing and erasure. Concretely: - *Domain-Driven Design:* packages by domain instead of technical layers, such as `domain/auth`, `domain/accesscontrol`, `domain/erasure`. - *Ports and Adapters* (onion architecture): the domain in the middle, everything external around it, such as `portsadapters/slackapi`, `portsadapters/stripe`, `portsadapters/cognito`. The domain knows neither Slack nor Stripe. An example: an agent asked to change erasure requests lands in `domain/erasure` without searching. The diff stays small and in one place. **And when several agents work at the same time?** Then each gets its own git worktree with its own port slot. That's a topic of its own: [#0119 git worktree Is Not Enough](/en/119). **The lesson:** Docs live where they change, and every repo says in its `CLAUDE.md` where the rest lives. Docs are code: [Shift Into](/en/101).