AppMap Gold Traces
Runtime behavior an agent could not otherwise obtain. Current at every commit. The baseline every change is verified against.
Found a gold_traces/ directory in a repository? Someone on the team keeps runtime behavior versioned with the code. Install AppMap to read the traces as diagrams, and your coding agent can query them over MCP.
Context agents cannot get any other way
A coding agent usually cannot run the application. No environment, no database, no credentials. From source it can only infer which queries fire, in what order, what a route actually touches. Some of it cannot be recovered from source at all. A committed trace is runtime ground truth without the runtime. Checkout delivers it with the code, so it is current at every commit, on every branch. And because the agent did not create the traces, they are a baseline it can verify its own changes against.
Three kinds of context
A coding agent works from three kinds of context. Source context is the code as written. Documentation context is the code as described. Runtime context is a record of what the code did when it ran: the calls it made, in what order, and the queries it issued. AppMap records the third kind, and Gold Traces version it with the code, so all three arrive with a checkout.
The team's approved baseline
Gold Traces are the behaviors a team has approved: the flows that must hold across every change, and the record intended changes must show up in. When code changes, the comparison against the baseline shows what held, what moved, and whether anything moved that shouldn't have. Developers and coding agents judge the change against the same evidence.
What teams use the comparison for
The routes, functions, and queries affected by a change.
Refactors and upgrades meant to hold behavior steady, verified to have held it.
The change touched the intended path and nothing else.
What a Gold Trace is
An AppMap trace is a recording of what the application did when it ran: the calls it made, in what order, and the queries it issued. Gold Traces are the curated set. They are selected to cover the key application paths, driven by a representative subset of the test suite. Each one is a small JSON file. At least one trace covers each release-critical subsystem, with additional traces for materially different code paths.
Where they live
Gold Traces are committed in the gold_traces/ directory, alongside the code. Git manages their provenance. They are flagged as binary in .gitattributes, so git never tries to merge them. A branch carries the trace set committed with that branch. When a feature branch changes behavior, its updated traces merge to main with the code, and every future branch inherits them. Checkout is the delivery mechanism: a developer or coding agent opening the repository starts with the same Gold Traces.
Every trace conforms to one published specification, the same format for every language. A gold_traces/ directory is portable: any MCP-capable agent can consume it, and any tool written against the specification can process it. The specification is open, at github.com/getappmap/appmap.
One person configures. The team expands.
Setup happens once per repository and is committed with the code. The appmap-gold-traces skill configures recording, creates the directory, and analyzes the code and test suite to select the initial set, listed in gold_traces/manifest.yml. Where coverage is missing, the skill suggests the test that would close it, and the coding agent can write it. After that, no one else configures anything. Coverage grows as a byproduct of normal work: a bug gets fixed, the path gets a trace, and later changes are compared against it.
What developers see
The IDE extensions display any trace as a diagram: the execution path, the queries with their sources, the API surface. The comparison between two revisions renders the same way, showing what held and what changed.
What coding agents query
Agents read the same traces over MCP: call trees, routes, SQL. The appmap-review skill compares the Gold Traces of a base and head revision, correlates the behavioral diff with the code diff, and reports what the change did when it ran: API changes and drift, SQL impact, security-affecting paths, unexpected side effects, performance changes. The findings post to the pull request. The same review runs locally before push, or in CI.
What issues does the review find?
Not issues from a list. A linter or a static analyzer carries a catalog of known-bad patterns and finds instances of them in your code. A behavioral review carries no catalog. It compares the change against the recorded behavior the team has approved, and reports what departed from it. That means it can expose the defects that are on no list: the ones specific to your application, produced by parts that are each correct alone. No rule says "two clocks in AI fallback calls," and no rule could. Every test can pass while the behavior changes. The comparison surfaces it because the behavior changed. A catalog of known-bad patterns finds what everyone's code gets wrong. A baseline of known-good behavior finds what your change got wrong. AppMap also includes a rule-based scanner for known problems, such as N+1 queries.
Sanitized before commit
Before a Gold Trace is committed, the AppMap CLI's sanitize command removes data values that may contain PII, secrets, or credentials. Gold Traces are development artifacts and are excluded from the built application, the same way test and documentation directories are.
How a set grows in practice
One of our own production applications adopted Gold Traces in a single day: one commit landed the manifest and the PR-time review together, and the skills were vendored so every agent session used them automatically. Coverage grew one fix at a time. Each incident, once fixed, was pinned as a trace. A read-only drift watch was added on main to catch changes from any lane. Each trace carries a plain-language line stating what breaks for a user if it fails. Four months of ordinary development later, the set guards forty behaviors across content integrity, authorization, ingest, and security paths, maintained by a team that is mostly AI agents.
When the team is mostly agents
Multiple agent sessions can touch the same code in a day. No agent sees the whole, and no agent remembers yesterday. The Gold Trace set is the part that persists: the behaviors the team has approved, in the repository, where every session reads them. The review checks every change against that baseline no matter which agent or lane produced it, and the drift watch covers pushes that skip the pull request. The application described above runs this way.
Enterprise
Teams start free in their own repositories. AppMap Enterprise adds airgapped deployment, internal distribution, organization-registered installs, and telemetry routing for organization-wide Gold Trace programs.