Coding Model Rules With Applied Research

A companion field guide for agents that have web search: save research to disk, keep it searchable, and apply it directly to the build instead of leaving it behind in disposable tool output.

By Eric Rhea Updated: Jun 27, 2026 Status: Agent field guide

This guide extends the coding model with a research loop designed to fix three recurring failures: agents skip web research, agents do research without saving it, and agents save research without using it.

Use this guide when outside knowledge can change the build

The short version

If web search exists, treat research as a project artifact. Check what the repo already knows, search only what matters, save it in a small structured note, and let that note change the code, tests, or architecture.

Borrow the useful part of the Agent Skills spec

Use front matter first, keep documents focused, and structure files for progressive disclosure. The goal is not to turn every repo into a skill package. The goal is to make research easy for agents to discover, load, and apply. The underlying influence is the Agent Skills specification.

Rule 16: research is part of the implementation

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, the agent should search existing project research before making assumptions and use targeted web research before acting on uncertainty. Save the result under research/, keep the note under 200 lines, include the original URL in source_url, and apply the finding to code, tests, configuration, or decision records.

  • Research is not chat exhaust. Tool output disappears. Project knowledge should not.
  • Research must be discoverable. If another agent cannot find it with a fast local search, it is effectively gone.
  • Research must be applied. A saved note that never changes the project is only partial work.

Use the applied research loop

  • 1. Check localSearch the manifest first

    Look in research/INDEX.md, then search front matter and headings in research/ before opening the web.

  • 2. Search targetedOnly research uncertainty that matters

    Search when current external knowledge can change correctness, compatibility, security, limits, or design choices.

  • 3. Save itWrite or update a focused note

    Each note gets YAML front matter, the original URL, a narrow topic, and a hard 200-line cap.

  • 4. Apply itChange the build because of the finding

    Turn the research into code, config, tests, architectural decisions, or explicit non-adoption rationale.

  • 5. Link itKeep the research index current

    Add or refresh the entry in research/INDEX.md so future agents can discover the note fast.

  • 6. Verify itProve the applied change

    Run the narrowest checks that show the research-backed change actually works.

Repository contract for the research folder

research/ is the home

Keep saved outside research at repo root so it is easy to find and does not disappear into temp directories or chat transcripts.

research/INDEX.md is the manifest

Agents should search it first. One line or one small block per note is enough as long as path, slug, scope, and status are easy to find.

200 lines max per note

Small notes load faster, search better, and force topic boundaries. Split oversized notes by question, source, or decision boundary.

Original URL is mandatory

Put the source in source_url so future agents can re-open the original context and verify drift.

Front matter comes first

Structured metadata should be at the top of the file so simple scripts and rg can locate notes without a custom toolchain.

One focused topic per note

Do not collapse ten articles, five APIs, and three decisions into one mega document. Focus keeps retrieval cheap and reuse obvious.

Research note shape

The note format should be lightweight, stable, and ripgrep-friendly. Required metadata should tell an agent what the note is, where it came from, when it was retrieved, and what part of the project it should influence.

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

# Summary
- What the source says in a few bullets.

# Key Facts
- Concrete versions, limits, flags, defaults, or behaviors.

# Applied Implications
- What should change in the codebase because of this note.
- Affected files or modules:
- Tests or checks to add:

# Open Questions
- What still needs confirmation.

Required fields

title, slug, source_url, source_domain, retrieved_at, status, applies_to, keywords, and confidence are enough for fast filtering without a heavy indexing system.

Keep the research cheap to find

The best local research system is the one every agent can use without negotiation. That means plain Markdown, predictable headings, and metadata simple enough for shell or Python.

  • Search metadata 
    rg -n "^slug:|^source_url:|^applies_to:|^keywords:" research/
  • Search note sections 
    rg -n "^# (Summary|Key Facts|Applied Implications|Open Questions)" research/
  • Search by topic 
    rg -n "oauth|rate limit|sdk version|pagination" research/
  • Search the manifest 
    rg -n "slug:|path:|applies_to:|status:" research/INDEX.md

Turn saved research into construction

  • Dependency behaviorDocs reveal a version boundary

    Pin the supported version, update adapter code, and add a regression test that proves the constraint holds.

  • API contractReference docs clarify pagination or auth

    Change request handling, fixtures, and error-path tests so the implementation matches the real contract.

  • SecurityAdvisory or vendor note changes risk posture

    Tighten defaults, add validation, and record the source of the change in the applied implications section.

  • PerformanceLimits or quotas shape the design

    Adjust batching, retry logic, or timeouts and then verify the new behavior with narrow checks.

Applied means visible

When research affects the build, the resulting change should be inspectable in code, tests, configuration, or a brief design note. Otherwise the note is just archived context.

Manifest pattern for research/INDEX.md

# Research Index

- slug: oauth-refresh-token-rotation
  path: research/oauth-refresh-token-rotation.md
  applies_to: auth, integrations
  source_domain: example.com
  retrieved_at: 2026-06-27
  status: active

- slug: api-pagination-rules
  path: research/api-pagination-rules.md
  applies_to: api, client
  source_domain: docs.example.com
  retrieved_at: 2026-06-27
  status: active

This does not need a database. It needs a stable first stop that any agent can search before paying the web-cost again.

Bottom line

Web search only becomes durable leverage when the result is written into the repository, kept small enough to load cheaply, and turned into a concrete change in the project. Good agents do not just look things up. They convert outside knowledge into reusable project memory.