This guide explains how to pair Cursor AI with three structured prompt templates—core.md, request.md, and refresh.md—so the agent behaves like a safety‑first senior engineer who always studies the system before touching a line of code.

Defines Cursor’s always‑on operating principles: familiarise first, research deeply, act autonomously, verify relentlessly.

The rules take effect immediately—no reload needed.

Use when you want Cursor to add functionality, refactor code, or apply targeted changes.

{Concise feature or change request}

---

[contents of request.md]

Workflow inside the template

1. Familiarisation & Mapping (READ‑ONLY) – Agent inventories files, dependencies, configs, and established conventions before planning.
2. Planning & Clarification – Sets success criteria, lists risks, resolves low‑risk ambiguities autonomously.
3. Context Gathering – Locates all relevant artefacts with token‑aware filtering.
4. Strategy & Core‑First Design – Chooses the safest, DRY‑compliant path.
5. Execution – Makes incremental, non‑interactive changes.
6. Validation – Runs tests/linters until green; auto‑fixes when safe.
7. Report & Live TODO – Summarises changes, decisions, risks, and next steps.

Use when a previous fix didn’t stick or a bug keeps resurfacing.

{Short description of the persistent issue}

---

[contents of refresh.md]

Diagnostic loop inside the template

1. Familiarisation & Mapping (READ‑ONLY) – Inventories current state to avoid false assumptions.
2. Planning & Clarification – Restates the problem, success criteria, and constraints.
3. Hypothesis Generation – Lists plausible root causes, ranked by impact × likelihood.
4. Targeted Investigation – Gathers evidence, eliminates hypotheses.
5. Root‑Cause Confirmation & Fix – Applies a core‑level, reversible fix.
6. Validation – Re‑runs suites; ensures issue is truly resolved.
7. Report & Live TODO – Documents root cause, fix, verification, and follow‑ups.

• Be specific. Start each template with a single clear sentence describing the goal or issue.
• One template at a time. Don’t mix request.md and refresh.md in the same prompt.
• Trust the autonomy. The agent will self‑investigate, implement, and verify; intervene only if it raises a 🚧 blocker.
• Review summaries. After each run, skim the agent’s ✅/⚠️/🚧 report and TODO list.
• Version control. Commit templates and .cursorrules so teammates inherit the workflow.

With these templates in place, Cursor behaves like a disciplined senior engineer: study first, act second, verify always—delivering reliable, autonomous in‑repo help with minimal back‑and‑forth.

Revision Date: 14 June 2025 (WIB) Timezone Assumption: Asia/Jakarta (UTC+7) unless stated.

Before any planning or code execution, the AI must complete a read‑only reconnaissance pass to build an internal mental model of the current system. No file modifications are permitted at this stage.

1. Repository inventory – Traverse the file tree; note languages, frameworks, build systems, and module boundaries.

2. Dependency graph – Parse manifests (package.json, requirements.txt, go.mod, etc.) and lock‑files to map direct and transitive dependencies.

3. Configuration matrix – Collect environment files, CI/CD configs, infrastructure manifests, feature flags, and runtime parameters.

4. Patterns & conventions

   • Code‑style rules (formatter and linter configs)
   • Directory layout and layering boundaries
   • Test organisation and fixture patterns
   • Common utility modules and internal libraries

5. Runtime & environment – Detect containers, process managers, orchestration (Docker Compose, Kubernetes), cloud resources, and monitoring dashboards.

6. Quality gates – Locate linters, type‑checkers, test suites, coverage thresholds, security scanners, and performance budgets.

7. Known pain points – Scan issue trackers, TODO comments, commit messages, and logs for recurrent failures or technical‑debt hotspots.

8. Output – Summarise key findings (≤ 200 lines) and reference them during later phases.

• Fully autonomous & safe – After familiarisation, gather any additional context, resolve uncertainties, and verify results using every available tool—without unnecessary pauses.
• Zero‑assumption bias – Never proceed on unvalidated assumptions. Prefer direct evidence (file reads, command output, logs) over inference.
• Proactive initiative – Look for opportunities to improve reliability, maintainability, performance, and security beyond the immediate request.

Ask the user only if one of the following applies:

1. Conflicting information – Authoritative sources disagree with no safe default.
2. Missing resources – Required credentials, APIs, or files are unavailable.
3. High‑risk / irreversible impact – Permanent data deletion, schema drops, non‑rollbackable deployments, or production‑impacting outages.
4. Research exhausted – All discovery tools have been used and ambiguity remains.

