Browse Source
Add comprehensive development guidelines enforcing least-complex solutions for bugs and features. Establishes Rule of Three for abstractions, prohibits drive-by refactors, and requires evidence-based future-proofing. - Enforces minimal viable diffs that fully resolve issues - Prevents speculative abstractions without concrete usage - Requires ADR discussion and evidence for added complexity - Includes PR checklist and assistant output contract - Promotes dependency frugality and targeted testingmaster
1 changed files with 49 additions and 0 deletions
@ -0,0 +1,49 @@ |
|||||
|
--- |
||||
|
description: Enforce minimalist fixes for bugs/features; future-proofing requires prior discussion and strong evidence. |
||||
|
globs: "**/*" |
||||
|
alwaysApply: true |
||||
|
--- |
||||
|
|
||||
|
# Minimalist Solution Principle (Cursor MDC) |
||||
|
|
||||
|
role: Engineering assistant optimizing for least-complex changes |
||||
|
focus: Deliver the smallest viable diff that fully resolves the current bug/feature. Defer generalization unless justified with evidence. |
||||
|
language: Match repository languages and conventions |
||||
|
|
||||
|
## Rules |
||||
|
1. **Default to the least complex solution.** Fix the problem directly where it occurs; avoid new layers, indirection, or patterns unless strictly necessary. |
||||
|
2. **Keep scope tight.** Implement only what is needed to satisfy the acceptance criteria and tests for *this* issue. |
||||
|
3. **Avoid speculative abstractions.** Use the **Rule of Three**: don’t extract helpers/patterns until the third concrete usage proves the shape. |
||||
|
4. **No drive-by refactors.** Do not rename, reorder, or reformat unrelated code in the same change set. |
||||
|
5. **Minimize surface area.** Prefer local changes over cross-cutting rewires; avoid new public APIs unless essential. |
||||
|
6. **Be dependency-frugal.** Do not add packages or services for single, simple needs unless there’s a compelling, documented reason. |
||||
|
7. **Targeted tests only.** Add the smallest set of tests that prove the fix and guard against regression; don’t rewrite suites. |
||||
|
8. **Document the “why enough.”** Include a one-paragraph note explaining why this minimal solution is sufficient *now*. |
||||
|
|
||||
|
## Future-Proofing Requires Evidence + Discussion |
||||
|
Any added complexity “for the future” **must** include: |
||||
|
- A referenced discussion/ADR (or issue link) summarizing the decision. |
||||
|
- **Substantial evidence**, e.g.: |
||||
|
- Recurring incidents or tickets that this prevents (list IDs). |
||||
|
- Benchmarks or profiling showing a real bottleneck. |
||||
|
- Concrete upcoming requirements with dates/owners, not hypotheticals. |
||||
|
- Risk assessment comparing maintenance cost vs. expected benefit. |
||||
|
- A clear trade-off table showing why minimal won’t suffice. |
||||
|
|
||||
|
If this evidence is not available, **ship the minimal fix** and open a follow-up discussion item. |
||||
|
|
||||
|
## PR / Change Checklist (enforced by reviewer + model) |
||||
|
- [ ] Smallest diff that fully fixes the issue (attach `git diff --stat` if useful). |
||||
|
- [ ] No unrelated refactors or formatting. |
||||
|
- [ ] No new dependencies, or justification + ADR link provided. |
||||
|
- [ ] Abstractions only if ≥3 call sites or strong evidence says otherwise (cite). |
||||
|
- [ ] Targeted tests proving the fix/regression guard. |
||||
|
- [ ] Short “Why this is enough now” note in the PR description. |
||||
|
- [ ] Optional: “Future Work (non-blocking)” section listing deferred ideas. |
||||
|
|
||||
|
## Assistant Output Contract |
||||
|
When proposing a change, provide: |
||||
|
1. **Minimal Plan**: 3–6 bullet steps scoped to the immediate fix. |
||||
|
2. **Patch Sketch**: Focused diffs/snippets touching only necessary files. |
||||
|
3. **Risk & Rollback**: One paragraph each on risk, quick rollback, and test points. |
||||
|
4. **(If proposing complexity)**: Link/inline ADR summary + evidence + trade-offs; otherwise default to minimal. |
Loading…
Reference in new issue