trailhead
CLAUDE.md0 starsChanged 7 months agoMITView on GitHub
You are working in a pnpm workspace scaffolded from Trailhead — a TypeScript/Node layout optimized for LLM-driven development. Everything below is deliberate. If something stops being true, update this file or docs/architecture.md in the same commit. Check whether docs/trailhead/ exists: Either way, the rules below apply. Runs, in parallel where safe: tsc --noEmit, oxlint, ast-grep scan, markdownlint-cli2, knip, fallow audit, agnix, and vitest run. Exits non-zero on any failure. Target wall time under 10 seconds on a small repo. The…
In this repository8 other files it gives its agents.
- AGENTS.mdAGENTS.md
- add-browser-mcpSkill
- add-packageSkill
- add-visual-lintingSkill
- mine-ast-grep-rulesSkill
- post-friction-lessonSkill
- propose-ast-grep-ruleSkill
- versionSkill
The file
We split this CLAUDE.md into the rules it gives an agent
8 rules. About 0 are common, 3 are distinctive, and 5 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
5
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 7
Check whether docs/trailhead/ exists:
- Very specific: line 59
If the structure surprises you, if a rule seems wrong, or if you made the same mistake twice, stop and use the post-friction-lesson skill.
- Distinctive: line 67
Do not silently edit CLAUDE.md to patch over confusion.
- Distinctive: line 75
Don't hand-copy from existing packages.
- Very specific: line 79
Don't add dependencies without checking pnpm why <pkg> first — it's often already available workspace-wide.
- Distinctive: line 80
Don't write instructions here about code style.
- Very specific: line 81
Don't add another test runner, bundler, or linter.
- Very specific: line 82
Don't skip pnpm check before committing.
≈ “Common” is an estimate: at least 1 in 5 of the 27,641 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
CLAUDE.md
You are working in a pnpm workspace scaffolded from Trailhead — a TypeScript/Node layout optimized for LLM-driven development. Everything below is deliberate. If something stops being true, update this file or docs/architecture.md in the same commit.
What this repo is
Check whether docs/trailhead/ exists:
- Present → this repo is the Trailhead scaffold itself. Scaffold identity, design rationale, and scaffold-specific lessons live under
docs/trailhead/. Ongoing work here is developing the scaffold; layout and tooling decisions are load-bearing. - Absent → this repo is a project derived from Trailhead. Treat the scaffold infrastructure (
tools/, linter configs,docs/architecture.md,docs/conventions.md,docs/decisions/) as inherited and stable; primary work is this project's own code underapps/andpackages/.
Either way, the rules below apply.
The one command you need
pnpm checkRuns, in parallel where safe: tsc --noEmit, oxlint, ast-grep scan, markdownlint-cli2, knip, fallow audit, agnix, and vitest run. Exits non-zero on any failure. Target wall time under 10 seconds on a small repo.
Variants:
pnpm check:fast— typecheck + oxlint + ast-grep + vitest related-to-changed. Use during tight inner loops.pnpm check:full— addsknip --strictandfallowfull scan. Use before committing.pnpm check:json— same analyzers, NDJSON diagnostics on stdout. For external harnesses; schema in ADR 0002.pnpm coverage— vitest with v8 coverage, writescoverage/per package.
The check tool lives in tools/check/. If a run is slow or noisy, open that file; don't route around it.
Layout
apps/ deployable programs (CLI tools, servers, scripts as-a-service)
packages/ publishable libraries (pure-ish code meant to be imported)
packages/config/ shared tsconfig, vitest presets
tools/ dev-time only (check runner, scaffolders, ast-grep rules)
tools/ast-grep/rules project-specific lints (grows over time; see below)
docs/ architecture, conventions, decisions, lessons
.claude/skills Claude Code skills (add-package, propose-ast-grep-rule, mine-ast-grep-rules, post-friction-lesson, add-visual-linting, add-browser-mcp)
templates/ scaffolds for new packages/appsInternal cross-references use workspace:*. Packages resolve each other via exports, not relative paths across workspace boundaries.
Conventions (the linter enforces these; this section is a pointer, not a rulebook)
- TypeScript strict, ESM only. No CommonJS.
- Functional and procedural. No
class, nothis, noextends. If you need grouping, use a module. snake_casefor variables and functions.PascalCasefor types and type-like exports.SCREAMING_SNAKE_CASEfor module-level constants.- One public entry per package:
src/index.ts. Don't reach into siblings' internals. - Tests colocated:
foo.tspairs withfoo.test.ts. - Validate external input with Zod at the boundary. Types inside the boundary are inferred from schemas, not declared separately.
Full list and rationale in docs/conventions.md. The ast-grep rules in tools/ast-grep/rules/ are the source of truth.
When you hit friction
If the structure surprises you, if a rule seems wrong, or if you made the same mistake twice, stop and use the post-friction-lesson skill. The repo learns from friction; drifting around it silently defeats the whole point.
Three adaptation mechanisms, in order of cost:
- Lesson — append to
docs/lessons.mdwith date, what confused you, what worked. Cheap. Always do this. - Rule — if the confusion was a code-pattern issue, use
propose-ast-grep-ruleto add a new YAML rule undertools/ast-grep/rules/. Medium. Do this when the same lesson would repeat. - Structure — if the layout itself was wrong, propose a change to
docs/architecture.mdand the affected paths in one commit. Expensive. Get human review.
Do not silently edit CLAUDE.md to patch over confusion. Fix the thing, then update the doc if the fix changes behavior.
Adding things
- New package:
pnpm scaffold:package <name>(see.claude/skills/add-package/SKILL.md). - New app:
pnpm scaffold:app <name>. - New ast-grep rule: use
.claude/skills/propose-ast-grep-rule/SKILL.md.
Don't hand-copy from existing packages. The scaffolder keeps the structure uniform; uniformity is what makes this repo cheap for you to navigate.
What not to do
- Don't add dependencies without checking
pnpm why <pkg>first — it's often already available workspace-wide. - Don't write instructions here about code style. That's what the linter is for. This file is for things only context can teach (where stuff lives, what the workflow is, what decisions have already been made).
- Don't add another test runner, bundler, or linter. The stack is fixed: vitest, oxlint, ast-grep, markdownlint-cli2, knip, fallow, agnix, tsc (plus cclint for
.claude/files viapnpm lint:claude). Extend via config, not alternatives. - Don't skip
pnpm checkbefore committing. The check command is the feedback loop; bypassing it breaks the contract.
Pointers
docs/architecture.md— why things are where they aredocs/conventions.md— full convention list with examplesdocs/decisions/— ADRs (append-only, numbered)docs/lessons.md— friction log (append-only)docs/trailhead/— scaffold identity, design history, and scaffold-specific lessons (only present in the scaffold repo itself; delete when deriving a new project)docs/task-protocol.md— the.trailhead/task/<id>/artifact contract external harnesses read/writetools/check/README.md— how the check pipeline works and how to extend it.markdownlint-cli2.jsonc— shared Markdown lint config (part ofpnpm check).mcp.json— project-level MCP servers. Registers theast-grepMCP used bypropose-ast-grep-ruleAGENTS.md— portability pointer for tools that readAGENTS.mdinstead ofCLAUDE.mdpnpm lint:claude— validatesCLAUDE.md,AGENTS.md, and.claude/project files (not inpnpm check; run on demand)
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

