agentleFS
ahumblenerdahumblenerd/tour-of-agents/CLAUDE.md

tour-of-agents

CLAUDE.md35 starsChanged 8 months agoMITView on GitHub

Interactive browser-based course teaching AI agent systems via Pyodide + Next.js. Follow this TDD loop for ALL code changes. No exceptions. The git pre-commit hook runs three checks in order: 1. Line count -- rejects any staged .ts/.tsx file over 200 lines 2. TypeScript -- tsc --noEmit must pass 3. lint-staged -- runs ESLint + related vitest tests on staged files All in src/test/fixtures/: - trace-events.ts -- sample TraceEvent[] arrays (simple, tool, llm, full, error) - pyodide-outputs.ts -- raw stdout…

The file

We split this CLAUDE.md into the rules it gives an agent

12 rules. About 0 are common, 9 are distinctive, and 3 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈9

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Follow this TDD loop for ALL code changes.

    line 7
  2. Very specific:

    Create *.test.ts or *.test.tsx next to the file you're changing

    line 10
  3. Distinctive:

    Test must fail before you write implementation

    line 11
  4. Very specific:

    Use fixtures from src/test/fixtures/ for sample data -- never inline large test data

    line 13
  5. Distinctive:

    Keep files under 200 lines (pre-commit hook enforces this)

    line 22
  6. Distinctive:

    If a file would exceed 200 lines, split it into smaller modules

    line 23
  7. Very specific:

    Run npm run build to verify static export works

    line 27
  8. Distinctive:

    Use fixtures for Pyodide stdout samples, trace events, LLM responses

    line 70
  9. Distinctive:

    No tests for actual LLM API calls (requires real keys)

    line 83
  10. Distinctive:

    No E2E browser tests yet

    line 84
  11. Distinctive:

    No tests for shadcn/ui primitives (tested upstream)

    line 85
  12. Distinctive:

    All visualization derives from TraceEvent[] pipeline

    line 118

≈ “Common” is an estimate: at least 1 in 5 of the 28,029 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

A Tour of Agents

Interactive browser-based course teaching AI agent systems via Pyodide + Next.js.

Development Loop (MANDATORY)

Follow this TDD loop for ALL code changes. No exceptions.

1. Write Test First

  • Create *.test.ts or *.test.tsx next to the file you're changing
  • Test must fail before you write implementation
  • Run: npm test -- --reporter=verbose <path>
  • Use fixtures from src/test/fixtures/ for sample data -- never inline large test data

2. Write Storybook Story

  • For every component, create a *.stories.tsx next to it
  • Stories cover: default state, loading, error, edge cases
  • Verify visually: npm run storybook

3. Write Implementation

  • Make the test pass
  • Keep files under 200 lines (pre-commit hook enforces this)
  • If a file would exceed 200 lines, split it into smaller modules

4. Connect & Integrate

  • Wire the component into the page/layout
  • Run npm run build to verify static export works

5. Execute & Verify

  • npm test -- all tests pass
  • npm run build -- no build errors
  • Manual spot check in browser if UI changed

File Rules

  • Max 200 lines per file -- enforced by git pre-commit hook
  • Lesson content: split markdown into separate content/ files if needed
  • One component per file, one hook per file

CSS & Styling Rules (MANDATORY)

  • NEVER hardcode hex colors -- use Tailwind theme tokens: bg-muted, text-foreground, border-border, text-destructive etc.
  • NEVER use raw color values like text-red-400, bg-blue-950 -- use semantic tokens: text-destructive, bg-primary
  • Use --header-height CSS variable for header offset -- never hardcode 3.5rem in layout calculations
  • All <input> elements must have focus rings -- use focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring or shadcn Input component
  • Light/dark mode must both work -- test both before shipping. Never use colors that only look correct in one mode
  • Use flex ratios over hardcoded heights -- flex-[3] not h-[40%] for responsive splits
  • Mobile: use scrollbar-none + flex-nowrap + overflow-x-auto for horizontal pill/chip scrolling
  • Touch targets minimum 44x44px on mobile interactive elements

Pre-Commit Checks (automatic)

The git pre-commit hook runs three checks in order:

  1. Line count -- rejects any staged .ts/.tsx file over 200 lines
  2. TypeScript -- tsc --noEmit must pass
  3. lint-staged -- runs ESLint + related vitest tests on staged files

Test Strategy

Unit Tests (vitest + jsdom)

  • src/lib/**/*.test.ts -- pure logic: trace parsing, mermaid generation, registry
  • src/hooks/*.test.ts -- hook behavior with mocked deps
  • src/components/**/*.test.tsx -- component rendering with RTL
  • Snapshot tests for deterministic output (mermaid diagrams, trace parsing)

Integration Tests (stub-based, MSW)

  • src/lib/trace/integration.test.ts -- full pipeline: raw stdout -> parse -> mermaid
  • MSW handlers in src/test/msw-handlers.ts stub OpenAI/Anthropic API responses
  • MSW server auto-starts in test setup (src/test/setup.ts)
  • Use fixtures for Pyodide stdout samples, trace events, LLM responses

Storybook Stories

  • src/components/**/*.stories.tsx -- every component gets stories
  • Cover: default, loading, empty, error, with-data variants
  • Storybook vitest addon runs stories as browser tests (npm run test:all)

Coverage

  • npm run test:coverage -- generates coverage report
  • 80% threshold enforced on src/lib/** and src/hooks/**
  • Excluded: lesson content files, Python runtime string modules

What to Skip

  • No tests for actual LLM API calls (requires real keys)
  • No E2E browser tests yet
  • No tests for shadcn/ui primitives (tested upstream)

Test Fixtures

All in src/test/fixtures/:

  • trace-events.ts -- sample TraceEvent[] arrays (simple, tool, llm, full, error)
  • pyodide-outputs.ts -- raw stdout strings as Pyodide would produce
  • llm-responses.ts -- mock OpenAI/Anthropic API response payloads

Commands

npm test               # Unit tests (vitest + jsdom)
npm run test:watch     # Unit tests in watch mode
npm run test:coverage  # Unit tests with coverage report
npm run test:all       # All tests including storybook browser tests
npm run storybook      # Start storybook dev server
npm run dev            # Start Next.js dev server
npm run build          # Production build (static export)
npm run lint           # ESLint

Architecture

  • src/app/ -- Next.js pages (server components where possible)
  • src/components/ -- React components (client components use "use client")
  • src/lib/ -- Pure logic, no React. Types, parsers, lesson data, Python runtime strings
  • src/hooks/ -- React hooks
  • src/test/ -- Test setup, fixtures, MSW handlers

Key patterns:

  • Pyodide loaded once via React context (PyodideProvider)
  • Python runtime modules stored as TS string constants, written to Pyodide FS
  • All visualization derives from TraceEvent[] pipeline
  • MSW stubs LLM APIs at the network level for integration tests
  • Mock LLM responses when no API key present (runtime fallback)

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.