AGENTS.md in Windsurf: Complete Setup Guide (2026)

Windsurf reads AGENTS.md natively. If you already have one for Codex, Cline, or Cursor, Windsurf picks it up without any extra setup.

This guide covers how Windsurf’s rule system works, where AGENTS.md fits relative to .windsurfrules, how to structure rules for teams using both Windsurf and other tools, and the practical differences from similar setups in Cursor and Claude Code.

How Windsurf Loads Rule Files

When Cascade (Windsurf’s AI) opens a file or starts a task, it scans upward from the current file’s directory for rule files. The load order, highest to lowest priority:

1. .windsurf/rules/ — directory of .md files (Windsurf-specific, with optional frontmatter activation)
2. .windsurfrules — single file at the project root or in subdirectories
3. AGENTS.md — cross-tool standard, project root or subdirectories
4. CLAUDE.md — read if present (Windsurf supports cross-tool formats)
5. Global rules — set in Windsurf Settings → AI → Global Rules

All loaded rules are combined. When the same instruction appears in multiple files, the higher-priority source wins.

.windsurfrules vs AGENTS.md in Windsurf

Both files use plain markdown. The difference is that .windsurfrules (and .windsurf/rules/*.md) support activation modes via YAML frontmatter, while AGENTS.md is always active.

Setting Up AGENTS.md for Windsurf

Place AGENTS.md at your project root. Windsurf reads it automatically.

Recommended Structure

# AGENTS.md

## Project Overview
Next.js 15 frontend, Go 1.22 backend (separate repo). PostgreSQL via Drizzle.
Production deploys to Vercel (frontend) and Railway (backend).

## Core Rules

### Files — never modify
- `src/lib/auth/` — security-reviewed auth layer
- `go.sum` — do not edit manually

### Always run before committing
- Frontend: `pnpm typecheck && pnpm lint`
- Backend: `go vet ./... && go test ./...`

## Code Style

### TypeScript
- `type` over `interface` for object shapes
- Prefer `const` assertions for readonly data
- No `any` — use `unknown` with type guards

### Go
- Wrap errors with `fmt.Errorf("context: %w", err)`
- Context as first parameter, never stored in structs
- Use `defer cancel()` immediately after context creation

## Commands
- Frontend dev: `pnpm dev`
- Backend dev: `go run ./cmd/server`
- Database migrations: `pnpm drizzle:migrate`

This structure works across Windsurf, Cursor, Cline, Claude Code, and GitHub Copilot — all read AGENTS.md.

Setting Up .windsurfrules

Use .windsurfrules for rules that are specific to Windsurf’s behavior, or for conditional activation via frontmatter.

Basic .windsurfrules

# Project Rules

Follow the patterns in AGENTS.md. This file adds Windsurf-specific behavior.

## Cascade behavior
- Always show what files you plan to edit before making changes
- If a task requires modifying more than 5 files, confirm the plan first
- Don't run `npm install` or `pnpm install` during tasks — ask first

## Context hints
- The frontend and backend are separate repositories
- Check the Go backend for existing API endpoints before adding new ones

Using the .windsurf/rules/ Directory

For more control, use a directory structure:

your-project/
├── .windsurf/
│   └── rules/
│       ├── 01-standards.md
│       ├── 02-frontend.md       # activate: always
│       ├── 03-backend-go.md     # activate: glob src/backend/**
│       └── 04-testing.md        # activate: glob **/*.test.ts
├── AGENTS.md
└── src/

Activation Modes (Windsurf-Specific)

.windsurf/rules/*.md and .windsurfrules files support frontmatter activation:

Always active:

---
trigger: always_on
---

# Core Standards

These rules apply to every task.

Glob-based (only when working on matching files):

---
trigger: glob
globs:
  - "src/components/**"
  - "**/*.stories.tsx"
---

# Frontend Component Rules

- Use Storybook stories for all new components
- Composition over inheritance — extract shared behavior to hooks
- No business logic in presentational components

Model-selected (Cascade decides when to apply):

---
trigger: model_decision
description: "Rules for database schema and migration work"
---

# Database Rules

- Never drop columns — mark as deprecated with a comment
- All tables need `created_at` and `updated_at` (handled by Drizzle)
- Foreign keys must declare explicit `ON DELETE` behavior

Manual (user must explicitly invoke):

---
trigger: manual
---

# Experimental Refactor Rules

Only apply during the Q3 service extraction project.

Per-Directory Scoping

Both AGENTS.md and .windsurfrules can be placed in subdirectories. Windsurf reads the nearest file to the current working file.

your-project/
├── AGENTS.md                    # global project rules
├── .windsurfrules               # global Windsurf behavior
├── src/
│   ├── frontend/
│   │   ├── AGENTS.md            # frontend-specific (overrides root for this dir)
│   │   └── .windsurfrules       # optional Windsurf-specific for frontend
│   └── backend/
│       └── AGENTS.md            # backend-specific (Go patterns, API conventions)
└── scripts/
    └── AGENTS.md                # scripting conventions (bash, Python)

When Cascade edits a file in src/frontend/, it uses the src/frontend/AGENTS.md rules. Root AGENTS.md is not inherited automatically — the subdirectory file takes over entirely for that scope.

This is the same behavior as Cursor, Cline, and Claude Code for AGENTS.md, but different from how .cursorrules works (which doesn’t support per-directory scoping as a first-class feature).

Team Setup: Multi-Tool Projects

If your team uses Windsurf alongside Cursor, Cline, or Claude Code, keep project-wide standards in AGENTS.md and tool-specific behavior in each tool’s file:

your-project/
├── AGENTS.md                    # All tools: project standards, test commands, file rules
├── .windsurfrules               # Windsurf: activation modes, Cascade-specific behavior
├── .clinerules/                 # Cline: conditional rules, team sidebar toggles
├── .cursorrules                 # Cursor: project rules (Cursor-specific syntax)
├── .claude/
│   └── CLAUDE.md                # Claude Code: session behavior, memory config
└── .github/
    └── copilot-instructions.md  # GitHub Copilot: workspace instructions

Keep AGENTS.md as the single source of truth for rules that every tool should follow. Only duplicate into tool-specific files when the behavior differs between tools.

What Windsurf’s AGENTS.md Support Covers

Cascade reads and follows AGENTS.md instructions for:

• Code style and naming conventions
• Test requirements
• File organization patterns
• Commands to run (dev, build, lint, test)
• Off-limits files or directories
• API conventions and error handling patterns

AGENTS.md does not control Windsurf’s UI behavior, flow settings, or activation triggers — that’s what .windsurfrules frontmatter is for.

Global Rules

For rules that apply across all your projects in Windsurf, use Settings → AI → Global Rules. Enter plain text — no file needed. These load in addition to project-level files.

Example global rules:

- Never hardcode API keys or credentials
- Explain what files will change before making large edits
- Commit messages follow Conventional Commits: feat/fix/chore/docs/refactor
- Ask before running any destructive command (rm, DROP TABLE, git reset --hard)

There is no ~/.agents/AGENTS.md global path for Windsurf (unlike Claude Code, which reads ~/.claude/CLAUDE.md globally). Global Windsurf rules are stored in the Windsurf settings database, not as a file.

Common Mistakes

Putting Windsurf-specific frontmatter in AGENTS.md. Other tools will see the frontmatter as literal text, not as activation config. Keep activation frontmatter in .windsurf/rules/*.md or .windsurfrules only.

Assuming subdirectory AGENTS.md inherits from the root. It doesn’t — it replaces. If you need shared rules plus module-specific additions, copy the shared rules into each subdirectory file, or reference the root file explicitly in your instructions.

Very long AGENTS.md files. Every rule file loads on every request. A 1,000-line AGENTS.md consumes significant context. Keep project-wide rules concise and use per-directory files for module-specific detail.

FAQ

Does Windsurf read AGENTS.md automatically without configuration? Yes. Windsurf reads AGENTS.md from the project root and any subdirectories when editing files in that directory. No setup required.

Do .windsurfrules and AGENTS.md conflict? Only if they give contradictory instructions. .windsurfrules (and .windsurf/rules/) takes priority when there’s a conflict. The usual pattern is to put shared standards in AGENTS.md and Windsurf-specific behavior in .windsurfrules.

Can I use both .windsurf/rules/ and .windsurfrules in the same project? Yes. Both are loaded. .windsurf/rules/*.md files are processed individually (useful for activation mode control); .windsurfrules is loaded as a single file.

Does Windsurf support the @import syntax from CLAUDE.md? No. Windsurf doesn’t support referencing external files from within AGENTS.md or .windsurfrules. Keep rules self-contained in the file.

What’s the difference between Windsurf’s AGENTS.md support and Cursor’s? Functionally similar — both read the file from the project root and respect subdirectory scoping. The main difference is activation modes: Windsurf supports trigger: glob and trigger: model_decision in .windsurfrules; Cursor’s equivalent is .cursor/rules/*.mdc files with globs frontmatter.

For cross-tool rule file examples and AGENTS.md templates from real projects, see our gallery — we track 500+ AGENTS.md and CLAUDE.md files from open-source repositories.