Skip to content

CLAUDE.md

Latest commit

 

History

History
147 lines (94 loc) · 5.8 KB

CLAUDE.md

File metadata and controls

147 lines (94 loc) · 5.8 KB
Raw

SpriteKitScience — CLAUDE.md

A collection of physics demonstrations built with Apple's SpriteKit, recreating popular physics videos and experiments using SpriteKit's built-in physics engine. A learning project for SpriteKit physics (joints, bodies, gravity) and packaging multiple demos under one Xcode workspace.

Project Structure

ScienceDemos.xcworkspace ties the demos together. Each demo is its own Xcode project in its own folder. Currently in the workspace:

  • Rope/Rope.xcodeproj — a rope/pendulum-style demo (SpriteKit joints).
  • DoubleDomino/DoubleDomino.xcodeproj — a dominoes simulation.

Open the workspace, pick a scheme (Rope or DoubleDomino), and run. Build/ is Xcode's generated output (not source). The README lists further demos as planned (double pendulum, mass on an incline, dancing T-handle in zero gravity, two-body collision) — these are aspirational and not yet in the workspace.

Environment

  • IDE: Xcode
  • Language: Swift (SpriteKit)
  • Build system: Xcode workspace (ScienceDemos.xcworkspace) of per-demo projects
  • Key dependencies: macOS + Xcode; SpriteKit (system framework), no third-party libs

Building and Testing

open ScienceDemos.xcworkspace

Select a scheme (Rope or DoubleDomino) and press Cmd+R. From the command line:

xcodebuild -workspace ScienceDemos.xcworkspace -scheme Rope -configuration Debug build

No test targets — verification is visual (run a demo and confirm the physics behaves as expected).

Conventions

  • No comments unless the why is non-obvious
  • No speculative code — only implement what is needed right now
  • Commit messages: short, descriptive, imperative tense ("add rope segment friction" not "added" or "adding")
  • One demo per Xcode project under its own folder; add new demos to ScienceDemos.xcworkspace
  • Swift / SpriteKit conventions; lean on the physics engine (bodies, joints) rather than hand-rolling integration

Current State

Completed

  • Workspace scaffolding (ScienceDemos.xcworkspace) aggregating per-demo projects
  • Rope demo (SpriteKit joints)
  • DoubleDomino demo (dominoes)

In Progress

  • Nothing in flight

Next

  • Additional demos listed in the README but not yet in the workspace: double pendulum, mass on an incline, dancing T-handle (zero-g), two-body collision
  • Add a one-or-two-sentence summary per demo and document min Xcode/macOS versions

Decisions Pending

  • None

Do Not Touch

  • Nothing off limits at this time.

Pair Programming

  • Driver writes all code — navigator (Claude) does not write code unless explicitly asked
  • Navigator provides: direction, design decisions, code review, and course corrections
  • One step at a time — navigator waits for driver to confirm before moving to the next
  • Navigator confirms tests pass before suggesting the next step
  • Navigation is terse — no lengthy explanations unless explicitly asked
  • If navigator disagrees with an approach, say so once then follow the driver's lead

Karpathy Rules

All rules apply to every task unless explicitly overridden.

Rule 1 — Think Before Coding

State assumptions explicitly. If uncertain, ask rather than guess. Present multiple interpretations when ambiguity exists. Push back when a simpler approach exists. Stop when confused. Name what's unclear.

Rule 2 — Simplicity First

Minimum code that solves the problem. Nothing speculative. No features beyond what was asked. No abstractions for single-use code. Test: would a senior engineer say this is overcomplicated? If yes, simplify.

Rule 3 — Surgical Changes

The driver should touch only what is necessary to make the current test pass. Don't "improve" adjacent code, comments, or formatting. Don't refactor what isn't broken. Match existing style. Navigator warns the driver if this rule is being broken.

Rule 4 — Agree on Done Before Starting

Before implementing anything, both driver and navigator should agree on what done looks like. A failing test is the preferred success criterion. Don't start until done is defined.

Rule 5 — Dropped

Original rule was written for agentic coding and does not apply to this pair programming model.

Rule 6 — Know When to Stop

If the session is getting long or context feels stale, checkpoint before continuing. Summarise what's done, what's verified, what's next. Update CLAUDE.md to reflect current state, then commit before ending the session. A fresh session with good context beats a stale one with accumulated confusion.

Rule 7 — Surface Conflicts, Don't Average Them

If two patterns contradict, pick one (more recent / more tested). Explain why. Flag the other for cleanup. Don't blend conflicting patterns.

Rule 8 — Read Before You Write

Before adding code, read exports, immediate callers, shared utilities. "Looks orthogonal" is dangerous. If unsure why code is structured a way, ask.

Rule 9 — Test Behaviours, Not Functionality

Tests verify what the code does from the outside, not how it does it internally. Tests must encode WHY the behaviour matters, not just WHAT it does. A test that can't fail when business logic changes is wrong.

Rule 10 — Checkpoint After Every Significant Step

Summarize what was done, what's verified, what's left. Don't continue from a state you can't describe back. If you lose track, stop and restate.

Rule 11 — Match the Codebase's Conventions, Even If You Disagree

Conformance > taste inside the codebase. If you genuinely think a convention is harmful, surface it. Don't fork silently.

Rule 12 — Fail Loud

"Completed" is wrong if anything was skipped silently. "Tests pass" is wrong if any were skipped. Default to surfacing uncertainty, not hiding it.