All posts

Build Agent Context From What Shipped, Not What Was Said

Hand-written agent context goes stale. PostHog now derives it from completed work, and Atlassian is heading there. How to build it, and what's unsolved.

Misha Druzhinin
Diagram: merged PRs, decision records, and releases flow through a nightly job into a present-tense context wiki that agents read, while meeting notes and brainstorms are filtered out.

Every team that puts agents to work hits the same wall: the agent doesn’t know what the team knows. The usual fix is a hand-written context file. PostHog tried exactly that and published the result. Over 90 days, only 64 users started a shared context file, and only 14 ever edited it (PostHog, September 28, 2026).

So PostHog stopped asking people to write context. A nightly job now derives it from what was shipped, merged, or decided. Atlassian has announced the same direction. Its governed agent loops end with agents updating shared context from completed work.

Our read: shared agent context is a derived artifact, like a build output. Treat it like one. That means a source of truth, a pipeline, provenance, and a way to rebuild it when the truth changes. The last part is where both write-ups go quiet.

Key Takeaways

  • Hand-maintained context files decay. PostHog’s own numbers: 64 users started one in 90 days, 14 edited it.
  • PostHog now builds context nightly from what shipped, merged, or was decided. It deliberately ignores meeting notes and brainstorms.
  • Atlassian’s loop ends with agents updating shared context from completed work. Two teams, same conclusion.
  • The filter matters more than the format. Discussion is proposals; agents read everything in context as fact.
  • The unsolved parts are reverts, provenance, and permissions. Model the layer as an event log with a rebuilt view, and those get tractable.

Why does hand-written agent context go stale?

Hand-written context goes stale because nothing in the workflow forces anyone to update it. It’s documentation, and documentation decays. PostHog’s numbers are the clearest public measurement we’ve seen of this for agent context specifically.

PostHog’s setup made the problem sharper. Context in PostHog Desktop lives in user-defined “Spaces,” not chat threads. Compare a Slack bot, which can read the thread it’s in. A Space has no conversation to infer scope from, so someone has to build the context on purpose. PostHog’s first answer was a user-written CONTEXT.md for each Space. Almost nobody kept it up.

This is the same pattern we described for specs in OpenSpec Is Automating Its Best Feature. Artifacts survive only inside a workflow that touches them on every change. A context file that sits beside the work, rather than in its path, gets written once and then lies.

The cost is worse with agents than with people. A stale wiki misleads the human who reads it. A stale context file misleads every agent run that loads it, silently, in parallel.

What did PostHog and Atlassian converge on?

Both treat shared context as something produced by finished work, not written alongside it. They differ in how much they’ve said about the mechanism.

PostHog Atlassian
What updates context A nightly “dreaming” task Agents, as the last step of each loop
Inputs What was shipped, merged, or decided that day: PRs, handbook pages, dashboards Completed work; Code Context built on Teamwork Graph
Explicitly excluded Meeting notes, brainstorming docs Not stated
Storage Version-controlled Markdown wiki, present tense Not stated
Access control Permissions acknowledged as a gap Agent Context Controls for which agents see what
Status Running inside PostHog Desktop Announced; mostly early access or beta

PostHog’s write-up is a practitioner report with real usage data. Atlassian’s is a product announcement. It names the loop and the controls but gives little detail on how context updates are validated. It also cites a DX analysis: teams whose AI tools used the most graph context shipped about 64% more per developer. The post doesn’t give the methodology, so we’d treat that as a vendor claim, not a benchmark.

The convergence is still the useful signal. Two very different organizations, a product team reporting on its own usage and a platform vendor, landed on the same rule. Context should come out of the work, not sit next to it.

Why is “shipped” the right filter?

Because agents can’t tell a proposal from a fact. Everything in the context window reads as current truth. A meeting note saying “we’ll probably move billing to Postgres” becomes, for the agent, “billing is on Postgres.”

PostHog says this directly: observing meeting notes or brainstorms would make the layer “hallucinate and misrepresent reality.” We’d go further. The filter is the design, and the storage format is a detail.

Here’s how we sort inputs:

  • Facts the agent can rely on: merged PRs, released changelogs, deployed config, accepted architecture decision records (ADRs), published handbook pages.
  • Inputs for humans, not agents: meeting notes, brainstorm docs, open RFCs, Slack debates, draft tickets.
  • The gray zone: “decided.” PostHog lists decisions as an input. A decision that exists only in a meeting is still discussion. If it matters, write it down as an ADR or a merged doc change. Then it’s an artifact and passes the filter.

That last point is where engineering leaders come in. A derived context layer is only as good as the team’s habit of recording decisions somewhere durable. The pipeline can’t fix a team that decides things in hallway conversations. It can make the cost of not writing them down visible, fast.

What’s still unsolved?

Three things. Neither write-up addresses reverts or provenance. Permissions are a known gap at PostHog and an announced feature at Atlassian. A PostHog reader raised the revert question in the comments.

Reverts

