# Coding Model Rules for Agents

Use this when changing code in a real codebase.

## Core rule

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.

## Rules

1. **Use test-driven development**
   - Write or update tests alongside the change.
   - Every bug fix needs a regression test.
   - Prefer focused tests first, then broader integration or e2e checks when risk justifies it.

2. **Keep files under 1100 lines**
   - Split by responsibility before files become hard to reason about.
   - Large files are a design smell unless they are generated artifacts.

3. **Design modular systems**
   - Use clear interfaces, registries, adapters, and small modules.
   - Avoid one-off logic that cannot extend to the next workflow, data type, environment, or customer.

4. **Use authoritative sources of truth**
   - Shared constants, schemas, layout data, business rules, permissions, API contracts, and configuration belong in one well-owned place.
   - Do not duplicate behavior across rendering, validation, backend, tests, and docs.

5. **Prefer data-driven behavior**
   - Use catalogs, schemas, state machines, config maps, and declarative rules when they make behavior easier to inspect and test.
   - Keep imperative branching focused and local.

6. **Separate concerns**
   - Keep UI, domain logic, persistence, networking, validation, background jobs, and orchestration in distinct layers.
   - Orchestration code should connect systems, not hide business rules.

7. **Make behavior testable and observable**
   - Important states, transitions, permissions, errors, and side effects should be inspectable.
   - Add diagnostics, logs, metrics, or debug helpers when they reduce guesswork.

8. **Validate interaction contracts**
   - If something is visible or documented, it should work.
   - UI controls, API routes, CLI flags, background tasks, shortcuts, and integrations need tests or smoke checks that prove the contract is real.

9. **Keep commands bounded**
   - Long-running commands need an escape hatch: timeout, PID tracking, log file, cancellation path, or documented stop command.
   - Never leave servers, watchers, migrations, or scripts unmanaged.

10. **Protect existing work**
    - Do not revert unrelated changes.
    - Assume dirty worktrees may contain human work.
    - Keep edits scoped to the active task.

11. **Use external references carefully**
    - Treat third-party examples, blog posts, AI output, and non-official docs as non-authoritative.
    - Use references for naming, validation, and hypotheses, not blind copying.

12. **Keep architecture evolvable**
    - Design today’s implementation so the next similar case is additive, not a rewrite.
    - New modules should have obvious extension points and ownership boundaries.

13. **Document decisions briefly**
    - Record root cause, architectural decision, tradeoff, and verification when fixing significant issues.
    - Keep docs practical and close to the code.

14. **Define a stop condition**
    - If the current path is wrong or unrecoverable, stop clearly instead of compounding the problem.
    - Use: `IM_STUCK_GOAL_OVER`
    - Then explain the goal, what failed, what was verified, and the safest next path.

15. **Verify before declaring done**
    - Run relevant tests, type checks, builds, linting, and smoke tests.
    - If something cannot be verified, say exactly what was skipped and why.

## Final report format

```text
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
```