Cursor Agent Guides

Note: These are meta-guides for working with Cursor Agent across projects, not documentation for a specific project.

Overview

This directory contains guides to help you work effectively with Cursor Agent when building web applications. The guides cover everything from getting started to maintaining documentation as your project grows.

Guide Index

Getting Started

🚀 FIRST-STEPS.md

Start here if you're beginning a new project

Learn how to:

• Communicate requirements effectively
• Choose tech stacks
• Get your first MVP built
• Work iteratively with Cursor Agent

Best for: Brand new projects, first-time users

📋 HOW-TO-PROVIDE-REQUIREMENTS.md

Master the art of describing what you want to build

Covers:

• Ideal requirement format
• What to include and what to skip
• Examples from minimal to detailed
• Quick templates

Best for: Before starting any project, clarifying vision

---

Documentation & Context

📝 HOW-TO-DOCUMENT-FEATURES.md

Where and how to document your project

Covers:

• Where to document features (README, FEATURES.md, etc.)
• How to structure CHANGELOG/DEVLOG/DECISIONS files
• Using archive/ for failed experiments
• Documentation workflows and templates
• Scaling documentation as project grows

Best for: Active development, maintaining project clarity

📄 HOW-TO-CREATE-README.md

Create a README that helps both humans and AI

Explains:

• Critical README elements
• Architecture decision documentation
• Known issues and limitations
• Complete README template
• What makes it AI-friendly

Best for: Starting projects, major refactors, improving existing README

📊 HOW-TO-TRACK-CHANGES.md

Track development history for AI context

Covers:

• Writing meaningful commit messages
• Using CHANGELOG/DEVLOG/DECISIONS effectively
• When and how to comment code
• Archiving failed experiments
• Minimum viable tracking

Best for: Ongoing development, team collaboration

---

AI Optimization

🤖 FILE-IMPORTANCE-FOR-AI.md

Understand what helps AI assist you best

Explains:

• Which files Cursor Agent prioritizes and why
• Why CHANGELOG/DECISIONS matter most
• How documenting failures prevents repeated mistakes
• What to include in commit messages
• File organization recommendations

Best for: Optimizing AI collaboration, understanding AI workflow

---

Quick Start Workflow

1. Before Building
   └─> FIRST-STEPS.md + HOW-TO-PROVIDE-REQUIREMENTS.md
       └─> Describe what you want
           └─> Get started with clear vision

2. Creating Project Structure
   └─> HOW-TO-CREATE-README.md
       └─> Set up README with tech stack, decisions, features
           └─> Establish documentation foundation

3. During Development
   └─> HOW-TO-DOCUMENT-FEATURES.md + HOW-TO-TRACK-CHANGES.md
       └─> Create TODO.md, CHANGELOG.md, document decisions
           └─> Track progress and changes

4. Optimize for AI
   └─> FILE-IMPORTANCE-FOR-AI.md
       └─> Understand what AI needs
           └─> Better collaboration across sessions

Key Principles Across All Guides

1. Document the "Why" Not Just "What"

Code shows what it does. Documentation should capture:

• Why this approach over alternatives
• What was tried and failed
• Tradeoffs that were accepted
• Context for future decisions

2. Start Simple, Scale as Needed

Small projects: Just README.md Medium projects: Add CHANGELOG.md, FEATURES.md, TODO.md Large projects: Create docs/ folder, DECISIONS.md, archive/

3. Failed Experiments Are Valuable

Always document before removing code:

• What you tried
• Why it didn't work
• What you switched to
• Archive the old code if substantial

4. Consistency Helps AI

When files follow consistent patterns, Cursor Agent can:

• Find information faster
• Avoid suggesting failed approaches
• Make better architectural decisions
• Work more efficiently across sessions

Recommended File Structure

Minimal (Day 1)

project/
├── README.md              # Overview, features, setup
├── package.json           # Dependencies
└── .cursor-guides/        # These meta-guides

Standard (Week 2+)

project/
├── README.md              # Current state
├── CHANGELOG.md           # Decisions & development log
├── TODO.md                # Current work
├── package.json           # Dependencies
├── .env.example           # Configuration
└── .cursor-guides/        # These meta-guides

Mature (Month 2+)

project/
├── README.md              # Overview
├── CHANGELOG.md           # Development log
├── FEATURES.md            # Detailed features
├── TODO.md                # Active work
├── package.json           # Dependencies
├── .env.example           # Configuration
├── archive/               # Failed experiments
└── .cursor-guides/        # These meta-guides

Comprehensive (Month 6+)

project/
├── README.md              # Overview + quickstart
├── CHANGELOG.md           # Development log
├── DECISIONS.md           # Architectural choices
├── docs/
│   ├── FEATURES.md
│   ├── ROADMAP.md
│   ├── ARCHITECTURE.md
│   └── API.md
├── archive/               # Experiments
└── .cursor-guides/        # These meta-guides

Most Important Files for AI

In order of priority:

1. README.md - Project overview and current state
2. Dependency files - Tech stack and versions
3. CHANGELOG/DEVLOG/DECISIONS - Context and history (MOST VALUABLE)
4. Configuration files - Architecture and setup
5. Git commits - Recent changes with good messages
6. Entry points - Application structure
7. TODO/FEATURES/ROADMAP - Planned work
8. Business logic - As needed for specific tasks
9. Tests - Expected behavior
10. Documentation folders - Deep technical context

Common Patterns

Document a Failed Experiment

## 2025-10-06: Switched from WebSockets to SSE

**Tried:** WebSocket connections for real-time updates
**Problem:** 30-second timeout on mobile, frequent disconnections
**Solution:** Server-Sent Events with automatic reconnection
**Tradeoff:** One-way communication, but more reliable
**Code:** Archived to archive/websocket-version/

Archive Code Before Deletion

# Before removing substantial code
mkdir -p archive/old-feature-name
cp -r src/feature archive/old-feature-name/
# Document in CHANGELOG.md why it was removed
git add archive/
git commit -m "Archive old feature before removal"

Write Informative Commit Messages

Good: Switch to SSE for real-time updates

Why: WebSocket connections unstable on mobile (30s timeout)
How: Server-Sent Events with automatic reconnection
Impact: Reliable updates across all devices

Bad: fix websocket issue

Tips for Working With Cursor Agent

✅ DO:

• Give clear requirements but trust AI to handle details
• Document decisions as you make them
• Keep CHANGELOG current with "why" explanations
• Archive code before major refactors
• Use commit messages to explain context
• Cross-reference related files

❌ DON'T:

• Micromanage implementation details
• Delete working code without documentation
• Let documentation drift from reality
• Use vague commit messages ("fix", "update")
• Duplicate information across files
• Over-document obvious code

Getting Help

These guides cover:

• ✅ How to work with Cursor Agent
• ✅ Project structure and documentation
• ✅ File organization best practices

These guides do NOT cover:

• ❌ Language-specific syntax
• ❌ Framework-specific tutorials
• ❌ Deployment procedures
• ❌ Project-specific documentation

For project-specific help, ask Cursor Agent directly!

Meta Note

These guides themselves follow the principles they teach:

• Clear purpose and structure
• Cross-references between related content
• Practical examples over theory
• Scalable from simple to complex
• Focused on "why" not just "how"

---

Ready to build something? Start with FIRST-STEPS.md!