Your Repo Is the Memory

Coding agents can now produce substantial code faster than many teams can align around it. This talk asks where intent, constraints, decisions, and proof should live when chat is temporary and the repository is the system of record.

The practical goal is to decide what to keep in the repo, what to leave in chat, and how to make the next run start smarter than the last one.

Coding agents made implementation cheap

The useful surprise is speed. A coding agent can inspect files, draft a plan, edit code, run commands, and summarize the result in minutes. The dangerous surprise is that alignment does not speed up automatically.

Noperator’s You can just say it describes the failure mode as “substantial form without discernible intent”: a capable generator can produce convincing code, tests, docs, and PRs from a vague instruction, leaving reviewers to reconstruct the goal.

The PR inherits too many jobs

Maggie Appleton’s One Developer, Two Dozen Agents, Zero Alignment describes the coordination shift: when implementation becomes cheap, “should we build it?” becomes harder than “how?”

If the pull request is the first shared checkpoint, it must recover the goal, plan, assumptions, proof, and coordination that disappeared when implementation collapsed to minutes. Durable context moves those decisions earlier, while the work is still cheap to redirect.

Speed becomes comprehension debt

Addy Osmani calls the ownership posture cognitive surrender and the accumulated gap comprehension debt. Tests can be green while nobody can explain the implicit decisions or safely change the result.

The team still owns generated code. Durable context keeps the goal, accepted tradeoffs, proof target, uncertainties, and human decisions attached to that code.

Start with the checkpoint you already trust

Before prescribing a workflow, locate the operating boundary. Autocomplete has a different risk profile from several terminal agents working against the same repo.

Ask three questions: how far can the agent run without review, which shared context survives outside chat, and where can a human still change direction before rework becomes expensive? Durable context carries shared intent to a checkpoint where it can still change the work.

The model is not your project memory

Simon Willison describes LLMs as a lossy encyclopedia: they carry broad public patterns, but the compression loses details. The model cannot infer this repo’s fast test command, migration rule, security constraint, product decision, or preferred module boundary.

For exact technical work, a correct repo-local example beats expecting the model to infer the rule. Repo files are local, versioned, and reviewable, but not automatically authoritative. Chat can remain temporary when it points to current, reviewable files.

In one Amp example, its co-creator Thorsten Ball reports that after a short UI-change request with a screenshot proof target, the agent read layered AGENTS.md files for the dev-server command, browser-automation and Storybook conventions, port, and checks, then returned the change and screenshots (00:20:22–00:22:55).

What should survive?

Durable context is useful because it filters, not because it hoards. Preserve accepted constraints, proof commands, decisions, task state, examples worth copying, and mistakes that should become checks. Let false starts, temporary hypotheses, duplicate logs, and moment-specific explanations expire.

Durable does not automatically mean current or authoritative. Name one current source of truth and say which source wins when instructions disagree. Never flush secrets, personal data, machine-specific paths, ephemeral URLs, or resource identifiers into repository memory.

The repo-memory stack

Each layer answers a different question. The map says where project truth starts. Procedures say how repeated work should happen. State says what is true for this task now. Evidence shows whether the work is done. Promotion turns one task’s lesson into reusable guidance.

Keeping those layers distinct prevents AGENTS.md, skills, and work items from becoming one large junk drawer.

AGENTS.md is the map

AGENTS.md is for instructions that apply before task-specific context exists: project shape, commands, coding conventions, dangerous paths, security rules, and links to deeper guidance.

It should be short enough to read and specific enough to change behavior. Boris Cherny recommends periodically deleting guidance, observing current model behavior, and restoring only instructions justified by repeated failures (00:03:21–00:08:54). Durable does not mean permanent.

Agent Skills are procedures

Agent Skills package repeatable workflows as folders with instructions and optional scripts, references, or assets. Use one when a workflow has a recognizable trigger, repeatable steps, supporting resources, and a clear proof target.

Use the description to tell the agent when the skill applies. Then run the same task with and without the skill. Nick Nisi and Zack Proser show an example where extra instructions made the agent perform worse. Their tests are informal, and the percentages they report are approximate (00:07:46–00:09:24, 00:29:24–00:30:27, 01:09:30–01:10:28).

A style preference belongs in AGENTS.md, a formatter, or a linter. A skill earns its place when it prevents a future run from rediscovering a procedure.

dot-agents keeps task state alive

