AI Workshop manifesto
Rules of intelligent communication with AI
Twelve rules that agent work rests on: from a clear task to owning the result. Short, with examples from real work.
1. Clarity before speed
Word the task so a new colleague with no context would get it. A minute on the wording saves an hour of rework.
Don'tMake the sign-up form work properly.DoStream sign-up form: email field, client-side validation, POST /api/events/waitlist, on success show «You're signed up». Style it like the form on /events.2. Context is work, not a luxury
The agent knows only what you gave it. Keep the constant parts — stack, commands, prohibitions — in CLAUDE.md or AGENTS.md; put only what changes in the task.
Don'tRe-explaining in chat every time that we use Next.js and Postgres.DoStack, commands and prohibitions live in CLAUDE.md. In the task: «Similar logic already exists in src/lib/events-store.ts — follow it».3. Define done before you start
Say what makes the work finished. Without a criterion the agent stops wherever it feels like enough.
Don'tFix the sign-up bug.DoDone when tsc is clean, waitlist.spec is green, and signing up twice with the same email creates no duplicate.4. Plan first, code second
If a change touches more than one file, plan first. Editing a plan is cheap; editing code built on a wrong plan is not.
Don'tRewrite the auth. (Then go get coffee.)DoPropose a 5–7 step plan: which files you'll touch and how you'll verify. Code after my «ok».5. Trust, but run it
«Done» is a claim, not a fact. Facts are test output, typecheck, a screenshot, a diff. Don't trust without checking.
Don'tThe agent says it all works — merge.DoShow me the tsc and test output and a screenshot of the page. I'll review the diff before merging.6. Targeted edits, not rerolls
Name the file, the spot and the change. «Redo it all» throws away what already worked and brings new bugs.
Don'tNot that. Start over.DoIn school-chrome.tsx add a «Workshop» item after «Events». Leave everything else as is.7. Honesty both ways
Say what you don't know, and ask for the same: «not sure» beats an invented API. Models hallucinate — give yours permission to doubt.
Don'tJust make it work.DoIf you're not sure about the API, say so and link the docs. Don't guess method names.8. Polite persistence
Calm tone, firm requirement. Instead of emotion — the specific gap between expected and actual.
Don'tYou broke everything again!!!Doauth.spec fails at line 42: expected 401, got 500. Find the cause, don't change the test.9. Least privilege, no secrets in the chat
Give the agent exactly the access the task needs. Keys never go into a prompt or into the repo.
Don'tHere's the production DB key, sort it out.DoThe key is in .env.local, which is gitignored. The agent reads the env variable but never prints its value.10. The agent works inside a harness
A harness — hooks, tests, a sandbox, limits — makes agent mistakes cheap and visible. The more freedom the agent has, the stronger the frame.
Don'tTurning off every confirmation on a work machine with production access.DoA sandbox with no prod access, a command allowlist, a hook that runs the linter after every edit.11. Know when to stop
If the agent is going in circles, stop. Narrow the task, restore context or take the step yourself. The tenth try with the same prompt gives the same result.
Don'tTry again. (For the tenth time.)DoStop. Revert the last edits, list what's already been checked, and propose two hypotheses.12. Responsibility stays with the human
The agent writes the code; the human makes the call and owns the result. Only what you understand goes to production.
Don'tThe AI did it that way.DoI've read the diff and understand every line I'm shipping.
We walk through the rules live
Episode 6 of the AI Workshop goes through all twelve rules on real agent conversations. Wednesday 11 November at 19:00 Moscow time.
Social card
1080×1350 for the feed. For stories, add ?size=story to the card URL.