├── README.md ├── vibe-coding-rules_overview.md ├── adapt_Windsurfrules_Prompt.txt ├── global_rules.md └── .windsurfrules /README.md: -------------------------------------------------------------------------------- 1 | # Vibe Coding AI Rules 2 | The Ultimate Vibe Coding Guide for AI IDEs like Windsurf, Cursor etc. – AI-optimized rules, best practices, and configuration files for efficient and controlled AI-powered coding. 3 | 4 | ## Level up your AI coding with Windsurf, Cursor or other AI IDEs! 5 | 6 | ### 🚀 This repository contains: 7 | 8 | - A complete Vibe Coding Ruleset for optimized AI coding workflows. 9 | - A detailed global_rules.md configuration file, for global vibe-coding seetings. 10 | - An example of a projec specific vibe-coding file: .windsurfrules 11 | - A super AI / LLM prompt, which helps you to adapt the project-specific config file (.windsurfrules) to your needs and projects 12 | - Best practices for clean, efficient, and controlled AI-driven development. 13 | 14 | ## Configuration Architecture 15 | Windsurf employs a two-tier configuration approach: 16 | 17 | - Global Rules (global_rules.md): Establish universal standards across all projects 18 | - Project-Specific Rules (.windsurfrules): Define contextual requirements for individual projects 19 | 20 | This separation creates a powerful inheritance model where project configurations extend global standards while adding domain-specific knowledge. 21 | 22 | 23 | #### ⚡ Stay in control. Code smarter. Deploy faster. 24 | -------------------------------------------------------------------------------- /vibe-coding-rules_overview.md: -------------------------------------------------------------------------------- 1 | # Vibe Coding Rules in short 2 | 3 | ## Setup & AI Configuration 4 | - Use **Cursor** or **Wind Surf** as AI-powered IDEs. 5 | - Prefer **Claude 3.7 Thinking** or **Grok 3** for agentic coding. 6 | - Ensure **API keys** are correctly set up. 7 | - Define **project rules** in the IDE to control AI behavior. 8 | 9 | ## Coding Workflow 10 | - Start with **detailed specs** before generating AI code. 11 | - Keep AI requests **small and precise** to avoid unnecessary changes. 12 | - Run **tests frequently** to verify AI-generated code. 13 | - Prefer **end-to-end tests** over unit tests for better real-world validation. 14 | - Monitor **AI chat context size**, restart sessions when performance drops. 15 | 16 | ## Code Quality & Structure 17 | - Prefer **simple solutions**, avoid over-engineering. 18 | - Eliminate **code duplication**, reuse existing functions where possible. 19 | - Maintain **separate environments** for DEV, TEST, and PROD. 20 | - Only apply **requested changes**, avoid modifying unrelated parts. 21 | - Don’t introduce **new tech or patterns** unless strictly necessary. 22 | - Keep the codebase **clean & structured**, refactor regularly. 23 | - Never use **mock data** in DEV or PROD, only for tests. 24 | - Never overwrite **.env files** without explicit approval. 25 | 26 | ## Documentation & Progress Tracking 27 | - Continuously update the **README** (installation, maintenance, key info). 28 | - Always **verify AI-generated code** before proceeding. 29 | - Maintain a **TODO file** (To Do, In Progress, Done) to track AI progress. 30 | 31 | ## Deployment & Version Control 32 | - **Commit frequently** to enable easy rollbacks. 33 | - Use **built-in IDE versioning** to revert changes when needed. 34 | - Run AI modifications in **separate branches** before merging to main. 35 | - Never use **YOLO mode** in production, manually approve critical deployments. 36 | 37 | ## Additional Optimizations 38 | - Stick to **popular tech stacks** (Python, JS, SQL, etc.) for better AI support. 39 | - Use **multiple AI agent windows** to develop features in parallel. 40 | - Leverage **AI chat history & restore checkpoints** when needed. 41 | 42 | -------------------------------------------------------------------------------- /adapt_Windsurfrules_Prompt.txt: -------------------------------------------------------------------------------- 1 | I need you to help me create a tailored .windsurfrules file for my project that follows the "Vibe-Coding" methodology for AI-assisted development in WindSurf IDE. I'll provide details about my project, and I want you to generate a comprehensive configuration file similar to the example below but customized for my specific needs. 2 | My Project Information 3 | Project Name: {{PROJECT_NAME}} 4 | Project Description: {{PROJECT_DESCRIPTION}} 5 | Main Goals: 6 | {{LIST_OF_PROJECT_GOALS}} 7 | Project Type: {{PROJECT_TYPE}} (e.g., Mobile App, Web Application, API Service, Desktop Application, etc.) 8 | Technology Preferences 9 | Primary Programming Languages: 10 | {{PREFERRED_PROGRAMMING_LANGUAGES}} 11 | Preferred Frameworks/Libraries: 12 | {{PREFERRED_FRAMEWORKS_LIBRARIES}} 13 | Database Technologies: 14 | {{DATABASE_PREFERENCES}} 15 | Additional Tools/Technologies: 16 | {{ADDITIONAL_TOOLS}} 17 | Technologies to Explicitly Avoid: 18 | {{TECHNOLOGIES_TO_AVOID}} 19 | Project Structure 20 | Preferred Directory Structure: 21 | {{DIRECTORY_STRUCTURE_PREFERENCES}} 22 | Key Modules/Components: 23 | {{KEY_MODULES_COMPONENTS}} 24 | Development Guidelines 25 | Coding Style Preferences: 26 | {{CODING_STYLE_PREFERENCES}} 27 | Testing Strategy: 28 | {{TESTING_STRATEGY}} 29 | Deployment Process: 30 | {{DEPLOYMENT_PROCESS}} 31 | Performance Considerations: 32 | {{PERFORMANCE_CONSIDERATIONS}} 33 | Security Requirements: 34 | {{SECURITY_REQUIREMENTS}} 35 | Special Instructions 36 | Known Challenges: 37 | {{KNOWN_CHALLENGES}} 38 | Additional Instructions: 39 | {{ADDITIONAL_INSTRUCTIONS}} 40 | 41 | Based on this information, please create a comprehensive .windsurfrules file that follows the Vibe-Coding methodology. The file should include: 42 | 43 | A detailed project context section 44 | A complete technology stack specification with versions 45 | A well-structured directory tree 46 | Specific coding conventions and style guidelines 47 | Workflow protocols for AI-assisted development 48 | Custom rules for AI interaction within this project 49 | Performance and security considerations 50 | Any project-specific patterns or architectural principles 51 | 52 | Please format the output as a complete Markdown file that I can use directly as my .windsurfrules file in WindSurf. Include all sections from the example (Project Context, Technology Stack, Project Structure, etc.) but tailored to my specific project needs. 53 | Use a structured approach with clear headings, bulleted lists, and code blocks where appropriate. Include both high-level guidelines and specific technical details to provide comprehensive guidance for the AI. 54 | 55 | Here is the a special .windsurfrules file for a Pomodoro Timer App: 56 | ''' 57 | {{conten of the .windsurfrules file)) 58 | ''' 59 | -------------------------------------------------------------------------------- /global_rules.md: -------------------------------------------------------------------------------- 1 | # Global AI Coding Rules for Windsurf 2 | 3 | These rules establish universal standards and preferences that apply across all projects developed with Windsurf AI assistance. 4 | 5 | ## Core Principles 6 | 7 | * **Simplicity First (SF):** Always choose the simplest viable solution. Complex patterns or architectures require explicit justification. 8 | * **Readability Priority (RP):** Code must be immediately understandable by both humans and AI during future modifications. 9 | * **Dependency Minimalism (DM):** No new libraries or frameworks without explicit request or compelling justification. 10 | * **Industry Standards Adherence (ISA):** Follow established conventions for the relevant language and tech stack. 11 | * **Strategic Documentation (SD):** Comment only complex logic or critical functions. Avoid documenting the obvious. 12 | Write new docs in english. If you find docs in other languages, rewrite them into english. 13 | * **Test-Driven Thinking (TDT):** Design all code to be easily testable from inception. 14 | 15 | ## Workflow Standards 16 | 17 | * **Atomic Changes (AC):** Make small, self-contained modifications to improve traceability and rollback capability. 18 | * **Commit Discipline (CD):** Recommend regular commits with semantic messages using conventional commit format: 19 | ``` 20 | type(scope): concise description 21 | 22 | [optional body with details] 23 | 24 | [optional footer with breaking changes/issue references] 25 | ``` 26 | Types: feat, fix, docs, style, refactor, perf, test, chore 27 | * **Transparent Reasoning (TR):** When generating code, explicitly reference which global rules influenced decisions. 28 | * **Context Window Management (CWM):** Be mindful of AI context limitations. Suggest new sessions when necessary. 29 | * **Preserve Existing Code (PEC):** Windsurf must not overwrite or break functional code unless explicitly instructed otherwise. Propose changes conservatively to maintain codebase integrity [AC, CA] 30 | 31 | ## Code Quality Guarantees 32 | 33 | * **DRY Principle (DRY):** No duplicate code. Reuse or extend existing functionality. 34 | * **Clean Architecture (CA):** Generate cleanly formatted, logically structured code with consistent patterns. 35 | * **Robust Error Handling (REH):** Integrate appropriate error handling for all edge cases and external interactions. 36 | * **Code Smell Detection (CSD):** Proactively identify and suggest refactoring for: 37 | * Functions exceeding 30 lines 38 | * Files exceeding 300 lines 39 | * Nested conditionals beyond 2 levels 40 | * Classes with more than 5 public methods 41 | 42 | ## Security & Performance Considerations 43 | 44 | * **Input Validation (IV):** All external data must be validated before processing. 45 | * **Resource Management (RM):** Close connections and free resources appropriately. 46 | * **Constants Over Magic Values (CMV):** No magic strings or numbers. Use named constants. 47 | * **Security-First Thinking (SFT):** Implement proper authentication, authorization, and data protection. 48 | * **Performance Awareness (PA):** Consider computational complexity and resource usage. 49 | 50 | ## AI Communication Guidelines 51 | 52 | * **Rule Application Tracking (RAT):** When applying rules, tag with the abbreviation in brackets (e.g., [SF], [DRY]). 53 | * **Explanation Depth Control (EDC):** Scale explanation detail based on complexity, from brief to comprehensive. 54 | * **Alternative Suggestions (AS):** When relevant, offer alternative approaches with pros/cons. 55 | * **Knowledge Boundary Transparency (KBT):** Clearly communicate when a request exceeds AI capabilities or project context. 56 | 57 | ## Continous documentation during development process (CDiP) 58 | 59 | * **Keep all *.md files up-to-date, which where used to keep track of progress, todos and help ing infos** (e.g. TASK_LIST.md, README.md, LEARNING_FROM_JAVA.md, VAU_IMPLEMENTATION_PLAN.md, etc.) 60 | - generate memories for each new created or new requested md file, which shall help the AI or the developer to keep track of the project context and progress. 61 | - update the md files, when new tasks are added, completed or when new todos are added or completed. 62 | - but do not touch *.md files in doc folder! 63 | 64 | ## Feature-Based Development Workflow 65 | 66 | 1. **Create Feature Branch:** 67 | - For each new feature or task, create a dedicated feature branch from master. 68 | - Use descriptive branch names with conventional format: `feature/feature-name` or `task/task-name` [CD]. 69 | 70 | 2. **Development Process:** 71 | - Complete all development work in the feature branch [AC]. 72 | - Ensure all tests pass successfully before considering the task complete [CTC]. 73 | - Follow clean architecture principles and coding standards [CA]. 74 | 75 | 3. **Task Completion in Feature Branch:** 76 | - Mark tasks as completed in `TASK_LIST.md` within the feature branch [CDiP]. 77 | - Commit these changes to the feature branch [CD]. 78 | - This should be done before creating the pull request. 79 | 80 | 4. **Pull Request Process:** 81 | - Create a pull request to the master branch when feature is complete [AC]. 82 | - Include the updated `TASK_LIST.md` in the pull request [CDiP]. 83 | - Wait for reviewer acknowledgment before proceeding. 84 | 85 | 5. **Merge Process:** 86 | - After approval, merge the feature branch into master. 87 | - Delete the feature branch after successful merge [AC]. 88 | 89 | 6. **Task Tracking:** 90 | - The updated `TASK_LIST.md` is already part of the merged changes [CDiP]. 91 | - No additional updates to `TASK_LIST.md` should be needed after the PR is approved. 92 | 93 | **This workflow ensures that:** 94 | - Each feature can be rolled back independently if needed [AC]. 95 | - Code quality is maintained through the review process [CA]. 96 | - The master branch always contains a working version of the application [PEC]. 97 | - Progress is clearly tracked and documented [CDiP]. 98 | - Task completion is part of the feature work and included in the review process [CD]. 99 | -------------------------------------------------------------------------------- /.windsurfrules: -------------------------------------------------------------------------------- 1 | 2 | ### Project Description 3 | 4 | **"FocusForge"** - An advanced Pomodoro timer application with AI-driven productivity insights, customizable work rhythms, and team synchronization capabilities for distributed teams. 5 | 6 | 7 | 8 | ### Main Goals 9 | 10 | - Develop an adaptive Pomodoro system that learns user productivity patterns. 11 | - Create a distraction-blocking mechanism with browser and OS integration. 12 | - Implement team synchronization for coordinated deep work sessions. 13 | - Build a comprehensive analytics dashboard with mood tracking, productivity scores, and focus metrics. 14 | - Create a gamified achievement system to reward consistent deep work habits. 15 | 16 | 17 | 18 | ### Architecture Overview 19 | 20 | - **Type:** Progressive Web App (PWA) with offline capabilities. 21 | - **Backend:** Serverless architecture for scalability and real-time synchronization. 22 | 23 | 24 | 25 | ## Technology Stack 26 | 27 | * **Primary Programming Languages:** 28 | * TypeScript 5.2+ (strict mode) 29 | * Python 3.11+ (for analytics backend) 30 | 31 | * **Frameworks/Libraries:** 32 | * Frontend: React 18.2, Next.js 14.0, TailwindCSS 3.3 33 | * Backend: NestJS 10.0, FastAPI 0.104 34 | * State Management: Zustand 4.4, React Query 5.0 35 | * Testing: Vitest 0.34, Playwright 1.40 36 | 37 | * **Databases:** 38 | * PostgreSQL 15+ with Prisma ORM (main data) 39 | * MongoDB 6.0+ with Mongoose (user analytics) 40 | * Redis 7.0+ (caching) 41 | 42 | * **Additional Tools/Technologies:** 43 | * Docker & Docker Compose 44 | * GitHub Actions for CI/CD 45 | * AWS (ECS, RDS, S3) 46 | * OpenTelemetry for observability 47 | 48 | * **Explicitly DO NOT use:** 49 | * Redux (use Zustand instead) 50 | * CSS-in-JS libraries (use TailwindCSS) 51 | * Axios (use native fetch API) 52 | * jQuery or other legacy libraries 53 | * Material UI (use Radix UI primitives with custom styling) 54 | 55 | 56 | 57 | ## Project Structure Example 58 | 59 | 60 | * **Directory Structure:** 61 | ``` 62 | ├── apps/ 63 | │ ├── web/ # Next.js frontend 64 | │ │ ├── src/ 65 | │ │ │ ├── app/ # App router pages 66 | │ │ │ ├── components/ 67 | │ │ │ ├── hooks/ 68 | │ │ │ ├── lib/ # Utilities 69 | │ │ │ ├── services/ # API clients 70 | │ │ │ └── types/ 71 | │ ├── api/ # NestJS API service 72 | │ │ ├── src/ 73 | │ │ │ ├── modules/ 74 | │ │ │ ├── common/ 75 | │ │ │ └── tests/ 76 | │ ├── analytics/ # FastAPI analytics service 77 | │ │ ├── src/ 78 | │ │ │ ├── routes/ 79 | │ │ │ ├── models/ 80 | │ │ │ ├── services/ 81 | │ │ │ └── tests/ 82 | ├── packages/ # Shared libraries 83 | │ ├── ui/ # Component library 84 | │ ├── config/ # Shared configuration 85 | │ ├── types/ # Shared TypeScript types 86 | │ └── utils/ # Shared utilities 87 | ├── infrastructure/ # IaC and deployment 88 | │ ├── terraform/ 89 | │ ├── docker/ 90 | │ └── scripts/ 91 | ``` 92 | * **Reusable Components/Modules:** 93 | * `packages/ui` - Component library with design system primitives 94 | * `packages/utils/analytics` - Analytics tracking utilities 95 | * `packages/utils/formatting` - Data formatting helpers 96 | * `packages/utils/validation` - Input validation functions 97 | 98 | 99 | 100 | ## Coding Style and Conventions 101 | 102 | * **Language-Specific Style Guides:** 103 | * TypeScript: Airbnb style guide with project-specific ESLint config 104 | * Python: PEP 8 with Black formatter (line length 88) 105 | 106 | * **Naming Conventions:** 107 | * TypeScript: 108 | * PascalCase for components, interfaces, types, and classes 109 | * camelCase for variables, functions, and instances 110 | * UPPER_SNAKE_CASE for constants 111 | * Python: 112 | * snake_case for variables, functions, and methods 113 | * PascalCase for classes 114 | * UPPER_SNAKE_CASE for constants 115 | 116 | * **Specific Formatting Rules:** 117 | * Indentation: 2 spaces for TypeScript, 4 spaces for Python 118 | * Maximum line length: 100 characters 119 | * Single quotes for TypeScript, double quotes for Python 120 | * Trailing commas required in multiline arrays/objects 121 | * Semicolons required in TypeScript 122 | 123 | * **Comment Guidelines:** 124 | * Use JSDoc/TSDoc for public API functions 125 | * Inline comments only for non-obvious solutions 126 | * Comment complex algorithms with time/space complexity analysis 127 | * Include references to external resources where relevant 128 | 129 | * **Environment Variables:** 130 | * Never commit .env files to version control 131 | * Use .env.example files with dummy values 132 | * Document all environment variables in README.md 133 | # Document all important steps how to deploy, install the application in README.md, keep it up to date 134 | * Group variables by service/purpose with prefixes 135 | 136 | 137 | 138 | ## Workflow 139 | 140 | * **Testing Strategy:** 141 | * Unit tests for utilities and pure functions (>90% coverage) 142 | * Integration tests for API endpoints and services 143 | * E2E tests for critical user flows 144 | * Visual regression tests for UI components 145 | 146 | * **Deployment Process:** 147 | * PR builds deployed to preview environments 148 | * Main branch deploys to staging environment 149 | * Release tags deploy to production 150 | * Database migrations run automatically in CI/CD 151 | 152 | * **Branching Strategy:** 153 | * Feature branches: `feature/feature-name` 154 | * Bugfix branches: `fix/issue-description` 155 | * Release branches: `release/v1.2.3` 156 | * Test AI changes in separate branches: `ai/description` 157 | 158 | 159 | 160 | ## AI Interaction 161 | 162 | * **Focus in Requests:** 163 | * Limit scope to specific files or functions 164 | * Provide clear acceptance criteria 165 | * Use custom tags for structured requests: `...` 166 | 167 | * **Handling Existing Code:** 168 | * Preserve formatting and style of surrounding code 169 | * Leave existing comments intact unless specifically editing them 170 | * Match abstraction level of current implementation 171 | 172 | * **Feedback on Rules:** 173 | * Tag rule applications with abbreviations: [SF], [DRY], etc. 174 | * Explain reasoning when choosing between conflicting rules 175 | * Suggest rule improvements if patterns emerge 176 | 177 | 178 | 179 | ## Additional Notes 180 | 181 | * **Important Patterns/Architectural Principles:** 182 | * Repository pattern for data access 183 | * Command/Query Responsibility Segregation (CQRS) 184 | * Feature-based folder structure within modules 185 | * Atomic design principles for UI components 186 | 187 | --------------------------------------------------------------------------------