CLAUDE.md · diff
git:20260721.3ce6c94 to git:20260805.fb6c4b3
61 added, 34 removed. Audit A to A.
# claude-cad — notes for Claude Code
- This repo is a **toolkit**, not a CAD project. It ships a Claude Code skill,
- prompts, and docs for generating CadQuery parts whose STEP files reliably open in
- SolidWorks. The defining idea: **never trust generated geometry — prove it's valid
- before export.**
+ This repo is **a toolkit *and* the default workspace**. It ships a Claude Code
+ skill, prompts, and docs for generating CadQuery parts whose STEP files reliably
+ open in SolidWorks. The defining idea: **never trust generated geometry — prove
+ it's valid before export.**
- ## Parts belong in the user's own folder, not here
+ ## The clone is the workspace (default)
- The skill installs globally, so claude-cad applies in any directory. This repo
- stays useful as a reference the user returns to — `prompts/workflows/project_init.md`
- for each new project, `prompts/templates/`,
- `skills/cadquery-modeling/scripts/preflight.py`, `docs/`. The only
- things that normally change *in* this repo are the toolkit itself and `examples/`.
+ The skill is committed at `.claude/skills/cadquery-modeling/`, so a fresh clone
+ arrives with it **already active — no install, no reload**. The default workflow
+ is: clone → open in VS Code → describe a part. Parts go in the top-level `parts/`
+ (a `diagnose.py` is shipped there so imports resolve); output lands in `output/`.
+ Both are git-ignored, so the user's work stays out of `git status` and `git pull`
+ (to update the toolkit) stays clean.
- If someone asks you to model something while this repo is the working directory:
- say that a single throwaway part here is harmless (outputs are git-ignored, and a
- cloner can't affect upstream), but that real or repeated work belongs in its own
- folder — a second design has nowhere to go otherwise, and toolkit `git pull`s start
- tangling with their files. Offer to set that folder up. Don't refuse outright.
+ If someone asks you to model something while this repo is the working directory,
+ **that is now the intended path — just do it.** Mention the standalone alternative
+ only when it actually fits.
+ ## When to suggest a separate project (the alternative)
+
+ A standalone project folder elsewhere — set up by pasting
+ `prompts/workflows/project_init.md`, producing the three-folder `claude-cad/` +
+ `parts/` + `output/` layout that `examples/sbc-case/` demonstrates — is worth
+ suggesting when the user wants to:
+
+ - **version their own designs** (the clone git-ignores `parts/`, and committing
+ there tangles with toolkit `git pull`s),
+ - keep **several unrelated projects** apart, or
+ - keep this clone **pristine** as a reference they `git pull` to update.
+
+ Don't push it by default; the point of the new layout is that most people never
+ need it.
+
## Helping someone who just arrived
- Most people who open Claude Code here have just cloned the repo. Useful things to
- offer, in order:
+ Most people who open Claude Code here have just cloned the repo. The skill is
+ already active (committed at `.claude/skills/`), so there's little to set up:
- 1. **Point them at `QUICKSTART.md`** — it's the linear path from clone to a
- verified part. Don't re-explain it; it's already written.
- 2. **Offer to install the skill for them** — copy `skills/cadquery-modeling/` to
- the location item 3 picks, using the right commands for their OS. Confirm the
- files landed, and tell them to reload Claude Code — skills only load at
- session start.
- 3. **Prefer project scope when installing.** Copy the skill into the user's
- project at `<project>/.claude/skills/`, not the personal directory
- (`~/.claude/skills/` on macOS/Linux, `%USERPROFILE%\.claude\skills\` on
- Windows), unless they say they do CAD constantly. A personal install loads its
- description into every session on their machine, and crowds the skill-listing
- budget.
- 4. **Check their Python** — `py -3.11 -c "import cadquery, OCP; print('env OK')"`.
+ 1. **Point them at `QUICKSTART.md`** — clone → Python → open in VS Code → confirm
+ the skill is already listed (`/skills`) → describe a part. Don't re-explain it.
+ 2. **Check their Python** — `py -3.11 -c "import cadquery, OCP; print('env OK')"`.
If `OCP` fails to import they're on too-new a Python (see below).
+ 3. **Then just build.** First part goes in `parts/`; run it with
+ `py -3.11 parts/<name>.py`; batch-verify with `py -3.11 preflight.py`.
+ If `/skills` doesn't list `cadquery-modeling`, they likely opened a subfolder as
+ the workspace root instead of the repo root, or need to reload the window — skills
+ load at session start.
+
## Conventions that differ from what you'd assume
These are the things that bite people. They're not derivable from the code:
- **Python 3.11, not the newest release.** The `OCP` kernel binding lags new
Python versions, so `pip install cadquery` succeeds while `import OCP` fails.
- **Export paths resolve from the script file, never the working directory.** A
bare `"../output/x.step"` silently writes one folder too high when the script is
run from the project root. Always
`Path(__file__).resolve().parent.parent / "output"`, and print the resolved path.
- - **`from diagnose import check` needs `diagnose.py` copied into the project's
- `parts/` folder.** It lives in `skills/cadquery-modeling/scripts/` here; that
- path is not importable from a user's project.
+ - **`from diagnose import ...` resolves against `parts/diagnose.py`**, which is
+ shipped in the clone. In a standalone project, `project_init` copies it there
+ (and keeps the canonical copy in that project's `claude-cad/`). The skill's
+ master copy lives in `skills/cadquery-modeling/scripts/`.
- **A green `[OK]` proves nothing — and neither do validity + solid count alone.**
A `.shell()` that silently no-ops returns a valid, single, *un-hollowed* solid.
Always assert volume against a hand estimate, and use `assert_points()` for any
feature whose position matters. See `docs/verification.md` and Pitfall 4b.
- **The one verified silent-corruption trap is `.shell()` on a solid whose
removed face was filleted** (Pitfall 4b — returns the part un-hollowed,
`IsValid=True`). The historically blamed operations (countersinks on shelled
walls, face-selected `cutThruAll`, lofted domes) do **not** reproduce on the
current kernel; their replacement patterns are kept as preferred constructions.
Read `docs/occ_pitfalls.md` (each pitfall's Verified behaviour block) before
writing code that shells, fillets, or lofts; re-test with
`tests/repro_pitfalls.py` after a kernel upgrade.
- **Auto-repair is deliberately conservative.** It only discards unambiguous
debris; it never patches invalid topology, because that would hide real design
errors. Don't "improve" it into something that silently fixes more.
## Editing this repo
+ - **The skill is committed twice:** `skills/cadquery-modeling/` (canonical — the
+ copy you EDIT, and what people copy to install elsewhere) and
+ `.claude/skills/cadquery-modeling/` (the active-on-clone copy). Always edit the
+ **canonical** copy.
+ - **HARD STEP — after ANY change under `skills/cadquery-modeling/`, before you
+ commit:** run `py -3.11 tools/sync_skill.py --fix`, then
+ `py -3.11 tools/sync_skill.py` and confirm it prints `[ok]`. A commit that
+ touches the skill without syncing the `.claude/` copy is a defect. Three things
+ catch it if you forget — `preflight.py` warns on every run, `tests/test_sync.py`
+ fails, and the check above — but none of them un-ship a bad commit, so do it by
+ hand. (`--fix` refuses if you edited the *active* copy instead; it won't
+ silently overwrite your edit — move the change to canonical and re-run.)
- `skills/cadquery-modeling/references/*.md` and several `docs/*.md` are
**mirrored copies**. If you change one, sync its twin (`occ_pitfalls`,
`verification`, `diagnosis`, `environment`→`python_env_setup`,
- `solidworks_checks`→`solidworks_integration`).
+ `solidworks_checks`→`solidworks_integration`). Because the skill is committed
+ twice, an `occ_pitfalls.md` edit lives in **three** copies: the docs↔skill
+ mirror pair you sync by hand, plus the `.claude/` skill copy that
+ `sync_skill.py --fix` refreshes for you. `tests/test_sync.py` checks both the
+ skill copies and all five doc mirror pairs.
- The same rule often appears in the skill, the docs, and the prompts. After
changing a rule, grep for it — leaving one copy stale is the most common defect
in this repo.
- **Examples and templates must stay generic.** No proprietary, confidential, or
patent-pending designs. Abstract the method, never someone's product.
- Any Python added here must pass its own verification block before it's
presented as working.