parallel-dev

Run multiple AI coding agents on the same codebase without merge conflicts.

Quick Start • The Problem • The Solution • Frameworks • Docs • Contributing

---

The Problem

When you run 3-8 AI coding agents (Claude Code, Cursor, Devin, Aider) developing features simultaneously, certain files become convergence points that every feature must edit:

src/models/index.js           <-- Every feature adds require() here
src/models/associations.js    <-- Every feature adds relationships here
server/loaders/services.js    <-- Every feature adds imports here
src/routes/index.js           <-- Every feature registers routes here

Result: Guaranteed merge conflicts. Every time. Even though the features are completely independent.

The Solution

Refactor convergence-point files once to auto-discover modules at startup. Then each AI agent creates only its own files -- never editing shared ones.

BEFORE: 5 features -> 5 edits to index.js -> merge conflict hell
AFTER:  5 features -> 5 new files dropped in -> zero conflicts

Quick Start

Option 1: Scaffold your project

npx parallel-dev init

This scans your project and creates the auto-discovery directories and templates.

Option 2: Manual setup

# Clone the repo
git clone https://github.com/drjc1001/parallel-dev.git

# Copy the patterns you need into your project
cp -r parallel-dev/templates/express-sequelize/* your-project/

What It Does

parallel-dev init creates this structure in your project:

your-project/
|-- src/models/associations/          <-- NEW: Drop-in model relationships
|   +-- README.md
|-- src/service-registrations/        <-- NEW: Drop-in service imports
|   +-- README.md
|-- specs/                            <-- NEW: Test-first specs for AI agents
|   +-- README.md
|-- scripts/
|   +-- integration-test.sh           <-- NEW: Run all feature tests
|-- docs/
|   +-- ai-agent-template.md          <-- NEW: Instructions for AI agents
+-- .feature-status.json              <-- NEW: Progress tracker

Then you refactor your 4 convergence-point files using the provided patterns (see Refactoring Guide).

How It Works

1. Auto-Discovery Model Registry

Instead of manually requiring every model:

// BEFORE -- every feature edits this
const User = require('./User');
const ChatFlow = require('./ChatFlow');     // Feature A adds
const WidgetConfig = require('./WidgetConfig'); // Feature B adds
module.exports = { User, ChatFlow, WidgetConfig };

// AFTER -- never edited again
fs.readdirSync(__dirname)
  .filter(f => f.endsWith('.js') && f !== 'index.js')
  .forEach(file => {
    const model = require(path.join(__dirname, file));
    if (model?.name) models[model.name] = model;
  });

2. Plugin-Style Associations

Instead of one giant associations file:

src/models/associations/
|-- orders.associations.js        <-- Feature A owns this
|-- notifications.associations.js <-- Feature B owns this
+-- billing.associations.js       <-- Feature C owns this

Each file exports a function:

// orders.associations.js
module.exports = (models) => {
  const { Company, Order } = models;
  if (!Order) return; // Guard clause
  Company.hasMany(Order, { foreignKey: 'company_id' });
};

3. AI Agent Isolation

Give each Claude Code instance clear boundaries:

Files you CREATE (your ownership):
   src/models/MyModel.js
   src/models/associations/my-feature.associations.js
   src/services/my-feature.service.js
   src/routes/my-feature.routes.js

Files you NEVER edit:
   src/models/index.js
   src/models/model-associations.js
   server/loaders/services.js

Zero conflicts. Every time.

Supported Frameworks

Framework	Status	Template
Express + Sequelize	Ready	templates/express-sequelize/
Express + Mongoose	Ready	templates/express-mongoose/
Flask + SQLAlchemy	Ready	templates/flask-sqlalchemy/
Django	Guide	docs/django-guide.md
NestJS	Guide	docs/nestjs-guide.md
Go + Gin	Guide	docs/go-gin-guide.md

Django and NestJS already have modular architectures -- see their guides for how to enforce feature isolation with AI agents.

Git Branch Strategy

main (production) ---------------------------------------- deploy
  |                                                          ^
  +-- stage (integration) -----------------------------------+
        |-- feature/feature-a     <-- AI Agent #1
        |-- feature/feature-b     <-- AI Agent #2
        |-- feature/feature-c     <-- AI Agent #3
        +-- feature/feature-d     <-- AI Agent #4

Features merge to stage one-by-one (no conflicts), test on staging, then batch-merge to main.

You only need ONE staging environment. Features are additive, not conflicting.

Recommended: Use with Git Worktree

Auto-discovery prevents file conflicts (agents don't edit shared files). Git worktree prevents folder conflicts (agents don't share a working directory). Together, they eliminate merge conflicts entirely.

Problem: Two agents edit the same FILE   --> auto-discovery solves this
Problem: Two agents work in the same DIR --> git worktree solves this

Setup: One Worktree Per AI Agent

cd ~/project
git checkout stage

# Create isolated folders for each agent
git worktree add ../project-feat-a -b feature/orders stage
git worktree add ../project-feat-b -b feature/widget stage
git worktree add ../project-feat-c -b feature/notifications stage

Now each AI agent gets its own folder and branch:

~/project/              <-- main repo (stage)
~/project-feat-a/       <-- Terminal A: feature/orders
~/project-feat-b/       <-- Terminal B: feature/widget
~/project-feat-c/       <-- Terminal C: feature/notifications

All folders share the same git history. No cloning. No push/pull between them.

Merge and Clean Up

# When features are done, merge one by one (no conflicts)
cd ~/project
git checkout stage
git merge feature/orders          # clean -- only its own files
git merge feature/widget          # clean -- no overlapping files
git merge feature/notifications   # clean

# Test on staging, then promote to production
git checkout main && git merge stage && git push origin main

# Remove worktrees
git worktree remove ../project-feat-a
git worktree remove ../project-feat-b
git worktree remove ../project-feat-c

Bug Fixes After Cleanup

Old branches are gone and that's fine. Create a new branch from current code:

# Normal bug fix (goes through staging)
git worktree add ../project-fix -b fix/order-calculation-bug stage

# Urgent hotfix (deploy to production immediately)
git worktree add ../project-hotfix -b hotfix/crash-fix main
# ... fix, merge to main, deploy, then backport to stage

Branch Naming Convention

Prefix	Purpose	Branch from
feature/xxx	New feature	stage
fix/xxx	Bug fix (test on staging first)	stage
hotfix/xxx	Urgent production fix	main

Documentation

• Refactoring Guide -- Step-by-step guide to apply auto-discovery to your existing codebase
• AI Agent Template -- Copy-paste instructions for Claude Code / Cursor / Devin
• Framework Adapters -- Patterns for Express, Flask, Django, NestJS, Go
• Before & After -- Real-world transformation examples
• Testing Strategy -- Spec-first TDD for AI agents
• FAQ -- Common questions

Use as a Claude Skill

This repo can be used as a Claude Skill for Claude Code:

# Add to your Claude project as a skill
cp -r parallel-dev /mnt/skills/user/parallel-ai-dev

When a user asks Claude to set up parallel development, Claude reads the SKILL.md and applies the patterns automatically.

Contributing

Contributions are welcome! Whether it's a bug fix, a new framework adapter, or documentation improvements.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

See CONTRIBUTING.md for detailed guidelines.

License

This project is licensed under the MIT License -- see the LICENSE file for details.

Acknowledgments

This project was born from real-world experience running multiple Claude Code instances in parallel on the same Node.js/Express/Sequelize codebase. Merge conflicts on shared registration files kept blocking progress. The auto-discovery pattern eliminated the problem entirely.

---

_{If this saved you from merge conflict hell, consider giving it a star.}