Windsurf (Codeium) Mastery
Architecture
AI-native IDE distinguished by Cascade agentic system and Flow context engine.
Core Components
| Component | Purpose |
|---|---|
| Cascade | Agentic AI: plans, executes, iterates on multi-step tasks |
| Flows | Iterative AI workflows with approval checkpoints |
| Supercomplete | Intent-predicting autocomplete (not just next token) |
| M-Query | Proprietary retrieval outperforming cosine similarity RAG |
Context Assembly Pipeline
Every interaction:
- Load Rules — global
.windsurfrules→ project-level rules - Load Memories — persistent facts from previous sessions
- Read open files — active file highest weight
- Codebase retrieval — M-Query pulls relevant snippets
- Recent actions — file edits, terminal commands, navigation
- Assemble final prompt — all sources merged and trimmed
Configuration
Project Rules
.windsurfrules or .windsurfrules.md:
## Stack
- Frontend: React 19 + TypeScript
- Backend: Node.js + Express
- Database: PostgreSQL with Drizzle ORM
## Conventions
- Use functional components with hooks
- All API responses use: { data, error, meta }
- Snake_case for DB columns, camelCase for TypeScript
## Boundaries
- Never modify migration files directly
- Always run tests before suggesting PR
Memories System
| Level | Type | Scope |
|---|---|---|
| Global | Auto + Manual | All workspaces |
| Workspace | Auto + Manual | Per-project |
| System | Enterprise | Admin-defined |
Cascade autonomously identifies important context to remember.
Ignore File
.codeiumignore — prevents Cascade from viewing/editing files:
.env*
secrets/
*.key
node_modules/
dist/
Terminal Config
- Allow list: Commands that auto-execute (e.g.,
git) - Deny list: Commands requiring permission (e.g.,
rm)
Best Practices
- Use
.windsurfrulesfor stack/conventions — avoids re-explaining each session - Leverage Memories for persistent architecture knowledge
- Use
.codeiumignorefor sensitive files and large generated dirs - Configure terminal allow/deny for safety vs speed tradeoff
- Use browser preview element selection for UI bug fixes