windsurf-reference-architecture
Implement Windsurf reference architecture with optimal project structure and AI configuration. Use when designing workspace configuration for Windsurf, setting up team standards, or establishing architecture patterns that maximize Cascade effectiveness. Trigger with phrases like "windsurf architecture", "windsurf project structure", "windsurf best practices", "windsurf team setup", "optimize for cascade".
- License 许可
- MIT
- 最近更新
- 2026-07-13
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- windsurf-reference-architecture
- tags
- [ "saas", "windsurf", "architecture", "configuration", "team-setup" ]
- author
- Jeremy Longshore <jeremy@intentsolutions.io>
- license
- MIT
- version
- 1.0.0
- description
- Implement Windsurf reference architecture with optimal project structure and AI configuration. Use when designing workspace configuration for Windsurf, setting up team standards, or establishing architecture patterns that maximize Cascade effectiveness. Trigger with phrases like "windsurf architecture", "windsurf project structure", "windsurf best practices", "windsurf team setup", "optimize for cascade".
- allowed-tools
- Read, Grep
- compatible-with
- claude-code, codex, openclaw
03 SKILL.md 正文
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.
04 同仓库更多 Skills
zustand-store-creator
Create zustand store creator operations. Auto-activating skill for Frontend Development. Triggers on: zustand store creator, zustand store creator Part of the Frontend Development skill category. Use when working with zustand store creator functionality. Trigger with phrases like "zustand store creator", "zustand creator", "zustand".
zero-trust-config-helper
Configure with zero trust config helper operations. Auto-activating skill for Security Advanced. Triggers on: zero trust config helper, zero trust config helper Part of the Security Advanced skill category. Use when configuring systems or services. Trigger with phrases like "zero trust config helper", "zero helper", "zero".
zapier-integration-helper
Assist with zapier integration helper operations. Auto-activating skill for Business Automation. Triggers on: zapier integration helper, zapier integration helper Part of the Business Automation skill category. Use when working with APIs or building integrations. Trigger with phrases like "zapier integration helper", "zapier helper", "zapier".
yaml-config-validator
Validate yaml config validator operations. Auto-activating skill for DevOps Basics. Triggers on: yaml config validator, yaml config validator Part of the DevOps Basics skill category. Use when configuring systems or services. Trigger with phrases like "yaml config validator", "yaml validator", "yaml".
xvary-stock-research
Thesis-driven equity analysis from public SEC EDGAR and market data; /analyze, /score, /compare workflows with bundled Python tools (Claude Code, Cursor, Codex).
xss-vulnerability-scanner
Scan xss vulnerability scanner operations. Auto-activating skill for Security Fundamentals. Triggers on: xss vulnerability scanner, xss vulnerability scanner Part of the Security Fundamentals skill category. Use when working with xss vulnerability scanner functionality. Trigger with phrases like "xss vulnerability scanner", "xss scanner", "xss".