Coding agent field guide

Turn repeated review corrections into small, evidence-backed project lessons that future coding agents load only when relevant.

Read why coding agents repeat project-specific mistakes for the public experiments behind the idea, the Plannotator worked example, and the boundary between field-guide lessons and stronger artifacts such as tests.

This repository is an experimental, tool-neutral starter. It works with Codex, Claude Code, Cursor, other coding agents, pull-request review, or a human-only workflow. Plannotator OSS is the worked example and an optional local feedback source. Plannotator Workspaces can hold the shared review record. Neither is required.

Use it when your team repeatedly corrects the same project-specific agent behavior. You can copy the starter immediately and inspect the complete backnotprop-plannotator example. The longer concept guide explains when this artifact fits and how it differs from other forms of agent context.

Unlike AGENTS.md, memory, or Skills, a field guide keeps reviewed lessons behind a short index so an agent loads only the entries relevant to its task.

The job

Review feedback usually fixes the current task. A small part of that feedback describes a project-specific lesson that will matter again. That lesson often gets lost in a conversation or copied into an increasingly large instruction file.

A field guide provides the missing conversion step:

review feedback + accepted change + source evidence
                         |
                         v
                 one candidate lesson
                         |
                         v
       accept | revise | reject | merge | graduate
                         |
                         v
       selectively retrieved project guidance

A coding-agent field guide is a curated, project-specific, progressively disclosed set of lessons derived from observed work and review. Each active entry is:

• supported by a commit, pull request, issue, test, contract, decision, or another durable source;
• scoped to the tasks or code it governs;
• verified by a human;
• explicit about good behavior, bad behavior, verification, and exceptions;
• loaded only when its purpose or scope applies.

What to copy

The starter directory contains:

• an AGENTS.md pointer fragment;
• a small field-guide index;
• an entry template;
• a distillation workflow;
• a quarterly audit workflow;
• a plan-review rubric;
• a code-review rubric.

The backnotprop-plannotator example shows the complete structure against real public Plannotator OSS history. It contains two active lessons and one lesson that graduated into code and a regression test.

Five-minute setup

1. Copy starter/field-guide into your repository as field-guide.
2. Copy the two workflows and the rubrics where your team keeps review guidance.
3. Add starter/AGENTS.md.fragment to your root AGENTS.md, adapting only the paths.
4. Keep field-guide/index.md short.
5. Add no active entry until a human verifies its sources, scope, and exceptions.

The starter intentionally has no CLI or generator.

Recommended workflow

1. An agent produces a plan or code change.
2. Run tests, lint, type checks, builds, and other deterministic checks.
3. A human reviews the work, optionally using the plan or code rubric.
4. The agent applies the feedback and reaches an accepted result.
5. Identify only a repeated or consequential project-specific lesson.
6. Use the distillation workflow to draft one entry from the feedback, final diff, and governing sources.
7. A human accepts, revises, rejects, merges, or graduates the lesson.
8. Add an accepted entry to the index.
9. Future agents read the index and load only relevant entries.
10. Audit the guide and move enforceable lessons into stronger artifacts.

Most review comments should resolve the current task and go no further.

Possible dispositions

Disposition	Result
Accept	Mark the entry active and add it to the index
Revise	Correct the factual claim, scope, examples, or exceptions
Reject	Leave the candidate out of the guide
Merge	Update an existing entry without creating a duplicate
Graduate	Move the lesson into a test, lint rule, type, CI check, Skill, runbook, contract, or decision

Code, tests, contracts, and accepted decisions remain authoritative. A field guide records reviewed judgment; it does not override those sources.

What this is not

Artifact	Its job
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
Runbook	An operational procedure
Retrospective	Analysis of one event
Conversation archive	Raw history for replay or audit
Field guide	Reviewed project lessons retrieved only when relevant

This repository is not:

• an agent-memory service;
• a conversation archive;
• a generic prompt or Skills collection;
• a benchmark or leaderboard;
• a formal standard;
• a model-training or preference-learning system;
• dependent on Plannotator OSS or Plannotator Workspaces.

Saving feedback in a file changes future context. It does not train model weights.

Why the rubrics are here

The rubrics make review criteria explicit before a candidate lesson enters the guide.

Both rubrics:

• run deterministic checks first;
• use anchored 0 through 3 dimensions without a blended total;
• treat hard failures as blocks;
• require evidence and consequences for findings;
• never reward verbosity, plan length, or finding count.

Use the Plannotator review record you already have

Plannotator OSS lets a human review plans, documents, local changes, pull requests, and merge requests, then return anchored feedback to a coding agent. When Save plans is enabled, approved and denied plan decisions are stored under ${PLANNOTATOR_DATA_DIR:-~/.plannotator}/plans/. The optional plannotator-compound skill can find recurring failures in denied plan reviews. Returned document and code review feedback can be saved in a local folder and distilled with the same source-first workflow.

Plannotator Workspaces keeps plans, technical documents, comments, replies, supporting files, and version history together for a team. Agents can read the review record and maintain field-guide/ files through MCP or the HTTP API. Workspaces supplies the shared capture layer; this repository supplies the entry format, distillation workflow, and human-review boundary.

See the complete Plannotator OSS and Workspaces workflow. The method works the same way when feedback comes from another review surface.

Sources and provenance

The method builds on:

• Cursor's experimental Field Guide in Agent swarms and the new model economics;
• ThePrimeagen's Field Guide workflow using human corrections, Markdown records, commits, and agent distillation;
• Anthropic's guidance on progressive context and rich references and verification loops;
• OpenAI's evaluation best practices and grader-hacking guidance;
• Google's agents-cli evaluation guide, code-review guidance, and Open Knowledge Format.

Cursor described an early research experiment, not a generally available named Cursor product feature. ThePrimeagen's thread does not say that he uses Plannotator.

See THIRD_PARTY_NOTICES.md for attribution.

Contributing

Read CONTRIBUTING.md before proposing an entry, example, or rubric change. Contributions need inspectable evidence, honest scope, a verification method, exceptions, and a human verifier.

Status

Version 0.1 is an experimental starter. It passed independent retrieval, distillation, rubric-discrimination, deterministic-separation, source, privacy, and link checks. These results validate the artifact and its examples; they do not prove model-performance improvement.

License

Apache-2.0. See LICENSE.