Windsurf AI Coding

Built to keep you in flow state

Workflow

1. Initialization: Start each session by loading PLANNING.md and .windsurfrules into the AI's context. Review the latest .windsurf/task-logs/ to understand current state.
2. Planning Phase: Update or refine PLANNING.md and .windsurf/plans/* as requirements evolve. Document all new insights before coding.
3. Task Management: Use TASK.md to break down work into actionable items. As tasks are completed, update TASK.md and log changes in .windsurf/task-logs/.
4. Implementation: Follow the prioritized plan (feature-order.md), referencing UI/UX, db-schema, and complexity-analysis as needed. Enforce standards via .windsurfrules.
5. Documentation: After each session, update all relevant files—especially task logs and planning artifacts—to leave clear "reminder notes" for the next session.
6. Review and Refactor: Use refactor.md (if present) to guide large changes, checking off steps as you go.

Project Structure

By rigorously maintaining these files, you ensure both human and AI collaborators stay aligned, productive, and resilient to context loss—enabling a truly next-generation, AI-augmented software development workflow.

• Memories
• Editor Examples

project-root/
├── .windsurfrules
├── .windsurf/
│   ├── plans/
│   │   ├── purpose.md
│   │   ├── priorities.md
│   │   ├── complexity-analysis.md
│   │   ├── ui-ux.md
│   │   ├── db-schema.md
│   │   └── error-patterns.md
│   └── task-logs/
│       └── [date]-[task].md
├── global_rules.md
├── README.md
└── refactor.md (optional)

File/Directory	Purpose
global_rules.md	Organization-wide or workspace-wide AI rules
.windsurfrules	Project-specific AI rules: tech stack, directory structure, coding standards, forbidden tools
.windsurf/plans/	Directory for detailed planning artifacts (see below)
.windsurf/plans/purpose.md	High-level vision, architecture, constraints, tech stack, tools, guiding principles
.windsurf/plans/priorities.md	Prioritized feature and dependency list, tracks current tasks, backlog, milestones, discoveries
.windsurf/plans/data-flow-diagrams.md	UI/UX wireframes, mockups, data structure sketches
.windsurf/plans/complexity-analysis.md	Analysis of technical challenges, scalability, edge cases
.windsurf/plans/db-schema.md	Database schema and rationale
.windsurf/plans/error-patterns.md	Catalog of recurring errors and mitigation patterns
.windsurf/task-logs/	Directory for persistent task logs
refactor.md (optional)	Step-by-step implementation roadmap/checklist
README.md	Project overview, setup instructions, usage

Best Practices

Evolve a maintenance schedule to ensure that both your codebase and Windsurf rules remain in optimal condition to maximize the benefits of your AI-powered development environment while maintaining high code quality standards.

Below is a structured routine to keep your codebase and .windsurf/rules in optimal condition, organized by timeframe and responsibility area.

Daily Tasks

Memory Management

• Perform quick check of active AI memories in Windsurf Cascade window
• Clear outdated or incorrect memories that could mislead the AI
• Reset the context when switching between major project components

Code Quality

• Dedicate 30 minutes to small code cleanup tasks (removing unused code, fixing comments)
• Review and refactor any high cyclomatic complexity methods you've worked on that day
• Validate that new domain entities include Zod schemas (as per your domain rules)
• Run automated tests to catch issues early

Documentation

• Update README files with any new installation or maintenance instructions
• Ensure all new domain types are documented using TSDoc or JSDoc comments
• Maintain your TODO file tracking features (To Do, In Progress, Done)

Weekly Tasks

Memory and Context Management

• Perform complete check and cleanup of all AI memories
• Review and update your prompting strategies based on results from the week
• Check task logs in .windsurf/task-logs/ to ensure they're properly maintained

Code Structure

• Run code analysis tools to identify duplicated code and remove it
• Verify validation happens at system boundaries (API, UI inputs) as per your rules
• Check for and correct any redefined entity types (as per your screenshot rules)
• Limit PR sizes (flag any PRs affecting more than 20 files)

Rules Maintenance

• Review .windsurf/rules for accuracy and update based on recent project changes
• Maintain and update your domain model documentation with:
  • Business purpose and context
  • Validation rules and constraints
  • Relationships to other domain entities
  • Example usage

Feature Management

• Review feature branches older than 1 week and plan for completion/merging
• Check that multiple AI agent windows are properly isolated to specific features

Monthly Tasks

Comprehensive Review

• Perform routine maintenance as specified in your Maintenance Checklist:
  • Verify backups are working
  • Check application updates
  • Update documentation and test cases
  • Inform users about implemented changes

AI Drift Prevention

• Analyze AI output patterns for drift indicators
• Identify common deviations from architectural patterns
• Update .windsurf/rules files to address specific drift patterns
• Document rule development and changes

Performance Optimization

• Review and optimize slow-performing code sections
• Check CI/CD pipeline and feature flag implementation
• Run comprehensive performance tests

Rule Management Guidelines

Domain Model Rules (as seen in your screenshot)

• Keep all domain types defined in src/core/domain/
• Document all new domain types with TSDoc or JSDoc comments
• Ensure all layers import types from the domain layer only
• Never redefine entity types elsewhere in the codebase
• Include Zod schemas for all domain entities
• Perform validation at system boundaries
• Use branded types for type safety where appropriate

Windsurf Memory Management Implementation

• Maintain the three-layer memory system:
  • Working Memory: .windsurf/core/activeContext.md
  • Short-Term Memory: .windsurf/task-logs/
  • Long-Term Memory: Remaining .windsurf/core/ files

Team Responsibilities

Daily Developer Responsibilities

• Follow the domain model documentation guidelines
• Maintain personal memory management habits in Windsurf
• Document code as you write it
• Participate in code reviews with focus on architectural conformance

Team Lead Weekly Responsibilities

• Review and update global rules in .windsurf/rules
• Monitor compliance with domain model standards
• Ensure memory management protocols are being followed
• Lead discussion on AI drift patterns observed and rule adjustments needed

Links

• 2025 Apr, Lenny's Podcast