Creating & Modifying Rules

Overview

In modern software development, maintaining a consistent codebase isn’t just about aesthetics—it’s critical for collaboration, readability, scalability, and long-term maintainability. Yet, as teams grow and projects evolve, small inconsistencies creep in: one developer uses inline styles, another writes custom CSS classes, while someone else reaches for utility-first frameworks like Tailwind. Without guardrails, your code starts to reflect a patchwork of personal preferences rather than a unified team standard.

Enter the Creating & Modifying Rules AI skill for Windsurf, a powerful capability that empowers developers to define, customize, and enforce project-specific coding conventions directly within their IDE. Whether you're mandating the use of Tailwind classes instead of raw CSS, banning deprecated functions, or standardizing component structure across React files, this skill turns your best practices into automated, intelligent enforcement mechanisms.

With this skill, Windsurf becomes more than an AI-powered coding assistant—it transforms into a proactive code quality enforcer, trained on your team’s unique rules and style guides. No more relying solely on code reviews or linter configurations that can’t understand context. Instead, you get real-time suggestions, auto-corrections, and preventive guidance—all tailored to your project's DNA.

Whether you’re a tech lead setting up a new microservice, a frontend architect standardizing design system usage, or a solo developer who wants cleaner, more predictable outputs from AI-generated code, mastering rule creation in Windsurf is a game-changer.

Let’s dive into why this skill matters—and how you can start using it today.

---

Key Benefits

Here’s what makes the Creating & Modifying Rules skill indispensable in your daily workflow:

1. Enforce Design System Compliance

Imagine every component automatically uses your organization’s approved UI patterns. With custom rules, you can ensure developers use Button components with predefined variants instead of creating ad-hoc <div>s styled with inline CSS. The AI will flag deviations and suggest compliant alternatives—keeping your UX consistent across features.

Scenario: A junior developer tries to add a new button using style={{ backgroundColor: 'blue' }}. Windsurf detects this, explains why it violates the rule, and offers to replace it with <Button variant="primary">.

2. Standardize Utility Framework Usage (e.g., Tailwind over CSS)

One of the most common pain points in frontend teams is inconsistent styling approaches. This skill lets you codify the mandate: "Use Tailwind classes, not raw CSS or styled-components." When AI generates code or a teammate writes markup, Windsurf checks compliance and reformats non-conforming code.

Scenario: You're building a Next.js app with Tailwind. An AI-generated modal includes a <style> block. Windsurf intercepts it, removes the block, and converts all styles into responsive Tailwind classes.

3. Prevent Anti-Patterns Before They Happen

Rules aren’t just about formatting—they can stop harmful patterns at the source. Define rules against direct DOM manipulation in React, improper state management, or importing from disallowed modules (like internal APIs). These become part of your AI assistant’s “knowledge,” so it won’t generate problematic code in the first place.

Scenario: Someone attempts to use document.getElementById() in a React component. Windsurf flags it as a violation and suggests using React refs instead.

4. Onboard New Developers Faster

Instead of handing new hires a 50-page style guide, embed those rules directly into the development environment. They’ll receive contextual feedback as they type—learning by doing, guided by AI that speaks your project’s language.

Scenario: A contractor joins your team for two weeks. Within hours, their pull requests look like they’ve been here for months—because Windsurf ensured adherence to naming conventions, file structure, and architectural patterns.

5. Future-Proof Your Codebase During Migrations

Migrating from one library to another? Deprecating old patterns? Create temporary rules to phase out legacy code. For example, ban imports from legacy-utils.js and redirect usage to the new core-helpers package. The AI helps refactor incrementally, reducing technical debt without slowing velocity.

Scenario: You’re moving from Moment.js to date-fns. A rule blocks new imports of Moment and suggests equivalent date-fns functions—automatically applied during AI-assisted refactoring.

---

Core Features

Feature	Description	Use Case Example
Custom Rule Definition	Write declarative rules using a simple configuration syntax to specify allowed/disallowed patterns.	Ban any use of var in favor of const/let.
Context-Aware Enforcement	Rules are evaluated with full understanding of code semantics, not just regex matching.	Allow console.log() in development files but warn in production modules.
Auto-Fix Suggestions	When violations occur, Windsurf doesn’t just highlight them—it provides ready-to-apply fixes.	Replace raw CSS classes with Tailwind equivalents in JSX elements.
Project-Specific Scope	Apply rules per project, branch, or even directory—no global overrides needed.	Enforce stricter rules in core libraries vs. demo apps.
Integration with AI Generation	All Windsurf AI-generated code respects active rules by default.	Generate a form component that uses only approved input components and Tailwind styling.
Rule Inheritance & Sharing	Reuse rule sets across projects or teams via shared configurations.	Roll out company-wide React best practices across all frontend repos.

