docs(claude): communication style — plain language for 3D / physics / graphics

Adds a "Communication style" section after "How to operate" that documents
how to discuss spatial / physics / animation / dat-format / protocol
topics with the user. The user has asked repeatedly for plain-language
framing of new concepts: name the idea in English first, then introduce
the term of art; give units (degrees, meters) instead of raw floats;
use analogies for spatial concepts (BSP = nested rooms, contact plane =
imaginary floor, sphere sweep = rolling a ball, dot/cross products);
walk through control flow frame-by-frame; flag terms of art the first
time they appear.

The goal is collaborative learning, not dumbed-down content.
This commit is contained in:
Erik 2026-04-30 13:21:21 +02:00
parent a48883af2d
commit 5210bd3d55

View file

@ -112,6 +112,51 @@ a phase just landed, and move to the next todo item.
always yes — keep going.** The single exception is visual verification;
otherwise, act.
## Communication style
The user is a strong systems / C# / network programmer but **less
practiced at 3D math, physics, graphics, and animation**. They want
to learn — they're not asking for dumbed-down content, but for
explanations that build understanding alongside the work.
When discussing 3D / physics / graphics / animation / dat-format /
protocol-internals topics:
- **Name the concept in plain language first**, then introduce the
term of art. "The angle of a slope (we call its straight-up
component `Normal.Z`)" rather than dropping `normal.Z = cos θ`
with no anchor.
- **Give units**: degrees, meters, cm — NOT raw floats. "FloorZ ≈
0.66 means slopes up to about 49° are walkable" rather than
"FloorZ = 0.66417414f". Floats are for the code; English is for
the conversation.
- **Use analogies for spatial concepts** when they fit. A BSP tree
is "a way of slicing space into nested rooms"; a contact plane is
"the imaginary floor under the player's feet"; a sphere sweep is
"rolling a ball forward through space and stopping it on contact";
a cross product is "the direction perpendicular to two arrows";
a dot product is "how aligned two arrows are (1 = same, 0 =
perpendicular, -1 = opposite)".
- **Don't pile on multiple new concepts in one paragraph.** If a
problem touches step-up AND step-down AND edge-slide AND
walkable-polygon tracking, walk through them one at a time, each
with what it does and why it exists.
- **Show the math when it matters, but explain it.** Don't just
drop a formula and move on; tag it with "what this means
geometrically".
- **Use frame-by-frame walk-throughs** for control-flow-heavy
physics: "frame N: player here, lands. Frame N+1: state checks…"
beats a function-call trace for understanding what's happening
in motion.
- **Flag terms of art** the first time they appear in a session,
even if they're sprinkled through code comments. "Broadphase",
"BSP", "step-up", "ContactPlane", "ValidateWalkable" — they
earn their meaning the first time you spell it out.
The goal is collaborative learning. Don't simplify the content; just
make sure every term and number is grounded so the user can keep up
and build intuition over time.
## Development workflow: grep named → decompile → verify → port
**This is the mandatory workflow for implementing ANY AC-specific behavior.**