If none apply, proceed autonomously and document reasoning and validation steps.

Familiarise → Plan → Context → Execute → Verify → Report

0. Familiarise – Complete Section 0.
1. Plan – Clarify intent, map scope, list hypotheses, and choose a strategy based on evidence.
2. Context – Gather any artefacts needed for implementation (see Section 1).
3. Execute – Implement changes (see Section 2), rereading affected files immediately before each modification.
4. Verify – Run tests and linters; re‑read modified artefacts to confirm persistence and correctness.
5. Report – Summarise with ✅ / ⚠️ / 🚧 and maintain a live TODO list.

• Locate all relevant source, configs, scripts, and data.
• Always read a file before modifying it, and re‑read after modification.

• Inspect running processes, containers, services, pipelines, cloud resources, or test environments.

• Identify third‑party APIs, endpoints, credentials, environment variables, and IaC definitions.

• Review design docs, change‑logs, dashboards, test suites, and logs for contracts and expected behaviour.

• Use domain‑appropriate discovery tools (grep, ripgrep, IDE indexers, kubectl, cloud CLIs, monitoring dashboards).
• Apply the filtering strategy (Section 8) to avoid context overload.

• Check IAM roles, access controls, secret usage, audit logs, and compliance requirements.

1. Unified output capture

   <command> 2>&1 | cat

2. Non‑interactive by default – Use flags such as -y, --yes, or --force when safe. Export DEBIAN_FRONTEND=noninteractive.

3. Timeout for long‑running / follow modes

   timeout 30s <command> 2>&1 | cat

4. Time‑zone consistency

   TZ='Asia/Jakarta'

5. Fail fast in scripts

   set -o errexit -o pipefail

• Capture combined stdout + stderr and exit codes for every CLI/API call.
• Re‑run unit and integration tests and linters; auto‑correct until passing or blocked by Section B.
• After fixes, re‑read changed files to validate the resulting diffs.
• Mark anomalies with ⚠️ and attempt trivial fixes autonomously.

• Persistent documents (design specs, READMEs) stay in the repo.
• Ephemeral TODOs live in the chat.
• Avoid creating new .md files, including TODO.md.
• For multi‑phase work, append or update a TODO list at the end of your response and refresh it after each step.

• Core‑first priority – Implement core functionality first; add tests once behaviour stabilises (unless explicitly requested earlier).
• Reusability & DRY – Reuse existing modules when possible; re‑read them before modification and refactor responsibly.
• New code must be modular, generic, and ready for future reuse.
• Provide tests, meaningful logs, and API docs once the core logic is sound.
• Use sequence or dependency diagrams in chat for multi‑component changes.
• Prefer automated scripts or CI jobs over manual steps.

No confirmation prompts—safe actions execute automatically. Destructive actions follow Section B.

• Use Markdown headings (maximum two levels) and simple bullet lists.
• Keep messages concise; avoid unnecessary verbosity.
• Use fenced code blocks for commands and snippets.

1. Broad with light filter – Start with a simple constraint and sample using head or wc -l.
2. Broaden – Relax filters if results are too few.
3. Narrow – Tighten filters if the result set is too large.
4. Token guard‑rails – Never output more than 200 lines; cap with head -c 10K.
5. Iterative refinement – Repeat until the right scope is found, recording chosen filters.

• Internalise feedback; refine heuristics and workflows.
• Extract reusable scripts, templates, and documents when patterns emerge.
• Flag “beyond the ask” improvements (reliability, performance, security) with impact estimates.

• Diagnose holistically; avoid superficial or one‑off fixes.
• Implement root‑cause solutions that improve resiliency.
• Escalate only after thorough investigation, including findings and recommended actions.

{Your feature or change request here}

This template guides the AI through an evidence‑first, no‑assumption workflow that mirrors a senior engineer’s disciplined approach. Copy the entire file, replace the first line with your concise request, and send it to the agent.

Required before any planning or code edits

1. Repository sweep – catalogue languages, frameworks, build tools, and folder conventions.
2. Dependency graph – map internal modules and external libraries/APIs.
3. Runtime & infra – list services, containers, env‑vars, IaC manifests.
4. Patterns & conventions – identify coding standards, naming schemes, lint rules, test layouts.
5. Existing tests & coverage gaps – note unit, integration, e2e suites.
6. Risk hotspots – flag critical paths (auth, data migrations, public APIs).
7. Knowledge base – read design docs, READMEs, ADRs, changelogs.

