> ## Documentation Index
> Fetch the complete documentation index at: https://docs.plannotator.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# What Is a Coding-Agent Field Guide?
> A coding-agent field guide turns repeated review corrections into evidence-backed project lessons that agents load only for relevant work.
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](https://github.com/plannotator/coding-agent-field-guide) to add this workflow to any repository. It works with Codex, Claude Code, Cursor, other coding agents, pull-request review, and human-only review.
## 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
| Artifact | What it should contain |
| -------------------------- | -------------------------------------------------------- |
| `AGENTS.md` or `CLAUDE.md` | Small, always-loaded commands, constraints, and pointers |
| Memory | Persisted facts, preferences, or session state |
| Skill | A repeatable workflow, sometimes with scripts or tools |
| Runbook | An operational procedure |
| Retrospective | Analysis of one event |
| Conversation archive | Raw history for replay or audit |
| Field guide | Reviewed project lessons loaded only when relevant |
The field guide does not replace these artifacts. Its root instruction is usually a short pointer:
```md theme={null}
## Project field guide
Use `field-guide/index.md` to find project-specific lessons derived from
reviewed work. Read only entries relevant to the current task.
Treat current code, tests, contracts, and accepted decisions as authoritative
when they conflict with the guide.
```
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](https://github.com/plannotator/coding-agent-field-guide/blob/main/starter/workflows/distill-reviewed-session.md) 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:
| Lesson | Stronger destination |
| --------------------------------------------- | --------------------------- |
| A path form must always be rejected | Test and shared predicate |
| Generated code must satisfy a mechanical rule | Linter or formatter |
| A value can occupy only valid states | Type or schema |
| Every change must pass the same command | CI check |
| A task follows a repeatable procedure | Skill or runbook |
| A behavior is part of the product contract | Contract or decision record |
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](https://github.com/plannotator/coding-agent-field-guide/blob/main/starter/rubrics/plan-review.md) and [code-review](https://github.com/plannotator/coding-agent-field-guide/blob/main/starter/rubrics/code-review.md) 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](https://github.com/plannotator/coding-agent-field-guide/tree/main/examples/backnotprop-plannotator) 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`](https://github.com/plannotator/coding-agent-field-guide/tree/main/starter/field-guide) directory into your project.
2. Add the [`AGENTS.md` fragment](https://github.com/plannotator/coding-agent-field-guide/blob/main/starter/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](https://github.com/backnotprop/plannotator) 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](https://cursor.com/blog/agent-swarm-model-economics))
* 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](https://x.com/ThePrimeagen/status/2081066227619836308?s=20))
* Anthropic recommends lightweight repository instructions, progressive disclosure, rich references, deterministic checks, and independent verification. ([Context engineering](https://claude.com/blog/the-new-rules-of-context-engineering-for-claude-5-generation-models), [verification loops](https://claude.com/blog/building-verification-loops-in-claude-code-with-skills))
* OpenAI and Google document task-specific evaluation, deterministic checks, human judgment, model graders, and grader-gaming risks. ([OpenAI](https://developers.openai.com/api/docs/guides/evaluation-best-practices), [Google](https://google.github.io/agents-cli/guide/evaluation/))
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.