Cursor Rules Pack

四份可直接复制的 Cursor `.mdc` 规则文件——常驻质量基线、设计工作标准、测试标准、按需调用的根因调试协议——并附 frontmatter 作用域说明。

规则 1 刻意写得很短，因为它每次请求都会加载。规则 2 通过 globs 挂到 UI 文件上，要求所有取值精确（十六进制色值并给出暗色变体、毫秒级动画时长、来自既定间距刻度的数值），且每个状态都要设计，而不只是默认态。规则 3 挂到测试文件上，要求你先说出「这个测试能抓住的错误实现长什么样」，说不出就别写。规则 4 设为手动触发的调试协议。附带的 frontmatter 表说明 `alwaysApply`、`globs` 与仅按描述加载三种模式，并提醒常驻规则写得越长，其中每条规则越弱。

# Cursor Rules

> **How to use this file:** Cursor reads rules from `.cursor/rules/*.mdc` files in your repo. Copy the sections below into one or more `.mdc` files. Each `.mdc` file starts with frontmatter that controls when it applies. Templates are at the bottom. Delete this note after copying.

---

## Rule 1: Always on quality standard

Keep this one short. It loads on every request, so every line here competes with your actual question.

```markdown
---
description: Quality standard for all work
alwaysApply: true
---

Your first working answer is a draft, not the deliverable. The bar is
that a staff engineer who owns this code finds nothing to change.

Before writing: read the surrounding code and match how this repo already
solves similar problems. State the requirement back in one sentence.

While writing: complete work only, no TODO or stub. Unhappy paths get the
same care as happy paths. Handle empty, null, zero, one, many, slow
network, no network, permission denied, and failure partway through.
Match existing style exactly. No magic values.

After writing: run the build and tests and paste the real output. Never
say tests pass without running them. Separate what you checked from what
you assumed.

Then review your own diff as a principal engineer looking for reasons to
reject it: correctness, edge cases, error paths, security, performance,
readability, consistency. Fix Blockers and Majors, then review again.
Stop after two clean rounds.

Reply with the answer first in one or two sentences, then only the
reasoning needed. No preamble, no process narration.
```

## Rule 2: Design work

```markdown
---
description: Standard for UI and design work
globs: ["**/*.tsx", "**/*.jsx", "**/*.swift", "**/*.css", "**/*.vue"]
---

Exact values only. Every spacing from a stated scale. Every colour in hex
with a dark mode variant and a stated contrast ratio. Every animation
with a duration in milliseconds and an easing curve. Every size in real
units. "Some padding" and "an appropriate value" are failures.

Design every state, not just the default: hover, pressed, focus visible,
disabled, loading, empty, error, success, long content, shortest content.
Empty and error states get real copy and a real next action.

Write the real words. No placeholder text. Buttons name the outcome.
Errors say what happened and what to do next.

Rank the elements by importance before styling anything. The design must
make that ranking obvious in one second.

Then review it: which values here are defaults rather than decisions?
Where is the spacing rhythm broken? Which state is missing? Fix those.
```

## Rule 3: Tests

```markdown
---
description: Test quality standard
globs: ["**/*.test.*", "**/*.spec.*", "**/tests/**"]
---

A test earns its place only if there is a plausible wrong version of the
code that it would catch. Name that wrong version before writing the
test. If you cannot, do not write it.

Cover in this order: the contract, boundaries and off by one, empty and
absent values, wrong shapes, failure paths, repeated and out of order
calls, concurrency.

One reason to fail per test. The name states the condition and the
expected result. Assert real values, not truthiness. No logic in tests.
Test through the public surface, not internals. Deterministic: no real
clock, no real network, no unseeded randomness, no order dependence.

For important tests, break the source code deliberately and show the test
failing, then restore it. A test you never watched fail is not known to
work.
```

## Rule 4: Debugging, on demand

Set this one to manual so you invoke it when you need it.

```markdown
---
description: Root cause debugging protocol
---

No fix until the cause is proven.

1. Separate observed facts from assumptions. Quote the actual error.
2. Reproduce it reliably. Show the failure.
3. Narrow by bisection. Show real output at each step, not expectations.
4. Write three hypotheses with a cheap test that would disprove each.
5. Prove one: make the bug appear on demand, and explain every symptom
   including the odd ones. An unexplained symptom means wrong cause.
6. Fix the cause, not the symptom. Then search for the same pattern
   elsewhere.
7. Add a test that fails on the old code. Show it failing and passing.

Banned: "try changing X and see", changing several things at once,
"this should fix it", a defensive check that hides the cause.
```

---

## Frontmatter reference

| Field | Effect |
| --- | --- |
| `alwaysApply: true` | Loaded on every request. Keep these short. |
| `globs: [...]` | Loaded when a matching file is in context. |
| `description: ...` only | Available for the agent to pull in when relevant. |

## Practical advice

- **Short beats complete.** Rules compete with your actual prompt for attention. A 500 line always on rule file makes every rule weaker.
- **One concern per file.** Easier to turn off, easier to see what is loaded.
- **Put project facts in their own rule.** Build command, test command, architecture, conventions. These are worth more than any generic standard.
- **Ban specifics, not vagueness.** "Never use `any`" works. "Write type safe code" does not.
- **Check what is loading.** If output ignores a rule, the rule is probably not in context, not badly written.

## Project rule template

```markdown
---
description: Project facts
alwaysApply: true
---

Stack: 
Build: 
Test: 
Lint and types: 

Architecture in three lines:

Conventions not obvious from the code:

Things that look wrong but are deliberate:

Do not touch:
```