How Cursor AI understands your codebase — rules, playbook, review, and tests (booking + MLM example)

Cursor does not wake up knowing your app.

It does not know that salon booking and MLM membership are different animals that share a login — until you tell it, repeatedly, in files it actually reads.

I've watched AI confidently:

• book two customers on the same stylist at 2:00 PM
• and credit two uplines for the same referral
• in the same pull request
• with a commit message that says fix: minor updates

That's not Cursor being evil. That's Cursor being fast in a repo with no map.

This post is how I teach Cursor to understand a real codebase — rules, playbook, review, tests — using an example project: a booking platform with MLM membership (salon sessions + member portal + commission wallet). The same workflow I use on this portfolio, PHP backends, and production mobile at DSSI.

Who this is for: developers using Cursor daily, founders whose dev uses AI, and anyone who asked "why does AI keep inventing a new folder structure every session?"

Related: Copilot vs Claude vs Cursor · AI didn't fail — your prompt did · AI engineering · booking platform developer · MLM portal developer

TL;DR — too long; didn't let AI merge

• Cursor indexes your repo — it searches files; it does not magically feel your intent.
• Rules = house laws in .cursor/rules/ (stack, naming, what never to touch blind).
• Playbooks = step-by-step recipes in .cursor/rules/playbooks/ for recurring jobs (new booking screen, wallet API, admin report).
• Project brain (CURSOR.md, README) = what the product is — booking + MLM in our example.
• Review = you read the diff before wallet or calendar math ships.
• Tests = the awkward friend who says "actually that slot was already taken."
• No rules + vague prompt = architectural improv comedy (you're not laughing).

The example project — booking + MLM membership

Imagine one platform for a Philippine network that also runs branded salons:

One login. Two domains of pain. Perfect teaching material.

Folder sketch (simplified):

booking-mlm-platform/
├── CURSOR.md                 # project brain — read first
├── .cursor/
│   ├── rules/
│   │   ├── global.md
│   │   ├── booking.md
│   │   ├── mlm-wallet.md
│   │   ├── php-api.md
│   │   └── playbooks/
│   │       ├── new-booking-screen.md
│   │       └── mlm-commission-report.md
│   └── hooks/
│       └── pre-commit.sh
├── docs/
│   ├── booking-flow.md       # slot lock, cancel tree
│   └── mlm-ledger-rules.md   # human-defined commission rules
├── api/                      # PHP + MySQL
│   ├── booking/
│   └── mlm/
├── apps/
│   ├── member-web/
│   └── admin-web/
└── tests/
    ├── booking/
    └── mlm/

If you dump "build booking + MLM app" with none of that, Cursor will still generate code. It will also generate surprises.

How Cursor actually "understands" your codebase

Plain language version:

1. Index — Cursor chunks and searches your files (like a very eager intern with Ctrl+F superpowers).
2. Context window — only so much fits per request; big repos need pointed prompts (@booking/, @mlm-wallet.md).
3. Rules — injected every session so it doesn't "forget" you're on PHP 8.2 and hate surprise Redux.
4. Your prompt — the task for this diff only.
5. Agent — proposes multi-file changes.
6. You — approve, reject, or cry.

Cursor does not understand your business unless business rules live in markdown or code it can read.

Example: "Members earn 5% on salon package booked by downline" belongs in docs/mlm-ledger-rules.md — not in a WhatsApp voice memo.

Layer 1 — Project brain (CURSOR.md)

Top of the repo. Short. Brutal. Boring on purpose.

What goes here for booking + MLM:

• Product one-liner
• Stack (PHP API, React admin, Framework7 mobile — whatever is real)
• Modules map: booking vs MLM vs shared auth
• Never auto-merge list: wallet, commission batch, slot lock SQL
• Link to process flows in docs/

# Booking + MLM Platform

## Modules
- booking/ — salon sessions, slot locks, stylist calendars
- mlm/ — genealogy display, wallet ledger, rank display (rules in docs/mlm-ledger-rules.md)

## Non-negotiable
- Human review before any wallet UPDATE or commission INSERT
- Booking holds must use DB transaction + row lock on slot
- No new npm/composer packages without note in PR

## AI workflow
- Small diffs. One feature per agent run.
- Run tests: booking slot conflict + wallet idempotency

When Cursor opens the project, this is the orientation lecture — not the feature spec.

Layer 2 — Rules (house laws)

Rules are always-on. Think bouncer at the club, not suggestions on a napkin.

Split by domain — critical for booking + MLM combo. Files live in .cursor/rules/:

.cursor/rules/global.md

• Match existing patterns; minimal diff
• No secrets in code
• Typecheck / lint must pass before you call it done

.cursor/rules/booking.md (globs: api/booking/**, booking UI)

• Slot availability must check appointments with lock — see docs/booking-flow.md
• Cancel policy: free before 24h, fee after — constants in one file
• Never delete appointments; soft-cancel with status enum

.cursor/rules/mlm-wallet.md (globs: api/mlm/**)

• AI may draft wallet read APIs and report queries
• AI may not merge payout batch logic without human label finance-approved
• Commission math follows docs/mlm-ledger-rules.md only — no improvising "5% feels right"

.cursor/rules/php-api.md

• Native PHP, prepared statements, no string-concat SQL
• JSON error shape matches existing { error, code } pattern

Bad rule: "Write good clean code."
Good rule: "Booking slot checks use SELECT ... FOR UPDATE in BookingRepository::holdSlot()."

Without .cursor/rules/mlm-wallet.md, AI will happily add a quick_payout_fix.php. You will find it on a Saturday.

Layer 3 — Playbooks in .cursor/rules/ (recipes)

Playbooks are how to do one job right — stored as rule files under .cursor/rules/playbooks/, not everything at once.

Examples for our project:

Playbook: .cursor/rules/playbooks/new-booking-screen.md

1. Read docs/booking-flow.md
2. Copy layout from apps/member-web/src/screens/ServiceList.tsx
3. Wire to POST /api/booking/hold-slot — do not invent new endpoint names
4. States: loading, empty, conflict (409), success
5. Output checklist for human: timezone, stylist id, double-book test

Playbook: .cursor/rules/playbooks/mlm-commission-report.md

1. Read docs/mlm-ledger-rules.md
2. Read-only SQL first; no UPDATE in same PR as report
3. Match admin table component from existing reports
4. Flag rows where payout_status = pending > 7 days

Playbooks save you from re-typing the same lecture every Monday.

On Cursor projects, I keep playbooks beside domain rules in .cursor/rules/. Same discipline on this portfolio — project docs and checklists before features ship.

Layer 4 — Process flow docs (the real source of truth)

AI drafts faster from flows. Skipping flows guarantees rework.

docs/booking-flow.md (excerpt):

Customer picks service → picks stylist → picks slot
→ POST hold-slot (transaction + lock)
→ payment within 10 min or release
→ confirmed → reminder → complete / no-show / cancel (fee?)

docs/mlm-ledger-rules.md (excerpt):

Retail salon package purchased by member M
→ sponsor S gets Level-1 retail bonus per plan table v3.2
→ wallet credit PENDING until T+2 finance batch
→ idempotency key = order_id + rule_id

Cursor doesn't invent stable MLM law. Your counsel + finance team does. Code reflects the doc.

Cross-link if you're scoping hire: MLM trust and legal.

Layer 5 — Prompting one feature (not the whole universe)

Cursed prompt:

Build booking and MLM membership with payments and genealogy thanks

Blessed prompt:

@docs/booking-flow.md @api/booking/hold-slot.php Add reschedule for customer — only if slot free, same rules as hold-slot. Small diff. Include test for conflict when new slot taken.

Cursor understands one hallway at a time. Not the whole building, elevator, and parking lot.

Layer 6 — Review (where adults enter the room)

My review checklist for booking + MLM changes:

If the diff touches wallet or slot lock, I slow down. I ask Cursor to explain the transaction boundary. I do not merge because the chat said "looks good."

Works in chat is not a release criterion. Works on staging with evil concurrent clicks is closer.

Layer 7 — Tests (boring until they save you)

Minimum tests worth writing for booking + MLM:

Booking

• Hold slot → success
• Hold same slot again → 409 conflict
• Payment timeout → slot released
• Cancel inside policy → correct fee

MLM

• Commission credit once per order_id (idempotency)
• Wallet balance never negative after concurrent webhook retries
• Member cannot call admin payout endpoint

AI is great at drafting these tests. You still verify they assert the right evil — not expect(true).toBe(true) performance art.

Run before merge:

pnpm test          # or phpunit / vitest — whatever the repo uses
pnpm typecheck
pnpm lint

Hooks help. A pre-commit hook in .cursor/hooks/ or your repo scripts is the "please don't embarrass us" line of defense.

The playbook — one session start to merge

Copy this for your booking + MLM repo (or any product):

1. Open CURSOR.md — confirm module boundaries
2. Pick one feature — e.g. "member books salon package that counts toward volume"
3. Attach context — @docs/booking-flow.md @docs/mlm-ledger-rules.md relevant API files
4. Use a playbook rule if you have one — or paste playbook steps from .cursor/rules/playbooks/
5. Agent small diff — one PR-sized change
6. Review — wallet, slots, auth, roles
7. Run tests — add one if missing for the bug you almost shipped
8. Merge — deploy — monitor — resist "AI fix prod without reading logs"

Repeat. The repo gets smarter because docs and rules accumulate, not because the model remembered your vibe from Tuesday.

What founders should ask their AI-using developer

• Where are the rules stored?
• Where is the booking flow written down?
• Where are commission rules defined — code, doc, or "trust me"?
• What gets human review every time?
• What tests block wallet and double-book regressions?

If the answer is "we just prompt Cursor," you're paying for speed now and incidents later. Possibly on the same salon chair.

Common failure modes (comedy, but real)

Bottom line

Cursor understands your codebase the way a new senior hire would — if you give them:

• a map (CURSOR.md)
• house rules in .cursor/rules/
• recipes (playbooks in .cursor/rules/playbooks/)
• business truth in docs
• a tight prompt per task
• your review on money and time slots
• tests that prove the evil cases

Booking + MLM in one platform is a stress test. Two ways to break time (calendar) and money (wallet). Get those gates right and AI is a force multiplier. Skip them and you get a very fast path to a very slow support queue.

That's the playbook I use. Fast drafts. Careful release. Same rule as production-ready AI dev.

---

Setting up Cursor rules on a booking, MLM, or multi-module product? AI engineer services · Get in touch — happy to talk playbook, review gates, and what not to let AI merge unsupervised.

FAQ

Does Cursor automatically understand my entire codebase?

It indexes and searches your repo, but understanding is only as good as your structure, rules, and docs. Large repos need scoped prompts (@folder, @file) and domain rules — especially for mixed products like booking + MLM.

What should I put in CURSOR.md or the project brain file?

Product summary, module map, stack, folders Cursor should match, never-auto-merge list, and links to flow docs. Short and enforceable — not a novel. Pair it with domain rules in .cursor/rules/.

What is the difference between Cursor rules and playbooks?

Rules in .cursor/rules/ are always-on constraints (stack, naming, never touch wallet blind). Playbooks in .cursor/rules/playbooks/ are step-by-step recipes for recurring tasks (new booking screen, commission report). Rules are laws; playbooks are recipes.

Why use a booking + MLM example for a Cursor playbook?

Because it's a realistic hard combo — time slots and money ledger in one product. If your AI workflow survives that, simpler apps are easier. Patterns apply to any multi-module platform.

Where should commission and booking business rules live?

In human-approved markdown docs (mlm-ledger-rules.md, booking-flow.md) that code and AI reference — not improvised in chat. Legal and finance own MLM rules; developers wire what is approved.

How do I stop AI from breaking wallet or double-booking logic?

Domain rules files in .cursor/rules/, small diffs, mandatory human review on mutating paths, and tests for idempotency + slot conflict. Auto-merge on wallet logic is a hard no.

Can AI write tests for booking and MLM modules?

Yes — draft conflict tests, webhook idempotency tests, and role-guard tests. You must verify they test real edge cases, not placeholders. AI speeds test authoring; you own assertions.

How does this relate to GitHub Copilot or Claude?

Copilot excels at inline completion; Claude at long reasoning in chat. Cursor adds repo context + agents + project rules in one IDE workflow. I compared all three in this post.

What hooks or checks should run before commit?

At minimum: lint, typecheck, and tests on touched modules. Pre-commit hooks catch embarrassment before Vercel or clients do. Wallet and booking PRs deserve manual review even when bots pass.

When should a company hire help to set this up?

When you have a real multi-module product (booking, MLM, commerce, delivery), more than one developer, or AI output hitting production without consistent review. Setup cost beats one bad payout or double-book incident.