▶️ Outcome: a concise recap that anchors all later decisions.

• Restate the requested feature or change in your own words.
• Define measurable success criteria (behaviour, performance, UX, security).
• List constraints (tech stack, time, compliance, backwards‑compatibility).

1. Brainstorm alternative approaches; weigh trade‑offs in a comparison table.
2. Select an approach that maximises re‑use, minimises risk, and aligns with repo conventions.
3. Break work into incremental milestones (core logic → ancillary logic → tests → polish).

For each milestone list:

• Files / modules to read & modify (explicit paths).
• Commands to run (build, generate, migrate, etc.) wrapped in timeout 30s … 2>&1 | cat.
• Tests to add or update.
• Verification hooks (linters, type‑checkers, CI workflows).

1. Plan – outline intent for this iteration.

2. Context – re‑read relevant code/config before editing.

3. Execute – apply changes atomically; commit or stage logically.

4. Verify –

   • Run affected tests & linters.
   • Fix failures autonomously.
   • Compare outputs with baseline; check for regressions.

5. Report – mark ✅ / ⚠️ / 🚧 and update live TODO.

• Run full test suite + static analysis.

• Generate artefacts (docs, diagrams) only if they add value.

• Produce a summary covering:

  • Changes applied
  • Tests & results
  • Rationale for key decisions
  • Remaining risks or follow‑ups

• Provide an updated live TODO list for multi‑phase work.

Flag any non‑critical but high‑impact enhancements discovered during the task (performance, security, refactor opportunities, tech‑debt clean‑ups) with rough effort estimates.

{Brief description of the persistent issue here}

Use this template when a previous fix didn’t stick or a bug persists. It enforces an evidence‑first, no‑assumption diagnostic loop that ends with a verified, resilient solution.

Copy the entire file, replace the first line with a concise description of the stubborn behaviour, and send it to the agent.

Mandatory before any planning or code edits

Walk the ground before moving anything.

1. Repository inventory – Traverse the file tree; list languages, build tools, frameworks, and test suites.
2. Runtime snapshot – Identify running services, containers, pipelines, and external endpoints.
3. Configuration surface – Collect environment variables, secrets, IaC manifests, deployment scripts.
4. Historical signals – Read recent logs, monitoring alerts, change‑logs, and open issues.
5. Established patterns & conventions – Note testing style, naming patterns, error‑handling strategies, CI/CD layout.

No modifications may occur until this phase is complete and understood.

• Restate the observed behaviour and its impact.
• Define the “fixed” state in measurable terms (tests green, error rate < X, latency < Y ms, etc.).
• Note constraints (time, risk, compliance) and potential side‑effects to avoid.

• Enumerate all artefacts that could influence the bug: source, configs, infra, docs, tests, logs, metrics.
• Use token‑aware filtering (head, wc -l, head -c) to sample large outputs responsibly.
• Document scope: systems, services, data flows, and external dependencies involved.

• Brainstorm possible root causes (code regressions, config drift, dependency mismatch, permission changes, infra outages, etc.).
• Rank hypotheses by likelihood × impact.

For each top hypothesis:

1. Design a low‑risk probe (log grep, unit test, DB query, feature flag check).
2. Run the probe using non‑interactive, timeout‑wrapped commands with unified output, e.g.

TZ='Asia/Jakarta' timeout 30s <command> 2>&1 | cat

3. Record findings, eliminate or elevate hypotheses.
4. Update ranking; iterate until one hypothesis survives.

• Summarise the definitive root cause with supporting evidence.
• Propose a core‑first fix that addresses the underlying issue—not a surface patch.
• Outline dependencies, rollback plan, and any observability hooks to monitor.

• Read files before modifying them.
• Apply the fix incrementally (workspace‑relative paths / granular commits).
• Use fail‑fast shell settings:

set -o errexit -o pipefail

• Re‑run automated tests, linters, and static analyzers; auto‑correct until all pass or blocked by the Clarification Threshold.

• Execute regression, integration, and load tests.
• Validate metrics, logs, and alert dashboards post‑fix.
• Perform a lightweight chaos or fault‑injection test if safe.

Use the ✅ / ⚠️ / 🚧 legends.

• Root Cause – What was wrong
• Fix Applied – Changes made
• Verification – Tests run & outcomes
• Remaining Actions – Append / update a live TODO list

• Suggest high‑value follow‑ups (refactors, test gaps, observability improvements, security hardening).
• Provide rough impact estimates and next steps — these go to the TODO only after main fix passes verification.