The Codex in 5 minutes
The whole doctrine in a nutshell: ten commandments — each first in brief, then in plain terms.
- IDocument for the agent, not for the archive.
Write down knowledge about the project so the next person (or AI) understands it before touching the code — and do it right away, not “someday”. A note written as you go saves hours of guessing; written after the fact, it goes stale anyway.
- IISearch the history before you write a line.
Before you build something from scratch, check whether someone already solved it in the project. Usually there’s a ready snippet, or a reason something works the way it does — a minute of searching is cheaper than a day of reinventing.
- IIIVerify, don’t declare.
Before anyone says “it works”, they have to show it — run it, check it, prove it. “Probably works” doesn’t exist; either there’s proof, or the job isn’t done.
- IVDry-run is the default; --execute is deliberate.
Every tool that changes data first shows the plan — what and how much it will change — and only makes it real after your approval. Like a safety catch: it guards against destroying something with one hasty click.
- VA backup is a rollback mechanism, not caution.
A backup made before every change isn’t over-zealousness — it’s the only way back when something goes wrong. Without it, undoing a mistake is often simply impossible.
- VIProd is sacred — you don’t touch it without “deploy”.
The version real customers use (production) isn’t touched without your explicit “deploy”. Saving changes isn’t the same as publishing them live — those are two separate decisions, and the second one you make deliberately.
- VIIUser data is inviolable.
Your users’ data — accounts, orders, reviews, history — is untouchable. On every database operation we make sure none of it is lost or mixed up, because it’s the company’s asset and the customers’ trust.
- VIIITag every deploy and write what the user gained.
Every live deploy gets a clear, dated marker — so it’s always known exactly what’s running for customers, and you can quickly go back to the previous version. Plus a short note in plain language: what the user gained.
- IXA small, coherent commit; one topic.
Save changes in small batches, each about one thing — a fix separately, a new feature separately. That way it’s easy to see what changed and, if there’s trouble, to undo just one thing, not everything at once.
- XPlan → iterate → review.
First show a plan or a few examples (three, not a hundred), gather feedback, and only then do it at scale. That way you avoid producing hundreds of things you have to throw away — and the product comes out not just working, but pleasant to use.