Coding Model Guide for Agents

A compact operating guide for AI coding agents: protect the codebase, make changes testable, keep systems modular, and verify before claiming done.

By Eric Rhea Updated: May 14, 2026 Status: Agent field guide

This guide translates Eric's coding model rules into a field manual agents can follow while changing real codebases.

Use this guide when you are coding

The short version

Make the smallest safe change that improves the system, prove it with tests or checks, and leave the codebase easier for the next agent to extend.

Download the concise rules

Need the portable version for an agent prompt, repo doc, or coding model context file?

Download the concise Markdown rules →

  • 1) Understand the contract: Identify the visible behavior, API, CLI flag, UI control, background job, or integration that must keep working.
  • 2) Add the proof first: Write or update a focused test before changing behavior whenever possible. Bug fixes need regression tests.
  • 3) Change the owned layer: Put the rule in its source of truth, not in three duplicated branches scattered through rendering, validation, docs, and tests.
  • 4) Keep the system evolvable: Prefer interfaces, adapters, registries, schemas, and small modules over one-off logic.
  • 5) Verify and report honestly: Run the relevant tests, type checks, builds, linting, and smoke tests. If something was skipped, say why.

Non-negotiables

  1. Use test-driven development. Write or update tests with the change. Every bug fix gets a regression test.
  2. Keep files under 1100 lines. Split by responsibility before a file becomes too large to reason about.
  3. Protect existing work. Do not revert unrelated changes. Assume dirty worktrees may contain human work.
  4. Keep commands bounded. Long-running servers, migrations, watchers, and scripts need timeout, PID tracking, cancellation, or a documented stop command.
  5. Verify before declaring done. Passing checks are part of the deliverable, not a nice extra.

Design the change so the next case is additive

  • Modular systems Build around clear interfaces, registries, adapters, and small modules. Avoid one-off branches that only solve today's exact case.
  • Authoritative sources of truth Shared constants, schemas, permissions, layout data, API contracts, and business rules should live in one well-owned place.
  • Data-driven behavior Use catalogs, schemas, config maps, state machines, and declarative rules when they make behavior easier to inspect and test.
  • Separated concerns Keep UI, domain logic, persistence, networking, validation, jobs, and orchestration in distinct layers.

Make behavior observable

Important states, transitions, permissions, errors, and side effects should be inspectable. Add diagnostics, logs, metrics, or debug helpers when they reduce guesswork.

Agent check

If a future agent cannot tell whether the workflow is healthy, the implementation is not observable enough yet.

Validate every interaction contract

  • If a UI control is visible, test that it works.
  • If an API route is documented, prove the request and response shape.
  • If a CLI flag exists, test that the flag is accepted and changes behavior.
  • If a background task is scheduled, prove it can run, fail visibly, and be stopped or retried.
  • If an integration is promised, smoke-test the integration path or clearly mark it unverified.

Use references carefully

Third-party projects, blog posts, examples, and AI output are hypotheses, not authority. Official dependency docs can be authoritative; everything else is only a clue for naming, validation, and possible approaches.

Stop conditions

If the current path is wrong, risky, or unrecoverable, stop cleanly instead of compounding the problem.

Use the stop phrase when needed

IM_STUCK_GOAL_OVER

Then explain the goal, what failed, what was verified, and the safest next path.

Final report format

Changed:
- What files/modules changed and why

Protected:
- What unrelated work was avoided or left untouched

Verified:
- Tests, type checks, builds, linting, smoke tests, or manual checks run

Skipped:
- Anything not verified, with the exact reason

Next:
- The smallest useful follow-up, if any

Bottom line

Good coding agents do not just make code appear. They preserve intent, reduce duplication, keep architecture legible, and leave evidence that the system still works.