Using with Cursor / Windsurf

Cursor and Windsurf are AI-native code editors built on VS Code. They support project-level context files that work similarly to Claude Code's CLAUDE.md — once set up, your AI has full awareness of your build package every time you open the project.

Cursor setup

1. Create a .cursorrules file

Cursor reads a .cursorrules file from your project root. Create it and paste this content — it instructs Cursor's AI to load your package:

You are building a product defined in project.md in this project root.

Before writing any code for a new feature or task:
1. Read project.md for product context and stack decisions
2. Read the relevant file(s) in /skills/ for implementation guidance
3. State your plan before acting

Key files to know:
- project.md — master product brief, data models, feature scope
- skills/skill-core-app.md — app structure and coding conventions
- skills/skill-auth.md — authentication patterns
- skills/skill-billing.md — subscription and payment logic
- All other skills/ files — domain-specific guidance

Always follow the patterns in the skill files. Do not introduce 
libraries or patterns not mentioned unless you explain why first.

2. Add skill files to Cursor's context

Open Cursor and press Cmd+Shift+P → Cursor: Open Rules. You can also manually add files to context in any chat with @file:

@project.md @skills/skill-auth.md 
Build the user authentication flow as described.

3. Use the Composer for full-file generation

Cursor's Composer (Cmd+I) is best for generating entire files or features. Always open it with your skill file referenced:

@project.md @skills/skill-core-app.md
Create the main dashboard layout page as described in project.md.
Follow all conventions in skill-core-app.md.

Windsurf setup

1. Use the global rules

Windsurf supports global and project-level AI rules. Open Settings → AI → Rulesand add a project rule pointing to your skill files:

This project is defined in project.md. 
Before writing any code, read project.md and the relevant 
file in /skills/ for the domain you're working in.

Always follow the patterns and stack choices described 
in the skill files. Reference them explicitly when 
explaining your implementation approach.

2. Use Cascade with file references

Windsurf's Cascade agent works best when you explicitly reference files. Start any feature with:

Read @project.md and @skills/skill-[relevant].md.
Then build [feature description].

General tips for any AI IDE

Regardless of which IDE you use, these habits will keep your AI building consistently:

• Always reference the skill file for the domain you're working in. Don't assume the AI remembers it from earlier in the session.
• Ask for a plan before code. "Tell me your approach before writing anything" catches misunderstandings early.
• One feature at a time. AI IDEs produce better results with focused, scoped tasks than with broad requests.
• Update skill files when decisions change. The skill files are the source of truth — if you change a library or pattern, update the file so the AI picks it up.
• Commit often. AI can make sweeping changes. Committing after each working feature gives you a clean rollback point.