1 files changed, 82 insertions, 0 deletions
diff --git a/languages/typescript/CLAUDE.md b/languages/typescript/CLAUDE.md
new file mode 100644
index 0000000..1794115
--- /dev/null
+++ b/languages/typescript/CLAUDE.md
@@ -0,0 +1,82 @@
+# CLAUDE.md
+
+## Project
+
+TypeScript/JavaScript project. Customize this section with your own
+description, layout, and conventions.
+
+**Typical layout:**
+- `src/` — source modules
+- `tests/` or `*.test.ts` beside the source — test files
+- `package.json` — scripts and dependencies
+- `tsconfig.json` — compiler options
+
+## Build & Test Commands
+
+If the project has a Makefile, document targets here. Common pattern:
+
+```bash
+make test                   # run the test suite
+make coverage               # suite + coverage report
+make typecheck              # tsc --noEmit across the project
+make lint                   # eslint
+make build                  # production build
+```
+
+Direct equivalents: `npm test`, `npx tsc --noEmit`, `npx eslint src/`,
+`npx prettier --check .`, `node --test`.
+
+## Language Rules
+
+See rule files in `.claude/rules/`:
+- `typescript-testing.md` — test conventions and mocking discipline
+- `verification.md` — verify-before-claim-done discipline
+
+## Git Workflow
+
+Commit conventions: see `.claude/rules/commits.md` (author identity,
+no AI attribution, message format).
+
+Pre-commit hook in `githooks/` scans for secrets and parse-checks staged TS/JS.
+Activate on a fresh clone with `git config core.hooksPath githooks`.
+
+## Problem-Solving Approach
+
+Investigate before fixing. When diagnosing a bug:
+1. Read the relevant module and trace what actually happens
+2. Identify the root cause, not a surface symptom
+3. Write a failing test that captures the correct behavior
+4. Fix, then re-run tests
+
+## Testing Discipline
+
+TDD is the default: write a failing test before any implementation. If you can't
+write the test, you don't yet understand the change. Details in
+`.claude/rules/typescript-testing.md`.
+
+## Editing Discipline
+
+A PostToolUse hook parse-checks every TS/JS file after Edit/Write/MultiEdit and
+blocks on a syntax error. It covers `.ts`, `.tsx`, `.mts`, `.cts`, `.js`,
+`.jsx`, `.mjs`, and `.cjs`.
+
+Two checkers, because one tool can't do both jobs: `node --check` for
+JavaScript, `tsc` filtered to syntax diagnostics for TypeScript. Do not
+substitute `node --check` for the TypeScript path — it ignores
+`--experimental-strip-types`, so it rejects valid TypeScript and accepts broken
+TypeScript (measured on node v26.4.0).
+
+Full type checking is not enforced by the hook: it needs the whole project graph
+and its dependencies resolved, which is a build-scale operation rather than a
+per-keystroke one. Run it via `make typecheck`. Formatting is likewise not
+enforced; adopt a style per project in the project's own config.
+
+## What Not to Do
+
+- Don't add features beyond what was asked
+- Don't refactor surrounding code when fixing a bug
+- Don't reach for `any` to silence a type error — narrow the type instead
+- Don't use `==` where `===` is meant
+- Don't add comments to code you didn't change
+- Don't commit `.env` files, credentials, or API keys — the pre-commit hook
+  catches common patterns but isn't a substitute for care