Article 10 of 12 · ARTHA Craft
Every problem in this series had the same root cause. Not a bad model. A missing rule.
Every problem I have described in this series, the re-built features, the cross-layer breakage, the lost decisions, the UI nobody could use, the production crisis, the codebase full of 80% complete work, had the same root cause.
Not a bad AI agent. Not a bad model. Not a bad tool.
A missing rule.
"An agent that hasn't read the brief will invent one. Always."
The first obligation of every coding session is reading, not building. Context seed, current state, session bridge, step sequence, task file. In that order. Before a single line of code. An agent that skips this step makes assumptions. Those assumptions are always expensive.
Prevents: invented context"Go-ahead means execute, not design. If questions remain, go-ahead hasn't been earned."
Go-ahead is a confirmation: every gap resolved, every decision locked, every question answered. If anything remains open, the planning session continues. An agent that receives a go-ahead with open questions will answer them itself. Confidently. Wrongly.
Prevents: agent-invented design decisions"Two features in one task file is the first domino. Scope creep starts here and nowhere else."
One task file. One feature. One step ID. One scope boundary. The moment two unrelated features share a file, the scope boundary becomes ambiguous and the coding agent has no clean definition of done. It builds until it runs out of obvious things to build, which is not done.
Prevents: scope drift"Old code doesn't get deleted. It gets marked deprecated. Deleted code has a habit of being needed tomorrow."
Nothing is ever deleted from the codebase. Old implementations are marked deprecated and preserved. The agent that deletes things it thinks are no longer needed will eventually delete something that is needed: by a module it didn't know existed, by a future step that assumed the old code was still there.
Prevents: silent dependency breakage"If the docs don't reflect the code, the docs are fiction. Fiction is expensive."
Every step that changes a file path, API route, module behaviour, or configuration key: the relevant documentation is updated in the same commit. Not later. Not in a follow-up. The same commit. The moment documentation falls behind the code, it starts actively misleading every agent and every developer who reads it.
Prevents: documentation drift"The handoff is the last file touched. Not almost last. Last. No exceptions."
Before any session closes, CONTEXT-HANDOFF.MD is written. Exact stop point. Locked decisions. Open questions. Paste-ready prompt. A session that closes without a handoff has made the next session harder. A project without handoffs is one developer departure away from a production crisis. This rule exists because that crisis is real.
Prevents: blank-slate sessions and production crises"If it's not in the step sequence, it hasn't been planned. Wanting to build something is not the same as planning to build it."
The step sequence is the single source of truth. If a feature has no step ID, it does not exist as a plan. It exists as a wish. Wishes do not get built correctly. Plans do. Add it to the sequence first, give it a task file, then build it.
Prevents: unplanned work entering the codebase"The agent builds the mockup. The architect approves it. Then the code is written. Never the other way."
UI decisions made during coding are shaped by implementation logic, not user experience. The mockup is the checkpoint. The agent builds it. The architect reviews it. Changes happen before a single line of implementation code exists. This one rule eliminated an entire category of rework from every project I have run since.
Prevents: technically correct but unusable UI"A bug fixed before it's logged is a bug that never officially existed. Unofficial fixes create official mysteries."
Every bug goes into BUGS.MD before it gets fixed. The entry takes thirty seconds. The triage it enables saves hours. The traceable history it creates saves days when the same bug reappears. A bug fixed without being logged cannot be tracked, triaged, or learned from. It becomes a gap in the record, and gaps compound.
Prevents: untraceable recurring bugs"Frozen modules stay frozen. No agent reopens them without explicit product approval. Confidence is not go-ahead."
Some modules are intentionally stubbed. Some features are deliberately deferred. Some decisions are frozen by product direction, not engineering preference. The agent that reopens a frozen module because it seems logical has made a product decision it was not authorised to make. Confidently. Without knowing why the freeze existed.
Prevents: unauthorised product decisionsThe Rule Beneath the Rules
Every one of these ten exists because of something that broke without it. None of them is theoretical. Each one is the scar tissue of a real session, a real project, a real failure that was expensive enough to become permanent.
Rules are not the enemy of speed. Rules are what makes speed safe. [2]
An AI agent with no rules is fast in any direction, including the wrong one.
An AI agent with these ten rules is fast in exactly the right direction. Precise. Bounded. Trustworthy. That is what 25 years of architecture, combined with the most capable coding tools ever built, actually produces.