Dan's Quick n Dirty Cursor AI Guide

cursor-ai-guide.md

Cursor AI Guide

Status: Current Last Updated: 2026-04-07

This guide covers how to effectively use Cursor AI for development within MindWeaver. For a quick-start overview, see Cursor AI 101.

Core Principle: Manage the Problem Scope

The single biggest factor in whether AI-assisted coding works is matching the problem scope to the right approach.

 Problem Scope          Example                   Cursor Approach
─────────────────────────────────────────────────────────────────────────
 MICRO                  "Tell me about X"         Ask Mode
                                                        │
 SMALL                  "Fix this bug"            Debug / Agent
                                                        │
 MEDIUM                 "Add this feature"        Plan → Agent (or decompose)
                                                        │
─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┤─ ─ ─ ─ ─ ─ ─ ─
 LARGE                  "Build a subsystem"             │
                                                   Decompose first:
 MACRO                  "Build an app"             Write docs → Roadmap → Phases
                                                        │
                                                        ▼
                                                   Tasks (each one is
                                                   SMALL or MEDIUM scope)
                                                        │
                                                        ▼
                                                   Implement via:
                                                   • Agent
                                                   • Ask → Agent
                                                   • Plan → Agent
                                                   • Multi-Agent
                                                   • SDD (SpecKit)

For large and macro-scale work, the approach is not "prompt the agent and hope for the best." Instead, decompose first: build a roadmap of phases and tasks, then implement each task at the appropriate scope level.

Interaction Modes

Mode	When	What it does
Ask	"How does X work?"	Read-only exploration, no file changes
Debug	Runtime errors, weird behaviour	Investigates with terminal/log context
Agent	"Build this thing"	Writes code, runs commands, makes changes
Plan	"Let's think before we build"	Discusses approach, then hands off to Agent

Tips:

• Ask mode is underrated — use it to force the agent to think deeply before writing code.
• Plan mode decouples planning from implementation, effectively doubling your usable context window (one agent plans, another implements).

Model Selection

Tier	Good for	Trade-off
Auto / Standard	Routine tasks, simple refactors, boilerplate	Fast, cheap
Mid-range (Sonnet 4.6)	Day-to-day coding	Good balance
High-reasoning (Opus 4.6, GPT-5.3 High)	Architecture, complex debugging, multi-agent	Slower, expensive

Opus 4.6 supports multi-agent teams — useful for large-scale refactors or complex architectural work.

Context Management (@docs)

Treat documentation as modular context windows. Instead of relying on the model's training data, explicitly reference docs to ground the agent:

Task Type	Load
Structural changes	@docs/architecture/
Backend integration	@docs/services/ivcap/README.md
State management	@docs/stores/README.md + specific store doc
Feature context	@docs/features/ + specific feature doc
Conventions check	@docs/contributing/conventions.md

Example usage in chat:

"Implement the new dataset fetching logic. Reference @docs/services/ivcap/README.md and @docs/stores/datasets.md for patterns."

The Docs Are Alive

The docs/ directory is a living part of the project. When modifying code, ensure the relevant docs are updated to reflect the changes. Stale docs actively harm agent performance.

MCP Servers

MindWeaver uses MCP (Model Context Protocol) servers to extend agent capabilities:

• Chrome DevTools MCP: Inspect DOM, computed styles, console errors, network failures, screenshots. Useful for debugging UI issues.
• Sequential Thinking: Breaks down complex problems into steps before acting. Reduces hallucination on deep architectural tasks.

MCP configuration lives in .cursor/mcp.json.

Agent Skills

The project includes specialised skills in .cursor/skills/. These are structured instructions the agent can read to gain expert knowledge on specific domains:

Usage: Ask the agent to read the relevant skill before performing a complex task:

"Read .cursor/skills/ivcap-api-integration/SKILL.md then help me implement the jobs poller."

Spec-Driven Development (SDD)

MindWeaver uses SpecKit for spec-driven development. The workflow:

1. Specification: Use /speckit.specify and /speckit.plan to generate specs in .specify/
2. Implementation: Reference specs to keep the agent aligned during coding
3. Phases: Architect phase generates specs/tasks, Builder phase implements them

Specs and tasks live under specs/ and .specify/. SpecKit commands are in .cursor/commands/.

Caveats: SDD is token-hungry. SpecKit uses feature branches, which limits concurrent multi-agent spec work.

Working Effectively

Fresh Context vs. Pushing Further

There's a tradeoff between starting fresh (clean context) and continuing a conversation (avoids re-populating context). Cursor supports context compaction/summarisation — the declared window is not a hard limit.

Iterative Prompting

You do not need the perfect prompt. Have a conversation with the agent — refine iteratively.

Privacy Mode

Settings > General > Privacy — when enabled, no code is stored on Cursor's servers or used for training.