windsurf-architecture-variants

name	windsurf-architecture-variants
description	Choose workspace architectures for different project scales in Windsurf. Use when deciding how to structure Windsurf workspaces for monorepos, multi-service setups, or polyglot codebases. Trigger with phrases like "windsurf workspace strategy", "windsurf monorepo", "windsurf project layout", "windsurf multi-service", "windsurf workspace size".
allowed-tools	Read, Grep
version	1.11.0
license	MIT
author	Jeremy Longshore <[e-mail]>
tags	["saas","windsurf","architecture","workspace","monorepo"]
compatibility	Designed for Claude Code, also compatible with Codex and OpenClaw

Windsurf Architecture Variants

Overview

How you structure your Windsurf workspace directly impacts Cascade's effectiveness. Large monorepos, multi-service setups, polyglot codebases, and different team sizes each require different approaches. This skill covers workspace strategies from solo projects to 100+ developer organizations.

Prerequisites

• Windsurf installed
• Understanding of Cascade's workspace indexing model
• Git workflow established

Instructions

Variant 1: Single Project (Solo / Small Team)

Best for: 1-3 developers, single service, <10K files.

my-project/
├── .windsurfrules          # Full project context
├── .codeiumignore          # Exclude build artifacts
├── src/
├── tests/
├── package.json
└── README.md

Configuration:

• Open entire project as workspace
• Cascade indexes everything — no partitioning needed
• .windsurfrules contains complete stack and architecture details

Variant 2: Focused Monorepo Windows (Medium Team)

Best for: 3-15 developers, monorepo with 2-10 packages.

monorepo/
├── .windsurfrules          # Brief shared conventions
├── .codeiumignore          # Aggressive exclusions at root
├── packages/
│   ├── api/
│   │   ├── .windsurfrules  # API-specific rules
│   │   └── .codeiumignore
│   ├── web/
│   │   ├── .windsurfrules  # Frontend-specific rules
│   │   └── .codeiumignore
│   └── shared/
│       ├── .windsurfrules  # Library conventions
│       └── .codeiumignore
└── .windsurf/
    └── workflows/          # Shared workflows

Strategy:

# Each developer opens their package directory:
windsurf packages/api/        # Backend dev
windsurf packages/web/        # Frontend dev
windsurf packages/shared/     # Library maintainer

# NOT: windsurf monorepo/     # Too broad!

Variant 3: Multi-Window Team Workflow (Large Team)

Best for: 15+ developers, microservices, 50K+ total files.

Developer A: Windsurf → services/auth/        (auth service)
Developer B: Windsurf → services/payments/    (payments)
Developer C: Windsurf → services/notifications/ (notifications)
Developer D: Windsurf → shared/libs/          (shared libraries)

Each developer gets focused Cascade context per workspace window.