Skip to content
🤖 Consolidated, AI-optimized BMAD docs: llms-full.txt. Fetch this plain text file for complete context.
BMAD Method BMAD Method BMAD Method

Preventing Agent Conflicts

When multiple AI agents implement different parts of a system, they can make conflicting technical decisions. Architecture documentation prevents this by establishing shared standards.

Common Conflict Types

Section titled “Common Conflict Types”

API Style Conflicts

Section titled “API Style Conflicts”

Without architecture:

  • Agent A uses REST with /users/{id}
  • Agent B uses GraphQL mutations
  • Result: Inconsistent API patterns, confused consumers

With architecture:

  • ADR specifies: “Use GraphQL for all client-server communication”
  • All agents follow the same pattern

Database Design Conflicts

Section titled “Database Design Conflicts”

Without architecture:

  • Agent A uses snake_case column names
  • Agent B uses camelCase column names
  • Result: Inconsistent schema, confusing queries

With architecture:

  • Standards document specifies naming conventions
  • All agents follow the same patterns

State Management Conflicts

Section titled “State Management Conflicts”

Without architecture:

  • Agent A uses Redux for global state
  • Agent B uses React Context
  • Result: Multiple state management approaches, complexity

With architecture:

  • ADR specifies state management approach
  • All agents implement consistently

How Architecture Prevents Conflicts

Section titled “How Architecture Prevents Conflicts”

1. Explicit Decisions via ADRs

Section titled “1. Explicit Decisions via ADRs”

Every significant technology choice is documented with:

  • Context (why this decision matters)
  • Options considered (what alternatives exist)
  • Decision (what we chose)
  • Rationale (why we chose it)
  • Consequences (trade-offs accepted)

2. FR/NFR-Specific Guidance

Section titled “2. FR/NFR-Specific Guidance”

Architecture maps each functional requirement to technical approach:

  • FR-001: User Management → GraphQL mutations
  • FR-002: Mobile App → Optimized queries

3. Standards and Conventions

Section titled “3. Standards and Conventions”

Explicit documentation of:

  • Directory structure
  • Naming conventions
  • Code organization
  • Testing patterns

Architecture as Shared Context

Section titled “Architecture as Shared Context”

Think of architecture as the shared context that all agents read before implementing:

PRD: "What to build"
     ↓
Architecture: "How to build it"
     ↓
Agent A reads architecture → implements Epic 1
Agent B reads architecture → implements Epic 2
Agent C reads architecture → implements Epic 3
     ↓
Result: Consistent implementation

Key ADR Topics

Section titled “Key ADR Topics”

Common decisions that prevent conflicts:

TopicExample Decision
API StyleGraphQL vs REST vs gRPC
DatabasePostgreSQL vs MongoDB
AuthJWT vs Sessions
State ManagementRedux vs Context vs Zustand
StylingCSS Modules vs Tailwind vs Styled Components
TestingJest + Playwright vs Vitest + Cypress

Anti-Patterns to Avoid

Section titled “Anti-Patterns to Avoid”