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:** **