Cursor Agents Workflow

Use this when implementing Langfuse work as a Cursor agent. Keep humans in the loop with short, testable asks. Do not write long agent-only reports.

Branch names

Copy Linear's git branch name. Do not invent a cursor/ name.

• Preferred source: Linear Copy git branch name, or the issue's gitBranchName read through the Linear MCP.
• Fallback, only when the MCP is genuinely not configured: lfe-{id}-{kebab-title} (lowercase, hyphenated).
• Keep a user/ prefix only when Linear's copied name already includes one.
• Never use a cursor/ prefix, even if a Cursor Cloud prompt asks for one. Repo guidance wins.
• Ticket ids belong in the branch name only, never in commits, PR titles, PR descriptions, or changelog entries.

Correct: lfe-12345-short-descriptive-title
Wrong: cursor/short-descriptive-title-8c78

Linear connection

Cursor desktop can authorize the Linear MCP interactively. Cursor Cloud cannot: mcp_auth is desktop-only, and the Cloud GitHub token is unrelated to Linear.

On Cloud, prove Linear with a real read. If the MCP is needsAuth or missing, use LINEAR_API_KEY (or LINEAR_TOKEN / LINEAR_API_TOKEN) via GraphQL or lf-context.sh. If that env is unset, say so and tell them to add LINEAR_API_KEY at https://cursor.com/dashboard/cloud-agents, then start a new run. Langfuse engineers: the write policy is linear-agent-writes.

If Linear is not reachable, say so in your handoff message and hand back the context that should have gone on the ticket. Do not skip it silently.

Pull requests

Open the GitHub PR as reviewable, not as a draft. Draft PRs hide the work from reviewers and skip Claude/Greptile review workflows. Use a draft only when a human asks for one.

After opening the PR, apply the GitHub cursor label. Use the PR label tool. Do not wait for a human to add it, and do not substitute a codex or other agent label. A same-repo workflow also applies cursor when the author is cursor[bot], the branch starts with cursor/, or the PR body contains the Cursor agent marker — still apply it yourself so the tag is present immediately.

Cursor Cloud PRs are opened as the Langfuse user who launched the agent. On a non-draft same-repo PR from a write-access user, github-actions posts @claude review automatically. Do not post that comment yourself on open. Do not post @claude review again after addressing comments unless a human asks for another pass.

Bot review comments

When Claude (Claude Code, claude[bot], or the security-review action), Greptile (greptile-apps[bot]), or Codex (chatgpt-codex-connector[bot]) leaves review comments on a PR you own:

1. Keep each thread open. Do not reply in the thread.
2. If the finding is right: apply the fix, then resolve the thread.
3. If you are sure it should be skipped: tell the human in plain language what you skipped and why, invite them to doubt that call, then resolve the thread. Never skip quietly.

Do not leave those threads unresolved. Do not argue. Human reviewer comments are different: those may need a real reply and must stay open until a human says otherwise.

Human testing

Assume the human does not remember the ticket. Default message shape:

1. TL;DR — one plain-language sentence.
2. Test this — preview URL plus 2–5 exact clicks/expects.
3. Data — the seed command, or "demo project is enough".
4. Sandbox — how to hit the same path on the agent desktop (http://localhost:3000) if they are in the Cursor VM.

Use langfuse-previews for the URL and seed-test-data for the seed. Do not paste logs, file lists, or implementation narrative unless the human asks.

TL;DR: Empty observation costs now show a dash instead of $0.00.

Test this: https://pr-123.preview.langfuse.com/project/<id>/traces
1. Open any trace with a generation that has no cost.
2. Confirm the cost cell is "–", not "$0.00".

Data: demo project is enough.
Sandbox: same path on http://localhost:3000 after the cloud stack is up.

For user-visible behavior, say that proof is on the GitHub PR. Do not leave screenshots only in this chat. Docs-only changes can skip proof.

Proof of work on the PR

Cursor chat attachments are not enough. Reviewers look at GitHub, so post the screenshot, short video, or before/after on the GitHub PR.

After you have walkthrough artifacts:

1. Embed them in the PR body when you create or update the PR.
2. Repeat them in the last GitHub PR comment (same comment as "what to doubt"), but only when that comment will be attributed to Cursor.

Use HTML tags and absolute local paths. Do not commit artifacts to the repo. Claude Code and other tools that comment as the user still embed proof in the PR body; they skip only the last comment.

<img src="/opt/cursor/artifacts/cost_cell_dash.png" alt="Cost cell shows a dash" />
<video src="/opt/cursor/artifacts/cost_cell_dash.mp4" controls></video>

The PR tool uploads those paths and rewrites them to public URLs. Use width-only HTML if you need sizing; do not set a fixed height. Skip this for docs-only or non-visual changes.

What to doubt

Cursor only. Post this GitHub comment only when it will be attributed to Cursor, not to a human author. Claude Code and other tools that comment as the authenticated user must skip this section.

When the PR is ready for a human, post one last GitHub PR comment (not a changelog). Lead with proof when the change is user-visible, then name the risky or curious parts:

Proof of work
<img src="/opt/cursor/artifacts/cost_cell_dash.png" alt="Cost cell shows a dash" />

What to doubt in review
- I reused the existing cache key; check it cannot collide across projects.
- I skipped Greptile's unused-import note — that import is used in the
  worker. Tell me if that's wrong.

Two to five bullets. Include any bot findings you skipped. Trigger skepticism. Skip praise, file lists, and "LGTM".

Human asks

Prefer one or two actions per message. That cap is preferred, not hard. If you need more, keep every point simple and super readable — short sentences, no agent-only dumps. Sequence when you can.

Wrong: a wall of logs plus five mixed asks.
Right: a short TL;DR and one or two clear next steps. Extra steps can wait, or sit as equally simple bullets if they must ship together.