De-slop: remove every em-dash + banned words across all modules + capstone (#94)
Sync course wiki / sync-wiki (push) Successful in 4s

Co-authored-by: claude <claude@jpaul.io>
Co-committed-by: claude <claude@jpaul.io>
This commit was merged in pull request #94.
This commit is contained in:
2026-06-22 23:21:22 -04:00
committed by Claude (agent)
parent 513d7e7ac8
commit c098933f25
99 changed files with 1324 additions and 1315 deletions
+25 -25
View File
@@ -1,4 +1,4 @@
# Module 5 Commit the AI's Config, Not Just the Code
# Module 5: Commit the AI's Config, Not Just the Code
> **The instructions you give the model are as worth versioning as the code it writes.** Write your
> project's conventions down once, commit them, and every teammate (and every agent) inherits the
@@ -8,10 +8,10 @@
## Prerequisites
- **Module 1** you have the `tasks-app` project, an editor, and a terminal.
- **Module 2** you can `commit`, read a `diff`, and treat commits as checkpoints. This module adds
- **Module 1**: you have the `tasks-app` project, an editor, and a terminal.
- **Module 2**: you can `commit`, read a `diff`, and treat commits as checkpoints. This module adds
one more thing worth committing.
- **Module 4** the AI now lives in your editor or CLI and reads your files directly. That's the
- **Module 4**: the AI now lives in your editor or CLI and reads your files directly. That's the
whole reason a *committed* instructions file matters: an editor-integrated tool can pick it up
automatically, where a browser chat never could.
@@ -27,7 +27,7 @@ By the end of this module you can:
3. Commit that file so the configuration travels with the repo, not with one person's machine.
4. Demonstrate the AI obeying the committed instructions, and changing its behavior when you change
the file.
5. Explain why committing the config makes AI behavior *reviewable* a change to how the AI works
5. Explain why committing the config makes AI behavior *reviewable*: a change to how the AI works
arrives as a diff, like any other change.
---
@@ -37,14 +37,14 @@ By the end of this module you can:
### The file your tool is already looking for
Open almost any agentic coding tool and, before it does anything, it scans the repo for a
**committed, repo-level instructions file** a plain-text (usually markdown) file at the project
**committed, repo-level instructions file**: a plain-text (usually markdown) file at the project
root that tells the AI how *this* project works. Different vendors look for different filenames, and
the names change; that's noise. The durable fact is the pattern: **your agentic tool reads a
committed instructions file from the repo, and you control what's in it.**
> Throughout this module we'll say "your agentic tool's committed instructions file" rather than name
> one. Find yours in your tool's docs (look for "project instructions," "rules," "context," or a
> repo-root config file). Some tools even read more than one filename point them all at the same
> repo-root config file). Some tools even read more than one filename; point them all at the same
> content if so. The principle outlives any one vendor's filename.
Without this file, you re-explain your project every session: "we use 4-space indent," "run the tests
@@ -58,17 +58,17 @@ becomes something the project *carries*.
An instructions file is not a prompt and it's not documentation for humans (that's the README). It's
a briefing for an agent that will edit this code. Keep it to what changes the AI's behavior:
- **Project conventions** language version, layout, naming, the patterns this codebase actually
- **Project conventions**: language version, layout, naming, the patterns this codebase actually
uses. "Core logic lives in `tasks.py`; the CLI front end is `cli.py`; state persists to
`tasks.json`."
- **Build and test commands** the exact commands, copy-pasteable. "Run the app with
- **Build and test commands**: the exact commands, copy-pasteable. "Run the app with
`python cli.py <command>`. Run tests with `python -m unittest`. Don't claim a change works until
the tests pass." This single line stops the AI from inventing a test runner you don't use.
- **Coding standards** formatting, typing, error handling, the libraries you do and don't want.
- **Coding standards**: formatting, typing, error handling, the libraries you do and don't want.
"Use the standard library only, no third-party packages. Type-hint public functions."
- **"Don't touch these files."** — the off-limits list. Generated files, vendored code, secrets,
- **"Don't touch these files."** The off-limits list. Generated files, vendored code, secrets,
anything the AI should read but never rewrite. "Never edit `tasks.json` by hand; it's generated."
- **House style** the taste calls that otherwise come back wrong every time. "Keep functions
- **House style**: the taste calls that otherwise come back wrong every time. "Keep functions
small. Match the existing style; don't reformat files you're not changing. Prefer clarity over
cleverness."
@@ -78,7 +78,7 @@ signal (see *Where it breaks*).
### Why commit it instead of keeping it in your head (or your settings)
Most tools also let you set instructions *globally* on your machine, for all projects. That's
Most tools also let you set instructions *globally* (on your machine, for all projects). That's
useful for personal preferences, but it's the wrong home for project knowledge, because of where it
lives: on *your* laptop, invisible to everyone else.
@@ -103,9 +103,9 @@ Code as the concrete case (sub your own agent's filenames):
| File | Shared or personal |
| --- | --- |
| `CLAUDE.md` (the instructions file) | **Shared** the whole point of this module |
| `.claude/settings.json` (project settings: permissions, hooks config) | **Shared** the team runs the same setup |
| `.claude/settings.local.json` (your personal overrides) | **Personal** gitignored for you |
| `CLAUDE.md` (the instructions file) | **Shared**: the whole point of this module |
| `.claude/settings.json` (project settings: permissions, hooks config) | **Shared**: the team runs the same setup |
| `.claude/settings.local.json` (your personal overrides) | **Personal**: gitignored for you |
| `.mcp.json` (the MCP servers the project uses) | **Shared if the project relies on them** |
| `.claude/commands/`, `.claude/agents/`, `.claude/hooks/` | **Shared if the project uses them** |
@@ -162,7 +162,7 @@ tutorials. It's the worked example for everything below.
### Where this is heading: Skills (Module 21)
A committed instructions file is the lightweight foundation. It says *how this project works* in
general always-on context the AI reads every session. When you find yourself wanting to capture a
general: always-on context the AI reads every session. When you find yourself wanting to capture a
*specific repeatable procedure* ("here's exactly how we cut a release," "here's our playbook for
adding a new CLI command"), that's the structured big sibling: **Skills (Module 21)**. Same instinct
(write the knowledge down, commit it, let the AI execute it your way) but packaged as reusable
@@ -202,11 +202,11 @@ editor-integrated AI (Module 4) for the part where the AI obeys the file.
- The `tasks-app` repo from Module 2 (already a Git repo with some history).
- Your agentic coding tool from Module 4, and knowledge of which filename it reads for repo-level
instructions (check its docs see the note in *Key concepts*).
- Optionally, a test command for the AI to honor Python's built-in `python -m unittest` works with
instructions (check its docs; see the note in *Key concepts*).
- Optionally, a test command for the AI to honor; Python's built-in `python -m unittest` works with
nothing to install (you'll write a real suite in Module 13; until then it simply reports no tests).
### Part A Write the instructions file and let the AI commit the config
### Part A: Write the instructions file and let the AI commit the config
1. Look up the instructions filename your tool reads (Claude Code uses `CLAUDE.md`; sub your own).
Open an AI session in the `tasks-app` repo and direct it to create that file from this module's
@@ -214,7 +214,7 @@ editor-integrated AI (Module 4) for the part where the AI obeys the file.
> *"Read `~/ai-workflow-course/modules/05-commit-the-ai-config/lab/instructions-file-starter.md`.
> Create my tool's instructions file at the root of this repo seeded from it, and adjust every line
> so it's accurate for this tasks-app. Don't commit yet I want to review it first."*
> so it's accurate for this tasks-app. Don't commit yet; I want to review it first."*
You're handing the AI the file creation and placement. You keep the judgment over *content*: a
wrong instruction is worse than none.
@@ -243,11 +243,11 @@ editor-integrated AI (Module 4) for the part where the AI obeys the file.
`settings.local.json`, no secrets). This commit is the point of the whole module: the configuration
now travels with the repo.
### Part B Watch the AI obey it
### Part B: Watch the AI obey it
5. Start a **fresh** AI session in your editor (so it picks up the file cleanly) and give it a task
that the instructions constrain. Pick a command your app doesn't have yet (so this is a real
feature, not a re-add) — for example:
feature, not a re-add). For example:
> *"Add a `search <term>` command that lists only the tasks whose title contains `term`. Then
> confirm it works."*
@@ -266,13 +266,13 @@ editor-integrated AI (Module 4) for the part where the AI obeys the file.
Vague instructions get vague compliance; specific, imperative lines ("Never edit `tasks.json` by
hand; it is generated") land far better than soft ones ("try to avoid editing generated files").
### Part C Make a behavior change reviewable
### Part C: Make a behavior change reviewable
8. Now change *how the AI works* and watch it show up as a diff. Direct the AI to add a house-style
rule to the instructions file, say a hard line length:
> *"Add this line to the instructions file under house style: `Keep functions under 20 lines; split
> anything longer.` Don't commit yet I'll review the diff first."*
> anything longer.` Don't commit yet; I'll review the diff first."*
9. Before anything gets committed, read the change exactly as a reviewer would. This is your
verification step, so run it yourself: