AI guardrails for Sui

What this page is for

The other three pages are tool setup — Cursor, Claude Code, Codex. This one is tool-agnostic. It explains why Sui needs stricter AI rules than a typical codebase, and gives you the review bar to hold once an agent starts writing Move on your behalf.

Use it when you are choosing what to trust, not when you are configuring an editor.

Why Sui is different

Most AI coding mistakes are cheap. A wrong React prop shows up immediately; a bad SQL query gets rolled back. Sui programs encode ownership, capabilities, and shared-object concurrency, and once a package is published the mistake is on-chain and permanent. The cost of a wrong guess is asymmetric in a way that most of a model's training data is not.

The failure mode is also specific. Models have seen far more Solidity than Move, so under uncertainty they reach for the chain they know best: contracts as long-lived mutable state, access control as a modifier, tokens as balances in a mapping. Every one of those instincts is wrong on Sui, and each produces code that compiles and reads plausibly.

Two more traps are recent rather than conceptual. JSON-RPC is deprecated, so any tutorial the model absorbed will reach for SuiClient and getFullnodeUrl. And because Move framework APIs move quickly, a model that half-remembers one will invent the rest of it rather than admit it does not know.

What good rules do about it

Standing rules fix this, but only if they are written to a particular shape. Three properties matter.

Point at facts instead of copying them. A rule that says edition = "2024" is a fact with a shelf life, asserted on every single request, that the reader has no way to validate. A rule that says read the nearest Move.toml stays correct forever and gets the right answer per package. The same goes for framework revisions, SDK versions, and source paths.

Flag, do not migrate. "Never use SuiClient" sounds strict, but in a repo that still has some, it reads as an invitation to start rewriting working call sites during an unrelated task. Say instead: default to SuiGrpcClient in new code, and where old clients exist, point them out and propose a migration.

Be additive. An agent told to "create AGENTS.md" in a repo where that path is a symlink to CLAUDE.md will write through the link and destroy the other file. Prefer a new rule file, or an appended section, over any instruction that replaces a file someone already relies on.

The review bar

Rules shape the draft. They do not sign off on it. Before you accept a change to Move code, answer these — and if the agent cannot answer one, treat that as the finding:

Ownership and transfer. Who can take, share, or destroy this object? Are the public and entry surfaces intentional, or did one widen to make something compile?

Capabilities. Are admin and mint caps gated? Could a stranger forge authority, or replay a call that was meant to happen once?

Arithmetic. For anything financial, are you using audited math helpers, and are the overflow and rounding assumptions stated rather than assumed?

Shared objects. Will this object congest under load? Every mutation is a contention point.

Off-chain clients. Do the SDK calls match the package ID and network this repo actually uses? Are error paths honest, or quietly swallowed?

Habits that scale

Keep a short definition of done in the repo — tests required, no secrets in samples — so it applies to humans and agents alike.

Let AI do the scaffolding and keep human sign-off on the auth and money paths. When you are unsure, ask the model to explain the security impact, then verify the explanation against the code rather than believing the story. Confident prose is not evidence.

For contracts that matter, pair sui move test with a Move review skill from Start building → Browse AI prompts, or with a human auditor. A review skill is a much better use of a long prompt than a rule file, because it loads only when you ask for it.

Installing the rules themselves

Press Copy markdown at the top of this page to get a tool-agnostic version: it inventories your repo, proposes the least destructive place to put the rules given whichever agent is reading it, waits for you to agree, and then applies the review bar above to every change it proposes afterwards.

If you already know which tool you are using, the Cursor, Claude Code, and Codex pages carry the same rules with placement instructions specific to that tool.