A PR merges Tuesday. The nightly job writes “checkout uses the new pricing service.” Thursday the PR is reverted after a bug report. What happens to the entry? PostHog’s post doesn’t say.

If the wiki is edited in place by an LLM, you have two bad options. Rewrite the entry and lose the history, or append a correction and hope agents reconcile them. Both get worse over months.

Provenance

A present-tense sentence with no source can’t be checked. When an agent acts on a wrong context entry, you need to know where it came from. Was it a bad summary, or a real change that was later undone?

Scope and permissions

PostHog acknowledges permissions for Spaces as an open gap. Atlassian has announced Agent Context Controls for which agents see which data. Any company with access rules will need the second model. Context derived from a private repo shouldn’t leak into an agent working for a contractor.

How to model it: an event log and a rebuilt view

Our suggestion, and it’s our design, not something either source describes: don’t let the job edit the wiki. Split it in two.

  1. An append-only event log. One record per qualifying event: PR merged, PR reverted, ADR accepted, ADR superseded, release shipped. Each record keeps its commit or document reference, timestamp, and access scope.
  2. A present-tense view, rebuilt from the log. The wiki agents read is regenerated, not patched. Every sentence carries a link to the event that produced it.

This is plain event sourcing. It makes all three open problems tractable.

  • Reverts become just another event. The view is rebuilt, and the reverted fact disappears without anyone hand-editing prose.
  • Provenance is built in. Each line in the view points back to a PR or ADR.
  • Permissions can filter at build time, if each event is tagged with its repo or access scope. Generate one view per audience from events that audience may see.

A minimal nightly job can be small. This sketch shows the shape; it’s not a drop-in tool.

# 1. Collect yesterday's changes that landed on main (merges, squash merges, reverts)
git log main --first-parent --since="1 day ago" --format='%H|%s|%cI' >> context/events.log

# 2. List ADR files changed in the same window
git log main --since="1 day ago" --name-only --format= -- docs/adr/ \
  | sort -u >> context/adr-changes.txt
# (In practice, track the last processed SHA instead of a time window, dedupe by hash,
#  and tag each event with its repo and access scope.)

# 3. Rebuild the view from the full log (LLM step: summarize, cite every line)
#    "your-agent-runner" is a placeholder for whatever agent CLI you use
your-agent-runner rebuild-context \
  --events context/events.log --adr-changes context/adr-changes.txt --adrs docs/adr/ \
  --out context/CURRENT.md --require-source-links

# 4. Open a PR with the diff to CURRENT.md for a human to approve

Step 4 is deliberate. The rebuild is automated, but the view changes through a pull request. A human glances at the diff each morning. That’s the same human seam we argued for in the OpenSpec post. Automate the typing, keep the approval.

You can also test the view. Sample ten lines a week and check each against its linked source. That’s a small eval, and it tells you whether the summarizer is drifting. Our eight-step method for agent evals covers how to turn spot checks like that into a gate.

When is this overkill?

When one or two people work in one repo with one agent. A short, hand-kept AGENTS.md with build commands, test commands, and a few conventions is fine there. Those facts change rarely, and the person who changes them is the person who notices.

The derived layer pays off when several people and agents share context across repos. That’s when nobody owns the file, and that’s the pattern behind PostHog’s 64-to-14 numbers. If you’re unsure, start with the filter rule alone. Keep meeting notes out of agent context today, even if the file is still hand-written.

More machinery isn’t automatically better here. As we argued in Complexity Is Easy. Reliability Takes Design., add the pipeline when the failure it prevents is real for you.

Frequently Asked Questions

What is a shared context layer for AI agents?

It’s the body of team knowledge that agents load before working: architecture, conventions, recent changes, and decisions. It can be a hand-written file, such as AGENTS.md, or a generated one. PostHog now generates it from completed work, and Atlassian has announced the same approach.

Why not let agents read meeting notes and Slack?

Agents treat what’s in context as current fact. Meeting notes and threads are mostly proposals, debates, and plans that changed later. PostHog excludes them because they would make the context layer misrepresent reality.

How often should derived context be rebuilt?

PostHog runs its job nightly. That’s a sensible default for most teams. Rebuild on every merge only if agents act on very recent changes and you can review the diffs that often.

The bottom line

Hand-written agent context fails for the same reason documentation fails. Nothing in the workflow makes anyone update it. PostHog measured that and moved to context derived from shipped work. Atlassian’s announced agent loop ends in the same place.

The filter is the important part. Shipped, merged, and formally decided work goes in. Discussion stays with humans. The open problems (reverts, provenance, permissions) are data-pipeline problems. An event log with a rebuilt, cited view handles them better than an LLM editing prose in place.

One thing to do this week: open your team’s agent context file and tag every line with the PR, ADR, or doc it came from. Lines you can’t source are your stale context. Delete them or turn them into a recorded decision.

If your agents already run on a context file nobody trusts, that’s the kind of mess our AI cleanup work is for.

Sources