# Coding Model Rules With Applied Research

Use this when changing code in a real codebase and web research is available.

## Core rule

Make the smallest safe change that improves the system, prove it with tests or checks, and when outside knowledge matters, turn research into saved project context the next agent can actually reuse.

## 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.

16. **Use web research as a saved project input**
    - If a web-search tool exists and outside knowledge can affect correctness, architecture, dependency usage, API behavior, security posture, or implementation tradeoffs, search existing project research before making assumptions and use targeted web research before acting on uncertainty.
    - Save or update the result under `research/` as a focused Markdown note with YAML front matter, the original URL in `source_url`, and a hard 200-line limit.
    - Keep every note easy to search with `rg` and easy to parse with lightweight shell or Python scripts. Maintain a `research/INDEX.md` manifest so agents can discover saved research before going back to the web.
    - Apply the finding to implementation, tests, architecture, or decision notes. Research that is not used, ruled out, or tracked forward is unfinished.

## Research note minimum shape

```yaml
---
title: OAuth refresh token rotation requirements
slug: oauth-refresh-token-rotation
source_url: https://example.com/docs/oauth/refresh-tokens
source_domain: example.com
retrieved_at: 2026-06-27
status: active
applies_to:
  - auth
  - integrations
keywords:
  - oauth
  - refresh-token
confidence: medium
---
```

```text
# Summary
# Key Facts
# Applied Implications
# Open Questions
```

Split any note that grows past 200 lines by question, source, or decision boundary.

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