ai-workflow-course/modules/05-commit-the-ai-config/README.md

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 same setup instead of each of you hand-tuning your own and quietly drifting apart.

---

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 one more thing worth committing.
• 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.

---

Learning objectives

By the end of this module you can:

1. Identify the repo-level instructions file your agentic tool reads, and explain what belongs in it.
2. Write an instructions file for a real project — conventions, build/test commands, coding standards, off-limits files, house style — that an AI will actually act on.
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 arrives as a diff, like any other change.

---

Key concepts

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 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 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," "the tests are pytest, run them before you say you're done," "don't touch the generated tasks.json." You say it, the AI complies, the session ends, the memory evaporates (Module 1's second seam), and tomorrow you say it all again. The instructions file is where that knowledge stops being something you retype and becomes something the project carries.

What goes in it

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 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 python cli.py <command>. Run tests with pytest. 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. "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, 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 small. Match the existing style; don't reformat files you're not changing. Prefer clarity over cleverness."

The test of a good line: would you otherwise have to say it again next session? If yes, it belongs in the file. If the AI already gets it right without being told, leave it out — bloat dilutes the 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 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.

Picture a two-person project with no committed instructions file. You've trained your local setup to run pytest and avoid tasks.json. Your teammate's setup hasn't — their agent reformats whole files and hand-edits the generated JSON. You're both "using AI on the same repo," but you're getting different behavior, and neither of you can see the other's configuration. That's drift: the same codebase, diverging because the rules live in two heads instead of one file.

Commit the file and that collapses. The configuration is now part of the repo. Clone the repo, get the rules. A new teammate — or a brand-new agent that's never seen the project — is configured correctly on the first run, because the setup travels with the code instead of with whoever set it up. This is the same move as Module 2's "the repo is durable memory the AI can read," aimed one level up: not just the code's history, but the instructions for working on it.

The real unlock: AI behavior becomes reviewable

Here's the part that makes this more than a convenience. Once the instructions live in the repo, a change to how the AI works on this project is a change to a tracked file — so it shows up exactly like a code change does:

git diff

When someone tightens "keep functions small" into "no function over 30 lines," or adds infra/ to the don't-touch list, that decision arrives as a diff you can read, question, and accept or reject. It's no longer an invisible tweak in one person's settings that silently changes what the AI does for everyone. The way your team works with AI becomes a reviewable artifact with a history — you can git log it and see why a rule exists and when it was added.

The full version of this lands in Module 10, where that diff becomes a pull request someone actually reviews before it merges, and Module 8, where a shared remote means the file reaches the whole team. You don't have those yet — so for now the payoff is local: the file is committed, the behavior is recorded, and git diff already shows changes to it as plainly as changes to any code. The habit starts now; the team-scale payoff arrives on schedule.

This course commits its own

You don't have to take this on faith — this repo does exactly what the module teaches. At the root of The Workflow is an AGENTS.md file: the committed instructions for the agents that help author the course. It states what the repo is, the core promises (model-agnostic, GitHub-as-default-not- requirement, the load-bearing dependency chain), the voice, the lab conventions, and a flat "Don't" list. Open it:

git show HEAD:AGENTS.md      # or just open AGENTS.md in your editor
git log --oneline AGENTS.md  # its history — every change to how agents work on this repo

That file is why every module in this course sounds like one course instead of twenty-seven 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 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 playbooks instead of a single always-on briefing. Start with the instructions file; graduate to skills when a procedure earns its own page.

---

The AI angle

This is the course thesis applied to your own configuration. The model is the cheap, swappable part; the setup you build around it is the durable artifact. When you swap models next quarter — and you will — your committed instructions file carries over unchanged. The new model reads the same conventions, the same test command, the same don't-touch list, and behaves consistently on day one. You configured the project, not the model.

Three things make this specifically an AI problem, not a generic config chore:

• AI has no memory across sessions, but it reads files. A committed instructions file is the cleanest way to give an ephemeral agent durable, project-specific context — written once, read every session, by every model.
• AI is confidently inconsistent without a spec. Unprompted, it'll pick a test runner, a formatting style, a place to put new code — and pick differently next time. The instructions file is how you make "the way we do it here" the default instead of a coin flip.
• AI behavior is otherwise invisible. A teammate's hand-tuned local rules silently change what the AI does. Committing the rules drags that into the open where it can be reviewed — which is the whole reason this audience trusts version control in the first place.

---

Hands-on lab

Lab language: shell + markdown, on the tasks-app project from Modules 1–2. You'll use your editor-integrated AI (Module 4) for the part where the AI obeys the file.

You'll need:

