From ae0d1da93bb7df89ceb750a58e9d1f43061968cf Mon Sep 17 00:00:00 2001 From: claude Date: Mon, 22 Jun 2026 21:31:25 -0400 Subject: [PATCH] docs(direction): AI-drives-git reframe, lesson=theory, Claude Code as example Lock the course direction before applying it across modules: - AGENTS.md: the git reframe (concepts + "the AI drives git"; arithmetic-by-hand in M1-3, calculator/AI from M4 on; don't re-teach basics); Claude Code as the concrete worked example while staying model-agnostic in principle; lesson-vs-lab rule (lesson = theory only); no-slop voice rule (kill "prose" etc.). - _TEMPLATE.md: Key concepts = theory with example output (never "run this"); Hands-on lab is the only place things run, and from M4 on the learner directs the AI to do git/setup and verifies. Foundation for the M1-6 fixes and the M7-27+capstone sweep. Co-Authored-By: Claude Opus 4.8 (1M context) Claude-Session: https://claude.ai/code/session_01TfzV5QvtPDz8LJS3Pu5VLT --- AGENTS.md | 33 ++++++++++++++++++++++++++++++--- _TEMPLATE.md | 15 +++++++++------ 2 files changed, 39 insertions(+), 9 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 656ad6e..026dca1 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -21,9 +21,11 @@ course content and a dogfooded example of the practices it teaches. ## Core promises (do not violate) -- **Model- and vendor-agnostic.** Never pin a lesson to one LLM vendor. Never hardcode a specific - tool's config filename — say "your agentic tool's committed instructions file." Examples must - survive a model swap. +- **Model-agnostic in principle; Claude Code as the concrete example.** The concepts and workflow + never depend on one LLM or tool. Name the common agentic tools once, then use **Claude Code** as + the worked example in commands and labs — e.g. `claude --version # sub your own agent`. Keep the + *concepts* vendor-neutral; use a concrete tool so steps aren't abstract. Examples must survive a + model swap. - **GitHub is the default, not the requirement.** Keep hosting content provider-neutral; name the alternatives and the self-host track. Do not reintroduce a single specific forge as *the* answer. - **The dependency chain is load-bearing.** A module may assume only what precedes it. Never @@ -33,11 +35,36 @@ course content and a dogfooded example of the practices it teaches. - **Don't pad.** This audience reads fast and trusts concrete over comprehensive. Lead with the pain, show the command and the failure mode. +## What the course teaches about git (the reframe) + +This is **not** a "memorize git commands" course. The reader should finish knowing git is +*critical*, understanding the *concepts* and the *basics*, and — above all — that they don't have to +memorize commands because **the AI drives git for them**. The analogy: learn arithmetic by hand, +then use a calculator. + +- **Modules 1–3 teach the mechanics by hand, on purpose.** The AI is still in the browser; the + learner types git to build intuition. Keep that. +- **Module 4 is the pivot.** It puts the AI in the editor/CLI. From there on the learner **directs + the AI** to do the git work (commit, branch, merge, revert, decide what to commit) and **verifies** + the result — they don't type the commands by hand, and modules must not tell them to. +- **Don't re-teach basics.** Once a concept is introduced, later modules build on it through the AI; + they don't re-explain how to create a branch, etc. + +## Lesson vs. lab (keep them separate) + +- The **lesson / Key-concepts** section is **theory**. To show a command, show it *with example + output* as illustration — never instruct the reader to *run* it there. +- **All hands-on execution lives in the lab.** The lesson must not duplicate commands the lab runs. + ## Voice Direct, concrete, rigorous. Reframe ops instincts the reader already has toward AI-assisted work. No motivational filler. When in doubt, show the command and what goes wrong without it. +**No slop.** Don't write like an AI. Avoid "prose" (say "writing", "words", or "docs"), "unlock", +"leverage" as filler, "delve", "dive in", "seamless", "in today's fast-paced", "it's worth noting". +Don't lean on em-dashes — at density they read as a machine tell; vary the punctuation. + ## Conventions for labs - Labs run on the learner's **own machine, any OS**. Don't assume a sandbox, cloud account, or diff --git a/_TEMPLATE.md b/_TEMPLATE.md index f92b13b..ed44d2e 100644 --- a/_TEMPLATE.md +++ b/_TEMPLATE.md @@ -39,9 +39,10 @@ By the end of this module you can: ## Key concepts -*The actual teaching content, in prose, with commands and snippets inline. This is the bulk of the -module. No fixed length — go as deep as the topic needs and no further. Use subheadings freely. -Reframe an ops instinct the reader already has wherever you can.* +*The teaching content — **theory only**. Explain the concept and why it matters; reframe an ops +instinct the reader already has. To show a command, show it **with example output** as illustration — +do NOT tell the reader to run anything here (all hands-on is the lab, and the lesson must not +duplicate it). No "prose"/slop words. No fixed length — go as deep as the topic needs, no further.* --- @@ -55,9 +56,11 @@ differentiator; never skip it.* ## Hands-on lab -*A practical exercise that uses AI **and** the tool together, run on the reader's own machine. This -is a tools course — end at a keyboard, not a quiz. State the lab language (Python or shell) once. -Provide starter files in `lab/` where useful and reference them by path.* +*The only place the reader runs things. End at a keyboard, not a quiz. State the lab language +(Python or shell) once; provide starter files in `lab/` and reference them by path. **From Module 4 +on, the learner directs the AI agent (Claude Code as the worked example) to do the git/setup work +and then verifies it — they don't type the commands by hand.** In Modules 1–3 the learner still +runs git manually, on purpose.* **You'll need:** **