Writing Specs for Parallel AI Coding Agents: The CLAUDE.md Approach

1. The Spec-Driven Development Shift

The traditional software development loop is: think about what to build, write the code, test it, iterate. With AI coding agents, the loop changes: think about what to build, write a detailed spec, hand it to an agent, review the output. The spec becomes the primary artifact that the human produces.

This shift is more profound than it sounds. Writing a good spec requires many of the same skills as writing good code: precision, completeness, anticipating edge cases. But it also requires a different kind of thinking. Instead of solving the problem directly, you are communicating the problem clearly enough that an AI can solve it. This is closer to technical writing or architecture documentation than traditional programming.

The CLAUDE.md pattern (named after the convention used with Claude Code) is a markdown file that sits at the root of your repository and provides persistent context to AI agents. It includes project conventions, architectural decisions, common patterns, and explicit rules. Every agent that works on the codebase reads this file first, establishing a shared understanding of how the project works.

Think of CLAUDE.md as onboarding documentation for an infinitely patient new hire who follows instructions exactly but has no institutional knowledge. The more precise your CLAUDE.md, the less time you spend correcting agent mistakes. Teams that invest heavily in their CLAUDE.md file report that agent output quality improves significantly because the agents stop making decisions that violate project conventions.

2. Anatomy of an Effective Agent Spec

A good spec for an AI coding agent has several distinct sections, each serving a specific purpose.

Context Section

Start with what the agent needs to know about the current state of the codebase. Which files are relevant? What existing patterns should it follow? What recent changes might affect its work? Do not assume the agent remembers anything from previous sessions. Each spec should be self-contained.

Requirements Section

Be explicit about what you want. "Add a user settings page" is too vague. "Create a new route at /settings that renders a form with fields for display name (text input, max 50 chars), email notifications (toggle, default on), and theme preference (dropdown: light, dark, system). Use the existing FormField component from src/components/form-field.tsx. Save changes via the PATCH /api/user endpoint" is specific enough for an agent to execute without ambiguity.

Constraints Section

List what the agent should NOT do. "Do not modify any files outside the src/settings/ directory. Do not add new dependencies. Do not change the existing API schema." Negative constraints are often more important than positive requirements because agents will sometimes take creative liberties that break other parts of the system.

Verification Section

Describe how to verify the work is correct. "Run npm test. All existing tests should pass. Add tests for the new settings form that cover: initial render with default values, form submission with valid data, and form submission with validation errors." This gives the agent a built-in feedback loop.

3. Parallelizing Agent Work Without Conflicts

The biggest challenge with multiple agents working simultaneously is file conflicts. Two agents editing the same file will produce merge conflicts, and resolving merge conflicts from AI-generated code is tedious and error-prone.

The primary strategy is task decomposition by file boundary. Each agent gets a spec that touches a disjoint set of files. Agent A works on the settings page (src/settings/). Agent B works on the notification system (src/notifications/). Agent C writes API tests (tests/api/). No overlap, no conflicts.

When file overlap is unavoidable, use a sequential approach for the overlapping files. Have Agent A complete its work first, then give Agent B an updated spec that accounts for Agent A's changes. This is slower than full parallelism but avoids the merge conflict problem entirely.

Another effective pattern is the interface contract approach. Define shared interfaces (types, API contracts, function signatures) in a spec that one agent implements first. Then give the remaining agents specs that depend on those interfaces. Each agent can work independently against the agreed contract.

For desktop automation tasks (as opposed to coding tasks), parallelism is simpler because agents typically work with different applications or different windows. A Fazm agent extracting data from a spreadsheet does not conflict with another agent composing an email. The key constraint for desktop agents is that only one agent can control the mouse and keyboard at a time, though accessibility API-based agents can often work with specific application windows without needing exclusive input control.

4. Review Patterns for Multi-Agent Output

Reviewing code from multiple agents requires a different approach than reviewing code from human developers. Agents produce code quickly, so the bottleneck shifts to review quality.

Automated checks should catch the mechanical issues: linting, type checking, test execution, and code style. Configure these as pre-commit hooks or CI checks so agents can self-correct before human review. The human reviewer should focus on architectural fit, correctness of business logic, and whether the code actually solves the right problem.

Use AI-assisted code review to scale. One AI agent reviews another's code. This sounds circular, but in practice a review-focused agent with access to the full spec and codebase context catches many issues that the implementing agent missed. The cost is minimal (a few cents per review versus $15 to $25 for a human reviewer), and it surfaces the most important issues for human attention.

Batch your reviews. Instead of reviewing each agent's output as it arrives, wait until all parallel agents complete their tasks, then review the combined diff. This gives you a holistic view of the changes and makes it easier to spot inconsistencies between different agents' implementations.

5. Tooling and Workflow Automation

Several tools support the parallel agent workflow. Claude Code with worktrees lets you run multiple agents on separate git worktrees of the same repository, avoiding file conflicts at the filesystem level. Each agent gets its own working copy and its own branch.

For task management, keep a simple markdown file that lists each agent's assignment, its branch, and its current status. This serves as a human-readable dashboard for the multi-agent workflow. Automated status checks (did the tests pass? is the agent still running?) can update this file periodically.

Template your specs. If you find yourself writing similar specs repeatedly, create a template with the common sections pre-filled. The context section can reference your CLAUDE.md file. The constraints section can include standard rules. The verification section can include your standard test commands. You only need to write the requirements section from scratch each time.

Beyond coding, the spec-driven approach applies to desktop automation tasks too. Instead of writing scripts to automate repetitive Mac tasks, you can write a spec describing what needs to happen and let a desktop agent (like Fazm) execute it. The spec might describe: "Open the monthly report spreadsheet, copy the summary row, paste it into the email template, and send it to the distribution list." The agent interprets the spec and handles the mechanical details.