cursorrules "v5"

November 18, 2025 Β· View on GitHub

πŸ‡¬πŸ‡§ English Documentation

🌏 Back to Top | πŸ‡―πŸ‡΅ ζ—₯本θͺž

This repository manages custom instructions for Cursor.

Premise

  • This v5 is a set of custom instructions optimized for the Cursor Agent.
  • For the Cursor Agent to operate autonomously (without human intervention), Auto-Run must be configured appropriately.
  • See the changelog for the latest updates.

Overview

  • After the release of Cursor's agent features, I noticed a recurring issue: insufficient analytical rigor. I began crafting custom instructions to better draw out the model's inherent analytical ability (originally Claude 3.5 Sonnet at the time).

  • The early themes were improving analytical capability and autonomous execution. Later iterations also targeted preventing duplicate module/resource generation, unintended design changes by the AI, and infinite loops in error handling. These efforts, combined with model refreshes and performance gains, have produced reasonable results.

  • The focus of this version upgrade is GPT-5.1 optimization:

    1. We create a checklist-style execution plan first, then verify completion item-by-item for a more disciplined process.
    2. Tasks are classified into Lightweight, Standard, and Critical levels, with simplified reporting for lightweight tasks and more thorough processes for heavier ones.
    3. Independent tasks are executed in parallel to improve throughput.

  • In addition, this version codifies detailed tooling policies (e.g., always read files before editing, rely on apply_patch for modifications, and run terminal commands only when necessary with safe flags) so the Cursor Agent executes tasks with consistent safeguards.

  • v5 was initially created with Anthropic Prompt Generator and has since gone through cycles of evaluation by contemporary models and practical improvements. When customizing, we recommend having your chosen AI evaluate it as well.

  • For detailed updates, including task classification, error handling tiers, and tooling policies, see CHANGELOG.md.

  • This repository itself also serves as a best-practice example, providing rule files for commit/PR messages and workflow command templates for commit, push, and PR creation.

Usage

  1. If .cursor/rules does not exist yet, create the folder.
  2. If the path exists, copy the language you preferβ€”en/.cursor/rules/v5.mdc (English) or ja/.cursor/rules/v5.mdc (Japanese)β€”into that folder (typically as v5.mdc).
  3. To enable the test strategy rules, copy ja/.cursor/rules/test-strategy.mdc (Japanese) and/or en/.cursor/rules/test-strategy.mdc (English) into the same .cursor/rules folder.
  4. To enable the commit message format rules, copy ja/.cursor/rules/commit-message-format.mdc (Japanese) and/or en/.cursor/rules/commit-message-format.mdc (English) into the same folder.
  5. To enable the PR message format rules, copy ja/.cursor/rules/pr-message-format.mdc (Japanese) and/or en/.cursor/rules/pr-message-format.mdc (English) into the same folder.
  • Because their application condition is "always", they will be referenced in subsequent chats as long as they exist at the designated path.
  • Both Japanese and English versions are set to alwaysApply: true, so you may want to adjust this setting based on your preferred language and whether you want the test rules enabled by default.

For the division of responsibilities and usage patterns between rule files (.cursor/rules/*.mdc) and workflow commands (.cursor/commands/*.md), see doc/rules-and-workflows.md.

  • ja/.cursor/rules/commit-message-format.mdc / en/.cursor/rules/commit-message-format.mdc

    • Role: Defines the commit message format (prefix, summary, bullet-list body) and prohibited patterns.
    • Characteristics: Based on Conventional Commits, with additional guidelines such as language-based language selection and diff-based message generation tailored for this repository.

  • ja/.cursor/rules/pr-message-format.mdc / en/.cursor/rules/pr-message-format.mdc

    • Role: Defines the format for PR titles and bodies (prefix-style titles and structured sections such as Overview, Changes, Tests) and prohibited patterns.
    • Characteristics: Aligns PR messages with the commit message conventions and encourages structured descriptions that facilitate review and understanding of change intent.

  • ja/.cursor/rules/test-strategy.mdc / en/.cursor/rules/test-strategy.mdc

    • Role: Defines test strategy rules for test implementation and maintenance, including equivalence partitioning, boundary value analysis, and coverage requirements.
    • Purpose: Serves as a quality guardrail by requiring corresponding automated tests whenever meaningful changes are made to production code, where reasonably feasible.

  • ja/.cursor/rules/prompt-injection-guard.mdc / en/.cursor/rules/prompt-injection-guard.mdc

    • Role: Defines defense rules against context injection attacks from external sources (RAG, web, files, API responses, etc.).
    • Contents: Describes guardrails such as restrictions on executing commands originating from external data, the Instruction Quarantine mechanism, the SECURITY_ALERT format, and detection of user impersonation attempts.
    • Characteristics: Does not restrict the user's own direct instructions; only malicious commands injected via external sources are neutralized.
    • Note: This file has alwaysApply: true set in its metadata, but users can still control when these rules are applied via Cursor's UI settings (Always Apply / Apply Intelligently / Apply Manually). See the operational guide for details on handling false positives.

  • doc/custom_instruction_plan_prompt_injection.md

    • Role: Design and threat analysis document for external context injection defense.
    • Contents: Organizes attack categories (A-01–A-09) via external sources, corresponding defense requirements (R-01–R-08), design principles for the external data control layer, and validation/operations planning.
    • Update: Fully revised in November 2024 to focus on external-source attacks.

Translation Guide

For the recommended prompt to translate custom instructions into other languages, see TRANSLATION_GUIDE.md.

Notes

  • If there are instructions in User Rules or Memories that conflict with v5, the model may become confused and effectiveness may decrease. Please check the contents carefully.

License

Released under the MIT License. See LICENSE for details.

Support

  • There is no official support for this repository, but feedback is welcome. I also share Cursor-related information on X (Twitter). Follow on X (Twitter)