agentleFS
robmclartyrobmclarty/trailhead/CLAUDE.md

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…

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
  1. Very specific:

    Check whether docs/trailhead/ exists:

    line 7
  2. Very specific:

    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.

    line 59
  3. Distinctive:

    Do not silently edit CLAUDE.md to patch over confusion.

    line 67
  4. Distinctive:

    Don't hand-copy from existing packages.

    line 75
  5. Very specific:

    Don't add dependencies without checking pnpm why <pkg> first — it's often already available workspace-wide.

    line 79
  6. Distinctive:

    Don't write instructions here about code style.

    line 80
  7. Very specific:

    Don't add another test runner, bundler, or linter.

    line 81
  8. Very specific:

    Don't skip pnpm check before committing.

    line 82

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
CLAUDE.md

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 under apps/ and packages/.

Either way, the rules below apply.

The one command you need

pnpm check

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.

Variants:

  • pnpm check:fast — typecheck + oxlint + ast-grep + vitest related-to-changed. Use during tight inner loops.
  • pnpm check:full — adds knip --strict and fallow full 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, writes coverage/ 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/apps

Internal 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, no this, no extends. If you need grouping, use a module.
  • snake_case for variables and functions. PascalCase for types and type-like exports. SCREAMING_SNAKE_CASE for module-level constants.
  • One public entry per package: src/index.ts. Don't reach into siblings' internals.
  • Tests colocated: foo.ts pairs with foo.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:

  1. Lesson — append to docs/lessons.md with date, what confused you, what worked. Cheap. Always do this.
  2. Rule — if the confusion was a code-pattern issue, use propose-ast-grep-rule to add a new YAML rule under tools/ast-grep/rules/. Medium. Do this when the same lesson would repeat.
  3. Structure — if the layout itself was wrong, propose a change to docs/architecture.md and 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 via pnpm lint:claude). Extend via config, not alternatives.
  • Don't skip pnpm check before committing. The check command is the feedback loop; bypassing it breaks the contract.

Pointers

  • docs/architecture.md — why things are where they are
  • docs/conventions.md — full convention list with examples
  • docs/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/write
  • tools/check/README.md — how the check pipeline works and how to extend it
  • .markdownlint-cli2.jsonc — shared Markdown lint config (part of pnpm check)
  • .mcp.json — project-level MCP servers. Registers the ast-grep MCP used by propose-ast-grep-rule
  • AGENTS.md — portability pointer for tools that read AGENTS.md instead of CLAUDE.md
  • pnpm lint:claude — validates CLAUDE.md, AGENTS.md, and .claude/ project files (not in pnpm check; run on demand)

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.