5 Parallel Agents on One Codebase - CLAUDE.md Specs Are the Only Coordination That Works

Fazm Team··2 min read

After a year of using AI to write 100% of my code, the biggest lesson is not about the model - it is about the context you give it. Put CLAUDE.md specs and skills files directly in the repo, and 5 agents running in parallel on the same codebase all just know what to do.

The Repo Is the Spec

Traditional development has specs in Notion, Jira, Confluence - anywhere except the codebase itself. When you are running multiple AI agents, this breaks immediately. Each agent needs to understand the project conventions, architecture decisions, and current priorities without asking.

The fix is obvious in retrospect - put everything in the repo. CLAUDE.md files at the root and in subdirectories. Skills files that define common operations. Convention docs that specify naming patterns, file organization, and testing requirements.

Why Parallel Agents Need Better Specs

A single agent session can get by with mediocre context. You are watching it, correcting it, guiding it. Five parallel agents cannot get that level of attention. They need to be self-sufficient.

This means the specs need to be precise enough that an agent can:

  • Find the right files to modify without searching the whole codebase
  • Follow existing patterns without being told what they are
  • Avoid conflicts with other agents working on different features
  • Know which tests to run and what success looks like

The Time Investment Shifts

I now spend more time writing specs than writing code. A well-written CLAUDE.md specification for a feature takes 30-45 minutes. The agent implements it in 10-15 minutes. Five agents running in parallel can ship a day's worth of features in under an hour - but only if the specs are right.

This is a real skill shift. The value is in decomposing problems, defining interfaces, specifying edge cases, and writing acceptance criteria. The typing is the easy part.

What Goes in the Repo

  • Root CLAUDE.md with project conventions and architecture
  • Per-directory CLAUDE.md files with local context
  • Skills files for repetitive operations
  • Examples of correct patterns for the agent to follow

Fazm is an open source macOS AI agent. Open source on GitHub.

More on This Topic

Related Posts