Engineering standards: say it once, enforce it where it counts
A restaurant kitchen has a few rules on the wall ("wash hands") and a few rules built into the equipment (the oven turns off if the door opens). A wall poster can be forgotten. A built-in lock cannot. Good engineering standards use both, and they know which rule belongs where.
- Anthropic's Claude Code best-practices page splits instructions in two kinds. Guidance (your prompt,
CLAUDE.md, skills) is read by the model, which "usually follows" it but is not forced to. Enforced rules (hooks, permission rules, managed settings, tests, CI) are applied by Claude Code or by your pipeline and do not depend on the model's choice. - The docs' advice: if you keep adding emphasis to a
CLAUDE.mdline and Claude still misses it, the line belongs in a hook. The reverse holds too: if you have hooks for things that are only preferences, delete them and let Claude decide. CLAUDE.mdloads into every session, so each line costs a little attention on every task. Keep it for what Claude cannot work out from the code: the exact test, typecheck and lint commands, decisions that are not in the repo, and gotchas. Personal preferences go inCLAUDE.local.md, which you add to.gitignore.- Claude Code reads settings from several places. The scope decides who a setting affects: user (
~/.claude/settings.json, you in every project), shared project (.claude/settings.json, everyone in the repo if committed), project local (.claude/settings.local.json, you in one project) and managed (set by an organization; nothing in your own files overrides it). - Precedence, highest first: managed settings, command-line
--settings, project local, shared project, user. List settings such aspermissions.allowmerge across files instead of replacing each other. - Some keys never take effect from a file committed in the repo, and some, such as
allowrules, wait until each teammate trusts the folder.denyandaskrules apply right away. Run/statusto see which settings sources are loaded. - Standards are only useful if people can find and use them. Write one short engineering standards file (we call it
ENGINEERING.mdin this course) and link to it fromCLAUDE.md.
| Rule | Guidance or enforced? | Where it lives |
|---|---|---|
| "Use clear names for functions" | Guidance | CLAUDE.md |
"Run python3 -m unittest before you say you are done" | Guidance, plus enforced by a Stop hook and CI | CLAUDE.md, .claude/settings.json, CI |
"Never read .env" | Enforced | permissions.deny rule |
| "Nothing merges without a passing test run and one human approval" | Enforced | Branch protection (Lesson 2) |
"Do not touch the migrations/ folder" | Enforced | PreToolUse hook that exits with code 2 |
- Write down every rule your team follows or wishes it followed, one per line, in plain words.
- For each rule, ask: is "almost always" good enough? If yes, it is guidance. If no, it is a rule that needs enforcement.
- Put guidance in
CLAUDE.md, keeping the file short. Include the exact commands for test, typecheck and lint. - For each enforced rule, choose the mechanism from the table and write it down: a deny rule, a hook, branch protection or CI.
- Create the real files:
.claude/settings.jsonwith your shared rules, committed to the repo, and.claude/settings.local.jsonfor personal overrides, kept out of Git. - Write
ENGINEERING.mdin one page with three sections: how we work, how we review, how we ship. - Run
/statusand check the settings sources look as you expect. - Check: a new teammate can find the test command in under a minute, and you can point to the exact place where each "never" rule is enforced.
Videos by other creators on YouTube, for reference. They are not made by or affiliated with The Future Market.
Read the video script
[Host] "A poster on the wall can be ignored. A lock on the door cannot."
[Text on screen: Guidance vs enforced] "Some rules are guidance, like a note in CLAUDE.md. Some are enforced, like a deny rule or a required check."
[Screen: the rules table] "Ask one question for each rule: is almost always good enough?"
[Text on screen: Keep CLAUDE.md short] "If not, move it out of the notes and into a hook, a permission rule or your pipeline."
[Host] "Short notes, strong locks, and one page everyone can find."
Write your team's rule list (at least ten rules), sort it into guidance and enforced, and create the files that hold each. Then write ENGINEERING.md on one page.
ClaudeStuck? Copy a ready-made prompt for Claude
Copy this, open Claude, paste it, and Claude will walk you through the lesson step by step.
For a grown-up: Claude is for adults (18+). Copy this, paste it into Claude, and use the answer to explain the lesson to your child.
I'm learning "AI Engineering Practice: ship and maintain AI-built software" on The Future Market. Lesson 1: "Engineering standards: say it once, enforce it where it counts". What the lesson teaches: - Anthropic's Claude Code best-practices page splits instructions in two kinds. Guidance (your prompt, CLAUDE.md, skills) is read by the model, which "usually follows" it but is not forced to. Enforced rules (hooks, permission rules, managed settings, tests, CI) are applied by Claude Code or by your pipeline and do not depend on the model's choice. - The docs' advice: if you keep adding emphasis to a CLAUDE.md line and Claude still misses it, the line belongs in a hook. The reverse holds too: if you have hooks for things that are only preferences, delete them and let Claude decide. - CLAUDE.md loads into every session, so each line costs a little attention on every task. Keep it for what Claude cannot work out from the code: the exact test, typecheck and lint commands, decisions that are not in the repo, and gotchas. Personal preferences go in CLAUDE.local.md, which you add to .gitignore. - Claude Code reads settings from several places. The scope decides who a setting affects: user (~/.claude/settings.json, you in every project), shared project (.claude/settings.json, everyone in the repo if committed), project local (.claude/settings.local.json, you in one project) and managed (set by an organization; nothing in your own files overrides it). - Precedence, highest first: managed settings, command-line --settings, project local, shared project, user. List settings such as permissions.allow merge across files instead of replacing each other. - Some keys never take effect from a file committed in the repo, and some, such as allow rules, wait until each teammate trusts the folder. deny and ask rules apply right away. Run /status to see which settings sources are loaded. - Standards are only useful if people can find and use them. Write one short engineering standards file (we call it ENGINEERING.md in this course) and link to it from CLAUDE.md. The exercise I'm working on: Write your team's rule list (at least ten rules), sort it into guidance and enforced, and create the files that hold each. Then write ENGINEERING.md on one page. I'm stuck. Please: 1. Explain the main idea in plain, simple words with one everyday example. 2. Walk me through the exercise one small step at a time. Ask me what I've done so far before giving the next step. 3. Don't just give me the final answer. Help me do it myself, and check my work when I share it.
I'm a parent helping my child (about 8 years old) with a lesson called "Engineering standards: say it once, enforce it where it counts" from the course "AI Engineering Practice: ship and maintain AI-built software".
Here's what the lesson says:
A restaurant kitchen has a few rules on the wall ("wash hands") and a few rules built into the equipment (the oven turns off if the door opens). A wall poster can be forgotten. A built-in lock cannot. Good engineering standards use both, and they know which rule belongs where.
The activity:
Write your team's rule list (at least ten rules), sort it into guidance and enforced, and create the files that hold each. Then write ENGINEERING.md on one page.
Please explain this so an 8-year-old understands: short sentences, a fun everyday example, and no hard words.
Then give me 3 simple questions I can ask my child to check they understood, and a way to do the activity together, one tiny step at a time.Sources
- Anthropic, Best practices for Claude Code: code.claude.com/docs/en/best-practices
- Anthropic, Settings files and precedence: code.claude.com/docs/en/settings
- Anthropic, Configure permissions: code.claude.com/docs/en/permissions
A review pipeline for code you did not write
This lesson is part of full access: every course and every level for one payment.
Tests as gates, and checking the tests themselves
This lesson is part of full access: every course and every level for one payment.
Security checks for AI-assisted code
This lesson is part of full access: every course and every level for one payment.
Claude Code in scripts and CI, with limits
This lesson is part of full access: every course and every level for one payment.
Ship in small steps and keep it maintainable
This lesson is part of full access: every course and every level for one payment.
Lead a small team and document the workflow
This lesson is part of full access: every course and every level for one payment.
Final project
This lesson is part of full access: every course and every level for one payment.
Quiz
What is the difference between guidance and an enforced rule?
Guidance (a prompt or CLAUDE.md) is read by the model, which usually follows it. An enforced rule (a hook, a deny rule, branch protection or CI) is applied by the tool or pipeline whatever the model decides.
Where should a "never read .env" rule live?
In a permissions deny rule (and the sandbox for stronger limits), not only in CLAUDE.md.
Does an AI code review approve or block a pull request?
No. It leaves findings, and the decision to merge stays with people.
Why does Code Review read REVIEW.md from the base branch and not from the pull request?
So a pull request cannot change the rules used to review itself.
What does a CODEOWNERS file do?
It names the people or teams responsible for parts of the code, who are asked to review changes to those files.
What is a mutation check?
Change the code on purpose in a small way and check that a test fails. If the tests still pass, they are too weak.
How do you make a failing test block a merge?
Run the tests in CI and turn on required status checks in branch protection.
Which warning signs should a human reviewer look for in an AI-written diff?
Unexpected files, deleted or weakened tests, tests changed to fit a bug, new dependencies, hard-coded secrets and code nobody can explain.
What does push protection do?
It blocks pushes that contain supported secrets before they reach the repository.
Name three limits you set on an unattended Claude Code run.
For example a short allowed-tools list, dontAsk permission mode, a turn or budget cap, and a workflow timeout.
Why use --bare in scripts and CI?
It skips auto-discovered hooks, plugins, MCP servers and CLAUDE.md, so the run does the same thing on every machine.
How do you undo a shipped commit and keep the history?
Use git revert, which makes a new commit that undoes the earlier one.
Final exam
This lesson is part of full access: every course and every level for one payment.
Certificate
This lesson is part of full access: every course and every level for one payment.