技能 编程开发 Windsurf 工作空间架构指南

Windsurf 工作空间架构指南

v20260423
windsurf-architecture-variants
本技能提供了全面的指南,指导用户根据项目规模(如单体项目、大型Monorepo、复杂多服务)选择最佳的Windsurf工作空间结构。它详细阐述了文件系统和规则的配置策略,旨在确保AI工具获取到准确、聚焦的项目上下文信息,从而最大化开发效率。
获取技能
268 次下载
概览

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.

Team conventions:

1. One Windsurf window per service/package
2. Every service has its own .windsurfrules and .codeiumignore
3. Cascade tasks scoped to current workspace only
4. Cross-service changes: open both workspaces side by side
5. Tag cascade commits: git commit -m "[cascade] description"
6. Use shared workflows from central config repo

Variant 4: Polyglot / Multi-Language

Best for: Projects with multiple languages (TypeScript + Python + Go).

# Each language has different .windsurfrules
services/
├── ts-api/
│   └── .windsurfrules     # TypeScript patterns, Fastify, Vitest
├── python-ml/
│   └── .windsurfrules     # Python patterns, FastAPI, pytest
└── go-gateway/
    └── .windsurfrules     # Go patterns, chi router, go test
<!-- .windsurfrules for Python service -->
# Project: ML Pipeline

## Stack
- Language: Python 3.11
- Framework: FastAPI
- ML: scikit-learn, pandas
- Testing: pytest with fixtures
- Type checking: mypy (strict)

## Conventions
- Use pydantic for all data models
- Async endpoints with asyncio
- Type hints on all functions
- No print() — use logging module

Variant 5: Frontend-Heavy (Design System)

Best for: UI-heavy projects with design system, Storybook, component library.

<!-- .windsurfrules for design system -->
# Project: Design System

## Stack
- Framework: React 18 + Next.js 14
- Styling: Tailwind CSS + custom tokens
- Components: Radix UI primitives
- Docs: Storybook 8
- Testing: Vitest + Testing Library

## Component Conventions
- One component per file (ComponentName.tsx)
- Co-located tests: ComponentName.test.tsx
- Co-located stories: ComponentName.stories.tsx
- Props interface exported: ComponentNameProps
- Use forwardRef for all components
- Use CVA (class-variance-authority) for variants

## Design Tokens
- Colors: use design-system/tokens, never raw Tailwind colors
- Spacing: use space-* scale (4px base)
- Typography: use text-* presets

Cascade integration: Use Previews to iterate on UI components:

"Preview the Button component with all variants"
Click elements in Preview → send to Cascade for refinement

Decision Matrix

FactorSoloFocused MonoMulti-WindowPolyglot
Team Size1-33-1515+Any
Codebase<10K files10K-50K50K+Mixed
Cascade SpeedFastFast (per window)Fast (per window)Fast (per window)
Setup EffortMinimal.codeiumignore + rulesPer-service configPer-language rules
Context QualityExcellentGoodGoodGood (per lang)

Error Handling

IssueCauseSolution
Cascade is slowToo many files indexedOpen smaller workspace, add .codeiumignore
Wrong file contextMonorepo root openOpen specific service directory
Conflicting editsMultiple devs, same filesFeature branches per Cascade session
Wrong language patternsMulti-language workspaceSeparate .windsurfrules per language directory
Stale suggestionsIndex out of dateCommand Palette > "Codeium: Reset Indexing"

Examples

Optimized .codeiumignore (Universal)

node_modules/
dist/
build/
.next/
coverage/
*.min.js
*.map
__pycache__/
.venv/
target/
vendor/
*.log
*.sqlite

Workspace Health Check

set -euo pipefail
FILE_COUNT=$(find . -type f -not -path '*/node_modules/*' -not -path '*/.git/*' | wc -l)
echo "Indexed files: ~$FILE_COUNT"
[ "$FILE_COUNT" -gt 10000 ] && echo "WARNING: Consider opening a subdirectory"
[ -f .windsurfrules ] && echo "Rules: $(wc -c < .windsurfrules) chars" || echo "Rules: MISSING"
[ -f .codeiumignore ] && echo "Ignore: $(wc -l < .codeiumignore) patterns" || echo "Ignore: MISSING"

Resources

Next Steps

For known pitfalls and anti-patterns, see windsurf-known-pitfalls.

信息
分类 编程开发
名称 windsurf-architecture-variants
版本 v20260423
大小 6.98KB
更新时间 2026-04-28
语言