AI Coding · Rules Files

What Is .windsurfrules?
Windsurf’s rules file and folder

You are using Windsurf, the AI IDE, or you saw a .windsurfrules in a repo. It is how you give Windsurf project rules: instructions about your stack, conventions, and commands, so its agent works on your project the way you want.

Like Cursor, Windsurf has an older and a newer form of this: a single .windsurfrules file, or a .windsurf/rules/ folder of Markdown files. Here is what each is and what goes inside.

Two forms: the legacy file or the .windsurf/rules/ folder

  • A single .windsurfrules file at the repo root is the older way, all your rules in one place.
  • A .windsurf/rules/ folder is the newer form, holding several Markdown files that Windsurf loads together, one per topic. It keeps things tidy once the rules grow. See how to organize .md files for keeping such a folder readable.

Either way, the content is the same, and it is all Markdown.

What goes inside

A .windsurfrules holds the same kind of thing every AI rules file holds: your stack and architecture, code conventions and style, the commands to run, and boundaries for what the agent should and should not touch. It is plain Markdown, so it is just headings and lists describing your project. If you are writing one, how to write Markdown covers the syntax.

.windsurfrules and the other rules files

Nearly every AI coding tool has its own version of this file. .windsurfrules is Windsurf’s:

Tool Its rules file From
Windsurf .windsurfrules or .windsurf/rules/*.md Codeium’s AI IDE
Cursor .cursorrules or .cursor/rules/*.mdc Cursor editor
Cline .clinerules (file or folder) VS Code coding agent
Cross-tool AGENTS.md The shared open standard

For the full map by tool, see which AI rules file your tool reads; for the closest cousin, what a .cursorrules file is and what .clinerules is; and for the cross-tool standard, what AGENTS.md and CLAUDE.md are.

Reading and editing .windsurfrules with NoteLoom

The .windsurf/rules/ folder is a natural fit for NoteLoom, because a folder of Markdown files is exactly what it is built to open. Mount the folder in the browser and NoteLoom renders each .md in a clean reading view, with a file tree to move between them, and a source view to edit and save back to disk. A growing set of rule files stays easy to read and keep tidy.

To be clear about the boundaries: NoteLoom has no AI and does not connect to Windsurf or any coding tool. It opens, renders, and saves the Markdown files locally; whether the agent follows the rules stays between you and Windsurf.

How you use it: open app.noteloom.cc in Chrome / Edge / Arc, mount your .windsurf/rules/ folder itself (pick that folder as the root, not a parent), and read or edit the .md files inside. Saved straight to your disk, no cloud, no account.

Related reading

Which AI rules file does your tool read? .windsurfrules, .cursorrules, CLAUDE.md, and more, mapped by tool. What is a .cursorrules file? Cursor’s version, which evolved the same file-to-folder way. What is .clinerules? Cline’s version, also a single file or a folder of Markdown. What are AGENTS.md / CLAUDE.md? What goes inside the rules files, and the cross-tool standard. Online Markdown Editor Mount a folder and read or edit its .md files in your browser.

FAQ

What is a .windsurfrules file?
It is how you give Windsurf, the AI IDE, rules for your project: instructions about the stack, conventions, and commands so its agent works the way you want. It comes as a legacy single .windsurfrules file at the repo root, or a modern .windsurf/rules/ folder of Markdown files.
What is the difference between .windsurfrules and .windsurf/rules/?
Same purpose, an older and a newer form. The single .windsurfrules file at the repo root is the legacy way; the .windsurf/rules/ folder is the newer one, holding several Markdown rule files that Windsurf loads together. The folder is the more organized, recommended form once your rules grow.
What should a .windsurfrules contain?
The usual rules-file content: your stack and architecture, code conventions, the commands to build and test, and boundaries for what the agent should and should not do. It is Markdown, so it is headings and lists describing your project.
Is .windsurfrules the same as .cursorrules or AGENTS.md?
Same idea, different tool. .windsurfrules is Windsurf’s, .cursorrules is Cursor’s. Windsurf also reads AGENTS.md, the cross-tool open format, so if you want one file most agents understand, that is the safer bet.
Can NoteLoom open a .windsurf/rules/ folder?
Yes. The .windsurf/rules/ folder holds Markdown files, and NoteLoom is built to mount a local folder and read and write the .md files inside it. It renders each one in a clean view and lets you edit in the source view. It has no AI: it will not make Windsurf follow the rules, it just helps you read and write the files.
Can I do this with NoteLoom on my phone or in Safari?
Not for now. NoteLoom relies on the browser’s File System Access API, which currently works in Chromium-based desktop browsers like Chrome, Edge, and Arc. Firefox, Safari, and mobile are not supported yet.

Open your .windsurf/rules folder and read it

Open NoteLoom in Chrome / Edge / Arc, mount your .windsurf/rules/ folder, and read or edit the Markdown rule files inside, all in a clean view. Saved straight back to your disk, no software to install and no account to sign up for.

Open NoteLoom and try it