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:
parent
a48883af2d
commit
5210bd3d55
1 changed files with 45 additions and 0 deletions
45
CLAUDE.md
45
CLAUDE.md
|
|
@ -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;
|
always yes — keep going.** The single exception is visual verification;
|
||||||
otherwise, act.
|
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
|
## Development workflow: grep named → decompile → verify → port
|
||||||
|
|
||||||
**This is the mandatory workflow for implementing ANY AC-specific behavior.**
|
**This is the mandatory workflow for implementing ANY AC-specific behavior.**
|
||||||
|
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue