De-slop: remove every em-dash + banned words across all modules + capstone (#94)
Sync course wiki / sync-wiki (push) Successful in 4s
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:
@@ -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:
|
||||
|
||||
Reference in New Issue
Block a user