Skip to main content
windsurf-reference-architecture Implement Windsurf reference architecture with best-practice project layout.
Use when designing new Windsurf integrations, reviewing project structure,
or establishing architecture standards for Windsurf applications.
Trigger with phrases like "windsurf architecture", "windsurf best practices",
"windsurf project structure", "how to organize windsurf", "windsurf layout".
npx skills add jeremylongshore/claude-code-plugins-plus-skills --skill windsurf-reference-architecture ai automation claude-code devops mcp ai-agents
Windsurf Reference Architecture
Overview
Complete project architecture optimized for Windsurf AI. Covers workspace configuration, rules hierarchy, workflow organization, and team standardization patterns that maximize Cascade's effectiveness.
Prerequisites
Windsurf IDE installed
Team agreement on coding standards
Repository with consistent project structure
Architecture Diagram
┌──────────────────────────────────────────────────────┐
│ Windsurf Workspace │
│ ┌───────────────┐ ┌────────────────────────────┐ │
│ │ .windsurfrules│ │ .windsurf/ │ │
│ │ (AI context) │ │ ├── rules/ (trigger rules)│ │
│ │ │ │ ├── workflows/ (automation)│ │
│ │ │ │ └── settings.json │ │
│ └───────────────┘ └────────────────────────────┘ │
│ ┌───────────────┐ ┌────────────────────────────┐ │
│ │ .codeiumignore│ │ ~/.codeium/ │ │
│ │ (index rules) │ │ ├── global_rules.md │ │
│ │ │ │ ├── windsurf/memories/ │ │
│ │ │ │ └── windsurf/mcp_config │ │
│ └───────────────┘ └────────────────────────────┘ │
├──────────────────────────────────────────────────────┤
│ Cascade AI Engine │
│ ┌───────────┐ ┌───────────┐ ┌─────────────────┐ │
│ │ Super- │ │ Cascade │ │ Command │ │
│ │ complete │ │ Write/Chat│ │ (Inline Edit) │ │
│ │ (Tab) │ │ (Cmd+L) │ │ (Cmd+I) │ │
│ └───────────┘ └───────────┘ └─────────────────┘ │
├──────────────────────────────────────────────────────┤
│ Context Layers │
│ Rules > Memories > @Mentions > Open Files > Index │
└──────────────────────────────────────────────────────┘
Instructions
Step 1: Project File Structure my-project/
├── .windsurfrules # AI context (stack, patterns, constraints)
├── .codeiumignore # Indexing exclusions
├── .windsurf/
│ ├── settings.json # IDE settings (committed)
│ ├── rules/
│ │ ├── testing.md # trigger: glob **/*.test.ts
│ │ ├── api-routes.md # trigger: glob src/routes/**
│ │ ├── security.md # trigger: model_decision
│ │ └── migrations.md # trigger: manual
│ └── workflows/
│ ├── new-feature.md # /new-feature
│ ├── deploy-staging.md # /deploy-staging
│ ├── review-pr.md # /review-pr
│ └── quality-check.md # /quality-check
├── src/
│ ├── routes/ # API route handlers
│ ├── services/ # Business logic
│ ├── repositories/ # Data access
│ └── types/ # Shared types
├── tests/
│ ├── fixtures/ # Test data factories
│ └── services/ # Service unit tests
└── docs/
└── architecture.md # Architecture decisions
Step 2: Rules Hierarchy # Priority order (highest to lowest):
rules_hierarchy:
1_global_rules:
path: ~/.windsurf/global_rules.md
limit: 6000 chars
scope: All workspaces
use_for: "Personal coding preferences, universal standards"
2_windsurfrules:
path: .windsurfrules (project root)
limit: 6000 chars
scope: Current workspace
use_for: "Project stack, architecture, conventions"
3_workspace_rules:
path: .windsurf/rules/*.md
limit: 12000 chars each
scope: Triggered by glob, model_decision, or manual
use_for: "File-type-specific patterns, conditional rules"
4_memories:
path: ~/.codeium/windsurf/memories/
scope: Workspace-specific (auto-generated)
use_for: "Decisions, discoveries (supplement, don't replace rules)"
# Total active chars: 12000 max (global + workspace rules combined)
# If exceeded: global rules take priority, workspace rules truncated
Step 3: Team Configuration Template // .windsurf/settings.json (committed to git)
{
"codeium.indexing.excludePatterns": [
"node_modules/**", "dist/**", ".next/**",
"coverage/**", "*.min.js", "**/*.map"
],
"codeium.autocomplete.enable": true,
"editor.formatOnSave": true,
"editor.defaultFormatter": "biomejs.biome",
"typescript.tsdk": "node_modules/typescript/lib",
"files.associations": { "*.css": "tailwindcss" }
}
Step 4: Monorepo Strategy monorepo/
├── .windsurfrules # Shared conventions (brief)
├── .codeiumignore # Broad exclusions
├── apps/
│ ├── web/
│ │ └── .windsurfrules # Next.js-specific rules
│ └── mobile/
│ └── .windsurfrules # React Native rules
├── packages/
│ ├── api/
│ │ └── .windsurfrules # Express/Fastify rules
│ └── shared/
│ └── .windsurfrules # Library conventions
└── .windsurf/
└── workflows/ # Cross-package workflows
# BEST PRACTICE: Open apps/web/ or packages/api/ directly
# NOT the monorepo root
# Cascade gets focused context per workspace window
Step 5: Context Pinning Strategy ## What to Pin in Cascade
Pin files that provide essential context:
- Type definition files (types/*.ts)
- Architecture decision records (docs/adr/)
- API schema files (openapi.yaml)
- Database schema (prisma/schema.prisma, drizzle/schema.ts)
How to pin:
- Click the pin icon next to a file in the Cascade context area
- Pinned files are always included in Cascade's context window
- Limit: pin 3-5 files max (more = diluted context)
Error Handling Issue Cause Solution Cascade ignores project patterns Missing/empty .windsurfrules Add stack and architecture details Rules truncated Over 12,000 combined chars Split into workspace rules with triggers Wrong patterns for file type No glob-triggered rules Add .windsurf/rules/ with glob triggers Team inconsistency No shared config Commit .windsurf/ directory to git Slow indexing in monorepo Root workspace open Open specific package/app directory
Examples
Minimal .windsurfrules for Any Project # Project: [name]
## Stack: [language] + [framework] + [database]
## Testing: [test framework]
## Conventions:
- [3-5 key coding patterns]
## Don't:
- [2-3 explicit anti-patterns]
Verify Architecture Setup set -euo pipefail
echo "=== Windsurf Architecture Check ==="
echo "Rules: $([ -f .windsurfrules ] && wc -c < .windsurfrules || echo 'MISSING') chars"
echo "Ignore: $([ -f .codeiumignore ] && wc -l < .codeiumignore || echo 'MISSING') patterns"
echo "Rules dir: $(ls .windsurf/rules/ 2>/dev/null | wc -l || echo 0) files"
echo "Workflows: $(ls .windsurf/workflows/ 2>/dev/null | wc -l || echo 0) files"
Resources
Next Steps For workspace variant strategies, see windsurf-architecture-variants.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).