---

How to Get & Install

The Creating & Modifying Rules skill is available free of charge and integrates natively into the Windsurf platform. Follow these steps to activate and configure it in your project:

✅ Step 1: Ensure You’re Using Windsurf

This skill works exclusively within the Windsurf IDE or VS Code extension. If you haven’t installed it yet:

1. Go to https://windsurf.com
2. Download and install the Windsurf IDE or the VS Code plugin
3. Sign in with your account (free tier available)

💡 Tip: Make sure you're running version v1.8+, where rule customization is fully supported.

✅ Step 2: Access the Rules Configuration File

Every Windsurf-powered project can have its own .windsurfrules.json file at the root. If it doesn’t exist, create one:

touch .windsurfrules.json

This file defines all custom rules the AI should follow when generating or reviewing code.

✅ Step 3: Define Your First Rule

Open .windsurfrules.json and start with a basic example—banning raw CSS in favor of Tailwind:

{
  "rules": [
    {
      "id": "no-raw-css",
      "type": "disallow-pattern",
      "language": "javascript,typescript,jsx,tsx",
      "match": "className=\"[^\"]*\\{[^}]*\\}[^\"]*\"",
      "message": "Avoid dynamic string concatenation in className. Use Tailwind's twMerge or clsx for conditional classes.",
      "suggest": "Use clsx() for dynamic class composition: import { clsx } from 'clsx';"
    },
    {
      "id": "prefer-tailwind-over-inline-style",
      "type": "disallow-property",
      "element": "JSXElement",
      "property": "style",
      "message": "Inline styles are not allowed. Use Tailwind utility classes instead.",
      "fix": "Convert style object to equivalent Tailwind classes."
    }
  ]
}

You can also forbid entire constructs:

{
  "id": "no-var-declarations",
  "type": "disallow-keyword",
  "keyword": "var",
  "message": "Use 'const' or 'let' instead of 'var' for variable declaration.",
  "fix": "Replace 'var' with 'const' where possible."
}

✅ Step 4: Activate Real-Time Rule Checking

Once saved, Windsurf automatically:

• Highlights violations in the editor
• Blocks AI from generating non-compliant code
• Offers quick fixes via lightbulb suggestions (⌥⏎)

To test it:

1. Type a JSX element with style={{ color: 'red' }}
2. Watch Windsurf underline it and offer to convert to className="text-red-500"

✅ Step 5: Share Rules Across Projects (Optional)

To reuse your rule set:

1. Publish your rules as a public or private npm package (e.g., @mycompany/windsurf-rules)
2. Install it in other projects:

   npm install --save-dev @mycompany/windsurf-rules
   

3. Reference it in .windsurfrules.json:

   {
     "extends": "@mycompany/windsurf-rules/base.json"
   }
   

For advanced users: Explore the Windsurf University course on rule logic and pattern matching at
👉 https://windsurf.com/university/general-education/creating-modifying-rules

---

Use Cases

Here are five ideal scenarios where the Creating & Modifying Rules skill shines:

1. Frontend Teams Using Design Systems

Enforce strict usage of branded components (<Card />, <DataTable />) and prevent bypassing through divs and custom styles.

2. Monorepo Governance

Apply different rule sets per package—stricter ones for shared libraries, relaxed ones for experiments.

3. Security & Compliance

Ban dangerous practices like eval(), innerHTML, or hardcoded secrets in environment files.

4. Legacy Modernization

Phase out old APIs during migration by marking them as deprecated in rules, with automatic replacement hints.

5. Educational Environments

Teach students or bootcampers good habits by embedding pedagogical rules—like requiring comments on complex functions or forbidding nested ternaries.

---

Tips for Success

1. Start Small, Iterate Often
   Begin with 2–3 high-impact rules (e.g., no inline styles, no console.log in prod). Gather feedback before rolling out dozens.

2. Combine with Linters, Don’t Replace Them
   Use ESLint/Prettier for formatting and syntax; let Windsurf handle semantic, AI-aware rules that go beyond static analysis.

3. Document Your Rules Internally
   Add a docs/rules.md file explaining each rule’s purpose. Link to it in the message field so developers understand the “why.”

---

Disclaimer: The Creating & Modifying Rules skill is a feature of the Windsurf AI coding platform. While it significantly improves code consistency, it does not replace thorough testing or peer review. Always validate critical logic manually. Some advanced rule types may require a Pro plan, though core functionality remains free. Visit windsurf.com for full details.