Skip to main content
A coding-agent field guide is a small, project-specific collection of lessons derived from reviewed work. Each lesson records a mistake or surprise, the accepted behavior, the evidence behind it, where it applies, and how to verify it. Agents read a short index, then open only the entries relevant to the current task. This keeps repeated corrections available without adding every lesson to AGENTS.md, a memory file, or the prompt for every session. Use the open-source coding-agent field guide starter to add this workflow to any repository. It works with Codex, Claude Code, Cursor, other coding agents, pull-request review, and human-only review. Totman turns one reviewed correction into a verified field-guide lesson linked to its source evidence.

​
What belongs in a field guide

A field-guide entry should come from an observed project case. It needs:
  • a commit, pull request, issue, test, contract, decision, or other inspectable source;
  • the project-specific behavior that surprised the reviewer;
  • guidance narrow enough to apply without becoming a universal rule;
  • a good example and a bad example with different behavior;
  • a verification method;
  • exceptions and applicable scope;
  • a human decision before the entry becomes active.
Most review comments should not become entries. Fix the current task and stop unless the correction is likely to recur or protects a consequential project boundary.

​
How it differs from other agent context

The field guide does not replace these artifacts. Its root instruction is usually a short pointer:
The index says what each entry is for and where it applies. The entry contains the evidence and detail. An agent working on a responsive header should not load a lesson about asynchronous job persistence.

​
Turn reviewed work into one lesson

Use this sequence after the work has reached an accepted result:
  1. State the correction in one sentence.
  2. Confirm that it is project-specific and likely to matter again.
  3. Search the current index for a duplicate or conflict.
  4. Check current code, tests, contracts, and decisions.
  5. Decide whether the lesson belongs in the guide or in a stronger artifact.
  6. Draft the smallest guidance that explains the behavior and consequence.
  7. Add evidence, scope, examples, verification, and exceptions.
  8. Leave the entry as a draft.
  9. Have a person accept, revise, reject, merge, or graduate it.
  10. Add only accepted entries to the active index.
The distillation workflow provides the copyable version.

​
Graduate enforceable lessons

Some corrections should not remain advisory Markdown. Graduate a lesson when a stronger artifact can enforce or explain it: A superseded field-guide entry can remain as a short lifecycle example that points to the stronger artifact. Future agents should follow the test, type, contract, or current code rather than treating the historical entry as the authority.

​
Keep deterministic checks separate from judgment

Tests, builds, type checks, lint, and contract checks answer different questions from a review rubric. A required failing check must block acceptance. A high rubric rating cannot offset it. Use anchored judgment dimensions for qualities such as scope, evidence, risk, correctness, test quality, and failure behavior, then state why each rating applies. The repository includes exercised plan-review and code-review rubrics. Their evaluation fixtures show adequate and inadequate work for the same bounded cases.

​
A public Plannotator example

The repository applies the method to three public Plannotator OSS changes:
  • feedback copied back to an agent must preserve whether the person reviewed a plan, file, or message;
  • a long-running Guided Review result must remain attached to the pull request or worktree where it started;
  • a Windows cross-drive path returned by path.relative() must not be treated as repository-relative.
The third lesson graduated into a shared helper and regression test. The worked example links each claim to its public issue, pull request, commit, and tests. Plannotator is the example, not a dependency. Feedback from another review surface can enter the same workflow.

​
Start in five minutes

  1. Copy the repository’s starter/field-guide directory into your project.
  2. Add the AGENTS.md fragment to your repository instructions.
  3. Copy the two workflows and the rubrics your team will use.
  4. Keep the index short.
  5. Add no active entry until a person verifies its evidence, scope, and exceptions.
The starter uses Markdown and one small YAML source manifest in the worked example. It has no CLI, database, vector search, hosted memory service, or vendor-specific runtime.

​
Using Plannotator feedback

Plannotator OSS lets a person review plans, documents, local changes, pull requests, and merge requests, then return comments to the coding agent. That returned feedback can be one input to the distillation step. Use the final accepted change and current project sources as evidence. Do not publish raw conversations, private code, credentials, customer information, or comments that a public source cannot support.

​
Sources and limits

The method combines several documented practices:
  • Cursor described an experimental Field Guide used by an agent swarm, including a short injected index and records of surprising encounters. (Cursor)
  • ThePrimeagen described recording human corrections in Markdown with commit references and having agents retrieve relevant lessons. His thread does not say that he uses Plannotator. (Thread)
  • Anthropic recommends lightweight repository instructions, progressive disclosure, rich references, deterministic checks, and independent verification. (Context engineering, verification loops)
  • OpenAI and Google document task-specific evaluation, deterministic checks, human judgment, model graders, and grader-gaming risks. (OpenAI, Google)
Saving a lesson changes the context available to a future agent. It does not train or fine-tune the model. A field guide can also become stale, reward its own wording, or retrieve an irrelevant lesson. Keep current project sources authoritative, record disagreements, and audit the guide after material project changes.

​
Frequently asked questions

​
Is a field guide the same as agent memory?

No. Memory may preserve facts, preferences, or session state. A field guide contains reviewed project lessons with evidence, scope, verification, and explicit status.

​
Should a field guide replace AGENTS.md?

No. Keep hard constraints, required commands, and a pointer in AGENTS.md. Put detailed lessons behind the field-guide index so agents can load them only when relevant.

​
Should every review comment become an entry?

No. Most comments should fix only the current task. Preserve a lesson when it is likely to recur, protects a consequential boundary, and cannot be enforced more clearly elsewhere.

​
Can an agent create entries automatically?

An agent can draft an entry from reviewed work and durable sources. A person should decide whether to accept, revise, reject, merge, or graduate it.

​
Does a field guide improve the model?

It changes the model’s task context. It does not prove that the model itself improved. Measure repeated corrections, relevant and irrelevant retrievals, context cost, and maintenance time before claiming that the workflow helped.
Last modified on July 27, 2026