Twenty, for the AI era
Best Practices
Every practice here carries three things: the sources it rests on, a file you can install into your repository, and a check that tells you whether it is actually in force. A practice with no artifact is a blog post; a practice with no check is an opinion.
- practices
- 20
- vetted sources
- 93
- automated checks
- 26
- made worse by agents
- 14
npx klay practices auditScores this repository against all twenty. Reads your files and your git log, runs nothing, sends nothing anywhere.
Working with coding agents
Set the boundaries once, in files, so you are not re-negotiating them with a model every session.
One rules file your agent actually reads
Keep your agent's rules in one short, imperative AGENTS.md at the repo root.agent-amplifiedMake the agent show its plan first
Require the agent to state its plan and the files it will touch before it edits any of them.agent-amplifiedCap what one agent run may change
Bound each agent run to a diff you could review by hand in ten minutes.agent-amplifiedNever give an agent your ambient credentials
Give an agent a scoped, expiring credential or a sandbox — never the environment you develop in.agent-amplified
Proving it works
Make the thing that would tell you it broke run automatically, especially for the parts that are not deterministic.
Put an eval in CI, not in your head
Give every LLM feature a golden set that runs in CI and fails the build.agent-amplifiedPin the model like any other dependency
Pin exact model identifiers in code and change them deliberately, never by alias.agent-amplifiedTest the failure, not the happy path
Write the test for the timeout, the refusal and the malformed response before the one that passes.Never let a failure look like an empty result
Make 'nothing found' and 'the call failed' different values, and never collapse one into the other.
Review in the AI era
Keep a human accountable for code no human wrote.
Keep pull requests small enough to review
Keep a pull request to one decision and roughly 400 changed lines.agent-amplifiedAI review is a second reader, never the reviewer
Let an AI reviewer comment first, and never let it be the only approval on a change.agent-amplifiedPut a named human on the dangerous paths
Require a named owner's review on the paths that handle money, auth and migrations.Read the diff, not the summary of the diff
Read the actual diff before you merge it: the summary is a claim, the diff is the fact.agent-amplified
Blast radius
Assume something will go wrong and decide now how far it gets.
Keep secrets out of the repository, permanently
Never commit a secret, and scan every push for one — a leaked key is leaked forever.agent-amplifiedMake every write safe to retry
Give every write an idempotency key so a retry has the same effect as one call.agent-amplifiedNever edit a migration that has already run
Treat a shipped migration as immutable: fix it with a new one, never by editing it.Have an undo you have actually run
Make every deploy reversible, and rehearse the rollback before you need it.
The repo as an interface
Your repository is read by new teammates and by agents on identical terms. Make it answerable without you.
A README whose commands actually work
Make the README's setup commands work verbatim on a clean clone, and check that they still do.agent-amplifiedCommit the lockfile and let a bot bump it
Commit your lockfile, and let an automated bot propose upgrades as reviewable pull requests.agent-amplifiedOne documented home for every setting
Keep configuration in the environment, and document every variable in a committed example file.Record the decision, not the mechanism
When you make a decision that was not obvious, write down why — the code already says what.agent-amplified
