agentleFS
Sign inStart free
MovGP0MovGP0/Skills/m03-mutability/SKILL.md

m03-mutability

Skill1 starsChanged 4 months agoMITView on GitHub

CRITICAL: Use for mutability issues. Triggers: E0596, E0499, E0502, cannot borrow as mutable, already borrowed as immutable, mut, &mut, interior mutability, Cell, RefCell, Mutex, RwLock, 可变性, 内部可变性, 借用冲突

We split this skill into the rules it gives an agent

2 rules. About 0 are common, 2 are distinctive, and 0 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈2

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Before adding interior mutability, understand:

    line 15
  2. Distinctive:

    When mutability conflicts persist:

    line 54

≈ “Common” is an estimate: at least 1 in 5 of the 308,232 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Mutability

Layer 1: Language Mechanics

Core Question

Why does this data need to change, and who can change it?

Before adding interior mutability, understand:

  • Is mutation essential or accidental complexity?
  • Who should control mutation?
  • Is the mutation pattern safe?

Error → Design Question

ErrorDon't Just SayAsk Instead
E0596"Add mut"Should this really be mutable?
E0499"Split borrows"Is the data structure right?
E0502"Separate scopes"Why do we need both borrows?
RefCell panic"Use try_borrow"Is runtime check appropriate?

Thinking Prompt

Before adding mutability:

  1. Is mutation necessary?
    • Maybe transform → return new value
    • Maybe builder → construct immutably
  2. Who controls mutation?
    • External caller → &mut T
    • Internal logic → interior mutability
    • Concurrent access → synchronized mutability
  3. What's the thread context?
    • Single-thread → Cell/RefCell
    • Multi-thread → Mutex/RwLock/Atomic

Trace Up ↑

When mutability conflicts persist:

E0499/E0502 (borrow conflicts)
    ↑ Ask: Is the data structure designed correctly?
    ↑ Check: m09-domain (should data be split?)
    ↑ Check: m07-concurrency (is async involved?)
Persistent ErrorTrace ToQuestion
Repeated borrow conflictsm09-domainShould data be restructured?
RefCell in asyncm07-concurrencyIs Send/Sync needed?
Mutex deadlocksm07-concurrencyIs the lock design right?

Trace Down ↓

From design to implementation:

"Need mutable access from &self"
    ↓ T: Copy → Cell<T>
    ↓ T: !Copy → RefCell<T>

"Need thread-safe mutation"
    ↓ Simple counters → AtomicXxx
    ↓ Complex data → Mutex<T> or RwLock<T>

"Need shared mutable state"
    ↓ Single-thread: Rc<RefCell<T>>
    ↓ Multi-thread: Arc<Mutex<T>>

Borrow Rules

At any time, you can have EITHER:
├─ Multiple &T (immutable borrows)
└─ OR one &mut T (mutable borrow)

Never both simultaneously.

Quick Reference

PatternThread-SafeRuntime CostUse When
&mut TN/AZeroExclusive mutable access
Cell<T>NoZeroCopy types, no refs needed
RefCell<T>NoRuntime checkNon-Copy, need runtime borrow
Mutex<T>YesLock contentionThread-safe mutation
RwLock<T>YesLock contentionMany readers, few writers
Atomic*YesMinimalSimple types (bool, usize)

Error Code Reference

ErrorCauseQuick Fix
E0596Borrowing immutable as mutableAdd mut or redesign
E0499Multiple mutable borrowsRestructure code flow
E0502&mut while & existsSeparate borrow scopes

Interior Mutability Decision

ScenarioChoose
T: Copy, single-threadCell<T>
T: !Copy, single-threadRefCell<T>
T: Copy, multi-threadAtomicXxx
T: !Copy, multi-threadMutex<T> or RwLock<T>
Read-heavy, multi-threadRwLock<T>
Simple flags/countersAtomicBool, AtomicUsize

Anti-Patterns

Anti-PatternWhy BadBetter
RefCell everywhereRuntime panicsClear ownership design
Mutex for single-threadUnnecessary overheadRefCell
Ignore RefCell panicHard to debugHandle or restructure
Lock inside hot loopPerformance killerBatch operations

Related Skills

WhenSee
Smart pointer choicem02-resource
Thread safetym07-concurrency
Data structure designm09-domain
Anti-patternsm15-anti-pattern

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

Reviews can't be read right now.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free