• 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 pytest (pip install pytest) so the AI has a real test command to honor.

Part A — Write the instructions file

1. Look up the instructions filename your tool reads. Copy this module's starter, lab/instructions-file-starter.md, to that filename at the root of your tasks-app repo. (If your tool reads several names, copy it to each, or symlink them.)

   cd ~/workflow-course/tasks-app
   # replace <YOUR_TOOL_FILE> with the name your tool actually reads:
   cp /path/to/modules/05-commit-the-ai-config/lab/instructions-file-starter.md <YOUR_TOOL_FILE>
   

2. Open it in your editor and make it true for your project. The starter is filled in for the tasks-app, but read every line and confirm it matches reality — wrong instructions are worse than none. At minimum, set the real test command (or delete the line if you didn't install pytest).

3. Commit it. This is the point of the whole module:

   git add <YOUR_TOOL_FILE>
   git commit -m "Add committed AI instructions for tasks-app"
   

   The configuration now travels with the repo.

Part B — Watch the AI obey it

4. 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:

   "Add a search <term> command that lists only the tasks whose title contains term. Then confirm it works."

5. Watch for the file taking effect. A correctly-configured agent should, without you saying any of it this time:

   • put the logic where your conventions said it goes (core in tasks.py, CLI wiring in cli.py);
   • not hand-edit tasks.json (you marked it off-limits);
   • use the standard library only (no surprise pip install);
   • run your stated test/run command before declaring success, instead of inventing one.

   You're checking that behavior you'd normally have to dictate every session now happens by default. That delta is the file working.

6. If it ignored a rule, that's signal too — tighten the wording, commit the change, and try again. 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

7. Now change how the AI works and watch it show up as a diff. Add a house-style rule to the file — say, a hard line length:

   Add to the instructions file: Keep functions under 20 lines; split anything longer.

8. Before committing, read the change exactly as a reviewer would:

   git diff
   

   That diff is the change to your AI workflow — readable, attributable, revertable. Commit it:

   git add <YOUR_TOOL_FILE>
   git commit -m "Require functions under 20 lines"
   

9. Look at the history of just this file:

   git log --oneline <YOUR_TOOL_FILE>
   

   Every line is a decision about how the AI behaves on this project — recorded, not lost in someone's local settings. (In Module 8 this file reaches your whole team via a remote; in Module 10 that diff becomes a PR someone reviews before it lands. The habit you just built is what those modules turn into a team workflow.)

---

Where it breaks

Be honest about what a committed instructions file does and doesn't buy you:

• It's guidance, not a guarantee. The file biases the model strongly; it does not bind it. An AI can still ignore a line, especially a vague one, especially deep in a long session. The enforcement that can't be ignored — tests that fail the build, scans that block a merge — is CI (Module 14) and security scanning (Module 15). The instructions file reduces how often the AI goes wrong; it doesn't replace the gates that catch it when it does.
• Bloat kills it. A 300-line instructions file is read the way you read a 300-line terms-of- service: not really. Every line you add dilutes the rest. Keep it to what actually changes behavior, and prune lines the model already honors without being told.
• Stale instructions are worse than none. A file that says "tests are pytest" after you've moved to something else will actively misdirect the AI. The file is code-adjacent — it has to be maintained like code, and reviewed like code. That's exactly why committing it (so changes are visible) matters.
• The team payoff isn't here yet. On a solo local repo, the "no more drift between teammates" argument is theoretical — there's only you. The full value lands with a shared remote (Module 8) and review (Module 10). What you get now is the habit and the local history; don't oversell the team benefit until the team can actually pull the file.
• It is not a security control. Telling an agent "don't touch secrets.env" is a convention, not a permission boundary — a sufficiently confused or adversarial agent can still read or write it. Real isolation and least-privilege for agents come later (Modules 16 and 22). The instructions file expresses intent; it doesn't enforce it.

---

Check for understanding

You're done when:

• Your tasks-app repo has a committed instructions file at the root, filled in to match the actual project, and git log shows the commit that added it.
• You've watched a fresh AI session honor a rule from the file — placing code where your conventions said, respecting the don't-touch list, or running your stated test command — without you saying it that session.
• You've changed a behavior rule, read the change with git diff, and committed it — so a change to how the AI works is now a reviewable diff with a history.
• You can explain, in one sentence, why committing the file beats each teammate hand-tuning their own setup: the configuration travels with the repo, so nobody drifts.

When the AI behaves like it already knows your project the moment you open it — and you didn't say a word this session — the file is doing its job. Module 6 takes the safety net further: branches, so the AI can try something wild in a sandbox you can throw away.