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),…
In this repository2 other files it gives its agents.
- level-1/CLAUDE.mdCLAUDE.md
- claude-md-coachSkill
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
- Distinctive: line 30
Every claim about Claude Code behaviour cites official docs in a Sources section.
- Very specific: line 32
Use Claude Code's real tool names — Read, Write, Edit, Bash, Glob, Grep, Task.
- Distinctive: line 38
Prefer tables to bulleted comparisons.
- Distinctive: line 39
No emoji in headings.
- Distinctive: line 46
Don't claim a level, file, or feature exists before it does.
- Distinctive: line 48
Don't add time estimates for unscoped work.
- Distinctive: line 49
Don't narrate the repository's own edit history to readers.
- Distinctive: line 51
Don't solve a level for the learner.
- Very specific: line 56
level-N/CLAUDE.mdfiles load into context: When Claude reads inside a level folder, that folder's CLAUDE.md is pulled into context …
≈ “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.
Files
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 starterCLAUDE.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'sCLAUDE.mdand updates the level'sLEARNINGS.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. Neverread_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.mdstates 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'sCLAUDE.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.mdfiles stay empty under their headings, and the coach skill challenges rather than rewrites.
Gotchas
level-N/CLAUDE.mdfiles load into context. When Claude reads inside a level folder, that folder'sCLAUDE.mdis 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.mdandEXAMPLE-CLAUDE.mdcollide — renames between them need an intermediate step. samples/example-CLAUDE.mdis deliberately not namedCLAUDE.md: a nestedCLAUDE.mdthere 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.
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.

