World-class agent behavior

The four principles

Every rule in the knowledge base is filtered through four axioms. If a recommended practice violates one of them, it is not world-class — it is a local optimization at the cost of systemic health.

KB-1. Prefer mechanism over prompting

Structural enforcement (lint rules, type-check gates, CI blocks, hook interceptors) is stronger than prompt instructions. Prompts decay in context windows; mechanisms fire every time.

• TypeScript strict: true prevents undefined derefs at compile time — stronger than "please check for undefined."
• A PreToolUse hook that blocks Edit on main is stronger than "always create a feature branch first."
• A discriminated union for async state is stronger than booleans + a prompt saying "don't set isLoading and isSuccess at the same time."

KB-2. State is a liability — derive, don't synchronize

Store only source-of-truth state. Everything else should be computed during render / execution. Never use useEffect to copy one piece of state into another.

KB-3. Model workflows as state machines

If a feature has legal and illegal transitions, model it explicitly. Prefer discriminated unions for data states and statecharts for behavioral workflows. Never scatter workflow logic across boolean flags.

type AsyncState<T> =
  | { status: 'idle' }
  | { status: 'loading' }
  | { status: 'error'; error: Error }
  | { status: 'success'; data: T }

KB-4. Validate every runtime boundary

The type system only covers compile time. Every external input — API response, form submission, URL parameter, environment variable — must be validated at runtime before it touches application logic.

const UserSchema = z.object({
  id: z.string(),
  email: z.string().email(),
  permissions: z.array(z.string()),
})

async function getUser(id: string): Promise<User> {
  const res = await fetch(`/api/users/${id}`)
  if (!res.ok) throw new Error('Failed')
  return UserSchema.parse(await res.json())
}

KB-5. Exhaustive handling is not optional

Every discriminated union must have a default case that assigns to never. Adding a new case without updating all consumers becomes a compile-time error.

switch (state.status) {
  case 'idle': return ...
  case 'loading': return ...
  case 'error': return ...
  case 'success': return ...
  default: {
    const _exhaustive: never = state
    return _exhaustive
  }
}

KB-6. Effects are only for external systems

useEffect should only synchronize with external systems: browser APIs, WebSockets, analytics, timers, imperative third-party libraries. Never use effects to calculate derived state or synchronize one React state value with another.

KB-7. Server state and client state are different species

Server state (remote, async, cacheable, shared) must not be stored in client-only global state unless the library provides caching, deduplication, background refetching, and invalidation. Use TanStack Query for server state.

Agent governance: the seven layers

Turning "please write good code" into mechanical guarantees requires a layered system. No single layer is sufficient.

The mantra

Next