agentleFS
JSchOBLJSchOBL/agentic-ai-learning-journey/CLAUDE.md

agentic-ai-learning-journey

CLAUDE.md3 starsChanged 4 months agoMITView on GitHub

A hands-on lab for learning to write CLAUDE.md files (and later skills, hooks, and MCP config). Each level-N/ folder is a self-contained exercise: the learner reads a brief, writes a CLAUDE.md, has an agent build the project from it, then runs the coach for a review. See ROADMAP.md for the plan and status. This file is guidance for anyone working on the lab itself, not for learners doing a level. - level-N/ — one self-contained exercise each: README.md (the brief),…

The file

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

9 rules. About 0 are common, 7 are distinctive, and 2 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈7

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 2

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Every claim about Claude Code behaviour cites official docs in a Sources section.

    line 30
  2. Very specific:

    Use Claude Code's real tool names — Read, Write, Edit, Bash, Glob, Grep, Task.

    line 32
  3. Distinctive:

    Prefer tables to bulleted comparisons.

    line 38
  4. Distinctive:

    No emoji in headings.

    line 39
  5. Distinctive:

    Don't claim a level, file, or feature exists before it does.

    line 46
  6. Distinctive:

    Don't add time estimates for unscoped work.

    line 48
  7. Distinctive:

    Don't narrate the repository's own edit history to readers.

    line 49
  8. Distinctive:

    Don't solve a level for the learner.

    line 51
  9. Very specific:

    level-N/CLAUDE.md files load into context: When Claude reads inside a level folder, that folder's CLAUDE.md is pulled into context …

    line 56

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

Agentic AI Learning Journey

A hands-on lab for learning to write CLAUDE.md files (and later skills, hooks, and MCP config). Each level-N/ folder is a self-contained exercise: the learner reads a brief, writes a CLAUDE.md, has an agent build the project from it, then runs the coach for a review. See ROADMAP.md for the plan and status.

This file is guidance for anyone working on the lab itself, not for learners doing a level.

Layout

  • level-N/ — one self-contained exercise each: README.md (the brief), LEARNINGS.md (fixed takeaways + the learner's dated notes), and — for early levels — a starter CLAUDE.md. Later levels drop the starter and have the learner create the whole .claude/ themselves. All four levels are built.
  • .claude/skills/claude-md-coach/ — the shared skill that reviews a learner's CLAUDE.md and updates the level's LEARNINGS.md.
  • docs/ — reference library, one canonical file per topic. A fact lives in exactly one of them. Predates the lab; levels link learners to it.
  • samples/ — copyable artifacts, not prose about artifacts. Directories must work when copied into .claude/ as-is.
  • ROADMAP.md — level plan and status. Unbuilt levels are marked provisional; never link to them as though they're finished.

Conventions

  • Prose over ASCII box diagrams. The earlier draft was mostly boxes restating the sentence above them; that content was cut, not moved.
  • Every claim about Claude Code behaviour cites official docs in a Sources section. If it can't be cited, say it's untested.
  • Use Claude Code's real tool names — Read, Write, Edit, Bash, Glob, Grep, Task. Never read_file / run_command; those are pseudocode from hand-built-agent tutorials and invite Claude to call tools that don't exist.
  • A level's README.md states what to build and its pitfalls, never how — the "how" is the learner's job. Don't leak implementation choices (language, libraries, commands) into a brief; those belong in the learner's CLAUDE.md.
  • Prefer tables to bulleted comparisons.
  • No emoji in headings.

Non-negotiable

  • Don't restate content that lives in another file — link to it. Duplication is the failure mode this structure was built to fix. Six copies of the skills-vs-hooks table is how the last version got unmaintainable.
  • Don't claim a level, file, or feature exists before it does. Provisional levels stay marked provisional.
  • Don't add time estimates for unscoped work.
  • Don't narrate the repository's own edit history to readers. The lesson can stay; "the previous version of this file said X" goes in the commit message.
  • Don't solve a level for the learner. Starter CLAUDE.md files stay empty under their headings, and the coach skill challenges rather than rewrites.

Gotchas

  • level-N/CLAUDE.md files load into context. When Claude reads inside a level folder, that folder's CLAUDE.md is pulled into context automatically — that's the whole point during a level, but be aware while editing the starters that their contents become live instructions, not inert text.
  • The filesystem is case-insensitive (macOS). example-CLAUDE.md and EXAMPLE-CLAUDE.md collide — renames between them need an intermediate step.
  • samples/example-CLAUDE.md is deliberately not named CLAUDE.md: a nested CLAUDE.md there would load into context whenever Claude reads that directory.
  • Setup instructions are version-sensitive (Ollama v0.14+, Jan 2026). Anything claiming to be verified carries an as-of date. Update the date or drop the claim.

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.