Parallel AI agents need a contract first

A developer built a fitness-coach attendance app using Claude as an orchestrator directing four parallel agents, each assigned exclusive ownership of a set of files and barred from editing shared files. The foundation commit, containing no features, established shared types and stubs before any code was written; the first full version followed 16 minutes later with 53 files and roughly 8,900 lines, including backend tests run against an in-memory database. The developer's takeaway is that shared contracts and file-level ownership eliminate merge conflicts, leaving the human to define the shape, rules and definition of done.

In the previous note https://kamilkolodziejczyk.dev/notes/why-i-did-not-integrate-with-messenger I wrote about why the attendance app for a fitness coach skips Messenger. This one is about how it was built: with Claude, as one orchestrator and four agents working on separate parts of the app at the same time. The interesting part is not that agents wrote code. It is what had to exist before they started. The first commit contains no features. It contains: There were four agents: the backend, the public check-in screen, the coach's training panel, and participants with statistics. Each one owned a set of files and was not allowed to edit anything outside it. If an agent needed a change in a shared file, it described the change in its final report instead of making it. This removes the problem that breaks parallel work: two agents editing the same file with different assumptions. There was nothing to merge. Conflicts came back as notes in the reports, where they could be decided on purpose. The commit with the first full version, with the backend, check-in, training panel, participants and statistics, landed 16 minutes after the foundation commit: 53 files and about 8,900 lines. The backend came with tests that call the API against an in-memory database. The very next commit removed comments from 59 files and moved the list of endpoints into a single API document. After that came the parts that turn a working version into something a real person can rely on: Agents are fast at filling in a well-defined shape. Deciding the shape, the rules and what "done" means is still the job. Contract first. Shared types are the cheapest way to make four agents agree without talking to each other. Ownership instead of merging. Split the work by files, not by tasks that touch the same files. Business rules in writing. Every rule in the plan is a question an agent does not have to guess. Stubs as a map. An empty screen with an owner tells an agent exactly where to work and where to stop. Originally published on kamilkolodziejczyk.dev https://kamilkolodziejczyk.dev/notes/parallel-ai-agents-need-a-contract-first .