dot-agents is a lightweight file convention for agent work that needs continuity, coordination, durable decisions, or a handoff. index.md is required and owns lifecycle state and the exact next action. Research, plans, progress, decisions, and persisted handoffs are optional support.

Small work stays conversational. Implement durable work in the current thread by default, and hand off only when another worker, environment, or independent judgment helps. At closeout, record proof, promote reusable lessons, commit the final snapshot, and remove the task-local work item; git history remains the archive.

Move review earlier than the PR

The diff is necessary, but it is no longer enough. Plan review catches wrong work before it is generated. Trace review catches skipped files, broad edits, repeated failures, and ignored checks. Diff review checks the implementation. Evidence review asks whether the proof matches the risk.

Vaibhav Gupta of Boundary describes a team that does not use traditional code review, but surrounds its BAML work with a small durable architecture.md, human-read design documents, dependency checks, and agent execution traces that feed human-triaged issues (00:00:01–00:06:00). The talk does not compare defects or maintenance outcomes with conventional review. The durable-context lesson is narrower: if line review shrinks, plans, traces, executable invariants, and evidence must become first-class review artifacts.

Authority should be explicit: permission to investigate does not imply permission to implement, and permission to implement does not imply permission to commit, push, merge, or release.

Evidence keeps judgment attached to the diff

Evidence is durable context because “done” is otherwise too easy to say. The proof should scale with risk: focused checks for a small change, integration or visual evidence for medium risk, and dry runs, rollback plans, or signoff for high risk.

Committed does not mean verified. Record which checks were rerun for this change, which results were inherited, and what remains uncertain. Evidence does not replace judgment; it gives judgment something concrete to inspect.

Promotion closes the loop

Promotion should leave the next run better, not merely larger. Preserve what changed future behavior, turn repeated mistakes into checks, and prune guidance that no longer earns its place.

The useful loop is map, procedure, state, evidence, then promotion back into the smallest reusable artifact.

The before and after is mundane

A chat transcript helps the person in that chat. Repo-local context lets a fresh thread continue the plan, a teammate inspect the same intent and proof, and local, cloud, and CI environments share commands and conventions.

The agent does not become wise because a folder exists. It becomes easier to steer because the steering surface is visible and the next reviewer does not have to reconstruct the work from the final diff.

Start with one repeated pain

Do not design the perfect agent operating model. Start with one repeated pain: a missed command, repeated workflow, lost task state, recurring mistake, repeated ambiguity, or high-risk decision. Promote the smallest artifact that would make the next run better.

Someone has to own the loop: notice what helped, promote it, delete stale guidance, and keep the next run better than the last.

Start with one real task. Write down what made the agent better. Repeat. dot-agents.dev is one example of how to keep that context close to the work.

Sources used

• Noperator, You can just say it — source for the “substantial form without discernible intent” framing.
• Maggie Appleton, One Developer, Two Dozen Agents, Zero Alignment — source for the alignment bottleneck and collaborative AI engineering framing.
• Addy Osmani, Cognitive Surrender in Software Engineering and Comprehension Debt — source for the surrender/debt framing and the gap between generated code and human understanding.
• Simon Willison, Lossy encyclopedia — source for the lossy-compression mental model and the advice to provide correct examples for exact technical work.
• Thorsten Ball, “Think Harder: How I Prompt” (00:20:22–00:22:55) — an Amp co-creator’s account of a short UI-change prompt using layered AGENTS.md instructions and screenshot proof.
• Boris Cherny, We Cut 80% of Claude Code’s Prompt (00:03:21–00:08:54) — source for prompt ablation and restoring guidance only after repeated observed failures.
• Nick Nisi and Zack Proser, Writing & Using Skills (00:07:46–00:09:24, 00:29:24–00:30:27, 01:09:30–01:10:28) — a hands-on workshop on when skills load and how to test whether they improve a task; its evaluation figures are approximate.
• Vaibhav Gupta, fighting slop with slop (00:00:01–00:06:00) — a Boundary product and engineering-practice account supporting durable architecture guidance, reviewed design writing, executable boundaries, and trace-based issue discovery when traditional line review is reduced.
• AGENTS.md, Agent Skills, and Codex Skills — source material for map and procedure conventions.
• dot-agents, Right-Sized Threads, Durable State, and Make the Agent Prove It — source material for file-backed task state, handoffs, and the evidence ladder.