Cursor Rules

cursor.md

Installing dependencies

When you run into any issues with dependencies, prefer using the ecosystem's package management to install them. For projects in Node.js, Python, Rust, etc., if you run into any issues with missing dependencies, prefer using the ecosystem's "install all dependencies" command (e.g. npm install instead of npm install <specific dependency>), especially if it seems like there are multiple missing dependencies. Don't forget to read the other rules FIRST to see if there are hints on how to install dependencies. This prevents a cycle where you run into missing dependencies and install them, then run into missing dependencies, then install them again.

Use discretion when adding new dependencies

Especially in Go projects: evaluate whether or not dependencies are needed. For example, if there's a dependency that only adds less than 500 lines of code (e.g. a very simple parsing library), prefer to create it from scratch or copy the code from the dependency and paste it into the project, ensure that the license is preserved.

"Make <command> work" when working in repos that provide <command>

If you're working in a repository that builds a binary or a script, and I tell you to make it "work". e.g. in a repo that builds the mygoserver binary, and you're instructed with, "Make mygoserver run --flag value --foo bar work", then take it as a hint to build the local binary first instead of just invoking the command already in the shell's $PATH. For example, if I'm working in a repo called poppy, which builds the poppy CLI, I would already have a version of poppy installed in my $PATH. Don't use that – use the poppy binary that is built by the repo. Check the repo and other rules for how to build it, and be discerning on where the binary lives, e.g. in this case it could live in ./bin/poppy after running make.

LOOK FOR REPOSITORY CONVENTIONS WHEN RUNNING "COMMON" TASKS:

For development tasks such as lint, build, deploy, build containers, etc. For tasks such as these, read Makefiles, package.json, .sh files, scripts/ and if they're meant for local/development consumption, then run the commands from there directly first before writing the command from scratch. Two examples:

1. run make build-proto over invoking protoc directly
2. run npm run lint over invoking eslint directly

At the very least, use these as hints on how tools are supposed to be invoked. Use other files at the root of the repo that may also be used for information and additional context on development tasks and setup.

USE IGNORED FILES FOR INFORMATION

Add .gitignored files to your context and indexing unless they're obviously a folder for vendored dependencies, e.g. node_modules.

ALWAYS SHOW THOUGHTS (this doesn't work)

Cursor always, by default, collapses "Thoughts" under a caret character and I have to go and expand it manually. Either keep the "Thoughts" steps expanded so I can read through your reasoning in our chats, and copy and paste each "Thought" in the output in the beginning of a response.

USE MY PR-DESCRIPTION STYLE WHEN WRITING COMMIT MESSAGES

Use my style of writing commit messages, ideally from the "master" or main branch as they are generated from the PR description and are therefore better written. Whenever you're told to write code or a commit message or commit, read through the git history to filter for my name's commits. This is the style of language you should use in the commit message. If you have a memory system, commit the style and examples into memory so you don't have to run git every time.

ALWAYS LINT

Before creating any commits and after any changes, always remind the user to run lint before they commit. Auto-run lint to double check at the end of runs where you modify files. Use the other rules and the repository to discern how to run lint for the repo.

RUN THINGS IN FOREGROUND

Always run processes in the foreground and always re-use the same shell session unless you need to run multiple processes.

TRIPLE DOT SYNTAX, GIT SHOW, AND USING GIT DIFF (a preference)

When I ask you to compare two branches or git refs, you should compare the textual differences of the state of the working directories as if they were checked out at that commit. It may be helpful to examine the triple dot diff if I ask for the difference between two commits or two branches, i.e. use git diff <ref1>...<ref2> or use git show per file. Remind the user that this is the methodology you're using.

NEVER MODIFY OR REMOVE GITIGNORED FILES EVEN IF NOT RUNNING IN READONLY MODE.

NEVER run commands that will overwrite any git ignored file. For example, if the directory gen/ is git ignored, and there is a make build-proto command that compiles protobufs into gen/, do not run it. Instead, first create a backup of the files about to be overwritten, then stop execution and prompt the user for confirmation before making any modificiations.

CITE RULES

When taking or suggesting an action that needs to respect a rule, cite the rule and source.

USE trash on macOS

On macOS, use trash instead of rm when removing or deleting files. Do not take this rule as permission to delete files. Always respect other rules when it comes to modifying or removing files.

When I ask you to "Analyze tests"

Analyze test files and check for:

1. Stubs that can now be implemented (perhaps due to recent changes)
2. Tests marked as expected to fail that can now be implemented (perhaps due to recent changes)
3. Tests that are missing that can now be implemented (perhaps due to recent changes)
4. Any other suggesetions around testing that you think is important.

Err STRONGLY towards not modifying source code and only updating tests. If a test implies there is implementation logic missing, instead of guessing implementation or stubbing implementation in the source code in a way that hides missing logic, do this instead: clearly and very obviously add a WARNING log to the test and to the source (if you must edit the source). Mark the test as either a stub or an expected to fail. When we write tests, we NEVER want to hide missing or broken logic in a passing test. Always make it a failing test: mark it as expected failures or stub, add warning logs.

Prefer other tools use find

Don't use find unless rg (ripgrep) or ag (thesilversearcher) is not installed.

old_rules.md

READONLY BY DEFAULT (borrowed from elsewhere)

By default, all chats should be start with "Readonly State" as active. In this state:

1. You must NOT modify files, create new files, or use edit_file/any file modification tools.
2. You MUST prefix your responses with [READONLY STATE]\n as a visual indicator
3. You may analyze code, suggest changes (in chat only), discuss strategy, and help with planning
4. You will only exit this state when I explicitly say "EXIT READONLY" or clearly request you to make specific file changes and you will ask for confirmation on whether or not to turly exit this state.
5. You must NOT run any git commands that mutate the git workspace, worktree, config or settings. You may use git commands that are read-only, e.g. read the log, the commits, history.

Readonly State is designed for thoughtful discussion and planning before implementation.

You may exit ReadOnly state if I explicitly say "Exit RO" or "Exit ReadOnly" or start a chat saying "Exit ReadOnly".

Keep recent git history in context always

In the beginning of a new chat, run and understand the most recent 3 git commits and merge your understanding of them with other context clues.