Jan's Cursor Rules

v0.2.3

A curated set of rules and skills for Cursor and Claude Code that shape AI assistant behavior toward careful, minimal, high-quality code.

What's in here

Rules (.mdc files)

File	Purpose
cursor-assistant.mdc	Core behavioral guidelines — thinking before coding, simplicity, surgical changes, goal-driven execution
safety.mdc	Guards against destructive filesystem and git operations; package-manager detection before installs
python.mdc	Python-specific conventions and tooling standards
memory-bank.mdc	Memory-bank documentation pattern for session continuity — optional, see §Installation for details

Skills (skills/ directory)

Skill	Purpose
skills/grill-me/	Relentless iterative interview that stress-tests a plan before any code is written — an explicit, structured version of "challenge me"
skills/code-audit/	Thorough code audit from a senior engineer perspective covering correctness, architecture, performance, security, simplicity, and configurability — produces a prioritized issue report and implementation plan
skills/extended-plan/	Audit-proof development planning in Cursor's native .plan.md format — explores the codebase read-only, decomposes the task into steps, and stress-tests each step against all code-audit dimensions before any code is written
skills/install-jans-rules/	Installs all rules and skills from this repo into Cursor and/or Claude Code globally on the current machine — handles OS/path detection, memory-bank opt-in, and verification

Adapted in part from mattpocock/skills, especially the grilling workflow. Recent additions draw on DietrichGebert/ponytail for skill structure and composition patterns, and shahshrey's Claude Code system prompt gist for behavioral and communication guidelines.

Philosophy

The two rules I care about most are:

1. Fix things at the cause, not the symptom.
2. Challenge me. Evaluate my suggestions from all angles and push back when warranted.

The remaining guidelines (simplicity first, surgical changes, goal-driven execution) are heavily influenced by Andrej Karpathy's observations on LLM coding pitfalls, as packaged in forrestchang/andrej-karpathy-skills and complemented by some of namakshenas's 12 rules.

Installation

First, clone this repo:

# SSH
git clone git@github.com:jlbgit/JansCursorRules.git
# HTTPS
git clone https://github.com/jlbgit/JansCursorRules.git

cd JansCursorRules

Then pick one of the two install paths below.

Option A — Command-line script (quickest, no AI needed)

A self-contained installer that copies the rules and skills into both Cursor and Claude Code globally. No AI tool needs to be running.

# macOS / Linux
./install.sh install

# Windows (PowerShell)
.\install.ps1 install

Note: install.sh is tested on macOS/Linux. install.ps1 mirrors the same logic but has not been tested on Windows yet — use with care and verify the results.

Uninstall removes exactly what it installed — Cursor's rule files and skill dirs, Claude's python.md + skill dirs, and the delimited JANS-RULES block in CLAUDE.md (your other CLAUDE.md content is left untouched):

./install.sh uninstall          # .\install.ps1 uninstall on Windows

Options (same on both scripts; PowerShell uses -Flag form):

Flag	Effect
--cursor-only / --claude-only	Install/uninstall just one tool (default: both)
--with-memory-bank	Also install the optional memory-bank rule (excluded by default)
--cursor-dir PATH	Override the Cursor config dir (default ~/.cursor)
--claude-dir PATH	Override the Claude config dir (default ~/.claude)

Re-running install is idempotent — it refreshes the rules/skills and replaces the CLAUDE.md block cleanly rather than duplicating it. The install-jans-rules skill itself is never installed. On Windows the scripts use %USERPROFILE%\.cursor and %USERPROFILE%\.claude.

Option B — Run the install skill (from inside Cursor or Claude)

Use this if you want the interactive flow with verification (diffs installed files against source and reports drift).

1. Bootstrap the install skill (one-time manual step)

The install skill needs to be in your AI tool's global skills directory before it can be invoked. Copy it there from inside the cloned repo:

# Cursor (macOS/Linux)
mkdir -p ~/.cursor/skills && cp -r skills/install-jans-rules ~/.cursor/skills/

# Claude Code (macOS/Linux)
mkdir -p ~/.claude/skills && cp -r skills/install-jans-rules ~/.claude/skills/

On Windows: replace ~/.cursor/ with %APPDATA%\Cursor\ and ~/.claude/ with %USERPROFILE%\.claude\.

2. Run the skill

In Cursor — open a chat and type:

/install-jans-rules

In Claude Code — start a session and say:

Use the install-jans-rules skill

The skill locates the repo by searching common paths (or asks if it can't find it), then:

• Detects your OS and config paths (asks if not found at the defaults)
• Installs the 3 core rules (cursor-assistant, python, safety) globally
• Asks whether to install memory-bank — explains what it does first
• Installs the 3 workflow skills (code-audit, extended-plan, grill-me) — the install skill itself is excluded
• For Claude Code, appends the always-on rules as a delimited JANS-RULES block to CLAUDE.md, and installs the path-scoped python rule as ~/.claude/rules/python.md

Re-running the skill switches to verify mode: diffs every installed file against the source and reports what's missing or outdated, without touching anything.

Manual installation

Copy files directly if you prefer:

• Rules: .mdc files from rules/ → ~/.cursor/rules/ (Cursor global) or .cursor/rules/ (project-scoped)
• Skills: directories from skills/ → ~/.cursor/skills/ (Cursor) or ~/.claude/skills/ (Claude Code)
• Claude Code rules: append the always-on rule bodies (cursor-assistant, safety) to ~/.claude/CLAUDE.md; install the path-scoped python rule as ~/.claude/rules/python.md with paths frontmatter

Using the skills

Invoke skills explicitly in chat:

Say...	Skill triggered
"grill me on this plan"	grill-me — one-question-at-a-time stress-test
"code audit" / "code review"	code-audit — P1/P2/P3 issue report + implementation plan
"extended plan" / "let's plan this"	extended-plan — audit-proof step-by-step plan in .plan.md
"install jans rules"	install-jans-rules — install or verify this repo's rules and skills

License & Disclaimer

MIT License — Disclaimer