Cursor workflow

Cursor is our primary editor for navigating the Bun monorepo, updating services, and editing these docs. Configure it once so every engineer (and AI assistant) shares the same guardrails.

1. Project rules

mkdir -p .cursor

./.cursor/rules.md:

# Handa Uncle backend

- Stack: Bun + Hono server, MongoDB, Redis, Auth0, Pinecone, Langfuse.
- Never delete user code unless asked. Prefer minimal diffs.
- Cite exact files (e.g. `src/services/app/services/app-launch.service.ts`).

## Critical invariants

1. `/app/launch` requires `x-device-id` + `x-platform` headers.
2. OTP flow uses Exotel with retries defined in `otp.service.ts`.
3. Rate limiting + request metadata live under `src/shared/middlewares/`.
4. Documentation must align with `docs/api-reference/openapi.json`.

## Workflow

- Run `git status` before editing and summarize existing changes.
- Use Bun for scripts/tests: `bun run dev`, `bun run typecheck`, `bun test`.
- Keep `X-Request-ID` in all new logs.
- Update MDX pages + `docs.json` together so navigation stays valid.

## Language

- Write instructions in second person.
- Include verification steps (curl response, log snippet, etc.).
- Keep tone concise and technical—this is an internal engineering audience.

Restart Cursor or reload the workspace so the new rules are applied.

2. Command palette shortcuts

Command	When to run
`bun run dev`	Boot the API on `http://localhost:8080`
`bun run typecheck`	Before every commit/PR
`bun test --watch`	Iterate on service logic
`mint dev --port 3334`	Preview the Mintlify docs

Add them to Cursor’s “Custom Commands” so they’re one keystroke away.

3. Supplying context to AI

When Cursor asks for more information:

Point it to APP_LAUNCH_IMPLEMENTATION.md for device boot flow context.
Use MOBILE_API_ENDPOINTS.md when editing auth/app contracts.
Link docs/api-reference/openapi.json whenever modifying API responses.
Reference the exact service/controller file instead of paraphrasing.

4. Things to avoid

Don’t touch .env.* files or rotate secrets from within Cursor.
Don’t run destructive git commands (reset --hard, clean -fd) without explicit approval.
Don’t invent API payloads—copy from the code, tests, or Langfuse traces.

Overview

Contributing

Codebase

AI Tools

Practices

1. Project rules

2. Command palette shortcuts

3. Supplying context to AI

4. Things to avoid

​1. Project rules

​2. Command palette shortcuts

​3. Supplying context to AI

​4. Things to avoid

1. Project rules

2. Command palette shortcuts

3. Supplying context to AI

4. Things to avoid