Experience Sediment 2.0: Stop Writing for Colleagues, Start Writing for Agents
The most senior engineer on my team, W, has been doing this for 14 years. Over the past decade he wrote 80-something wiki pages on the company intranet, and they're full of scar tissue — the edge conditions of some ancient API, the root cause of a specific outage, the design traps hiding in a certain class of requirement. Writing wikis has been the standard way engineers preserve experience for the last ten years.
Then I fed all 80 pages to an agent and had it run real coding tasks. It performed exactly as if it had never read them.
The agent isn't stupid. Those wikis are, structurally, not written for an agent. They assume the reader will pick up context, ask a colleague, go read the code, stitch information across five documents. An agent sees one context window at a time and cannot ask you "which version are you talking about here" or "when exactly was this 'currently' written."
That's the big broken anchor of experience-sediment in the AI era: the reader quietly changed, and the writing didn't. W's 80 wikis were a treasure for a colleague in 2018. For an agent in 2026 they're noise.
Three layers: from rules to harness
If you accept that experience is now written for agents, then what you write, where you put it, and what format it takes all need redoing.
I split it into three layers, bottom to top, high-frequency to high-leverage.
L1 — the agent rule layer (cursorrules / claude.md / agent rules)
Bottom layer, highest frequency. That claude.md or .cursorrules file in every repo is what the agent reads before doing anything at all. It holds the judgments you'd otherwise have to repeat every single time:
- This repo uses pnpm, not npm; install with
pnpm i - Any SQL change generates a migration first — never edit the schema file directly
- The glossary (users call it an "order," the internal message bus calls it a "transaction")
- "When you're done: run tsc, then test, then lint. All three pass or you're not done."
Every line comes from a real incident. One rule kills one recurring class of bad output.
W's wiki did note that "this API times out because a piece of middleware caps at 30s." In 14 years that sentence saved nobody, because nobody reads a wiki before calling an API. Put the same sentence on line 1 of cursorrules and the agent sees it before every single call. Same words, different location, dozens of times the value.
L2 — the spec and kit layer (planning-level sediment)
Middle layer. What gets stored here is how to decompose this class of problem. Agents are strong at single-step execution and terrible at breaking work down — and breaking work down happens to be the core skill a senior engineer spent ten years building.
A few concrete shapes:
- Spec templates: "build a new dashboard page" expands into 7 steps — data API → type definitions → query layer → view layer → loading/empty states → tests → docs. Inputs and outputs of each step are fixed.
- Task kits: "debug a production bug" packages into a kit — pull the logs → diff against the last 24h of commits → reproduce on a branch → apply the minimal fix → add a regression test. The agent sees "production bug" and knows to expand into that flow.
- Review checklists: the same nits you've flagged on other people's PRs for five years — naming, edge conditions, N+1 queries, missing error handling — frozen into a list the agent must produce at review time.
This layer is the hardest to write, because it forces you to turn intuition into a finite number of steps. But everything you manage to convert is enormous leverage. A good spec template moves an agent from a wobbly 70 to a steady 90 — and it stops needing your review.
L3 — the harness orchestration layer (agent of agents)
Top layer. This one stores what the whole workflow should look like.
This is what I've spent the past year on: building a multi-coding-agent harness. Fundamentally it's your team's workflow encoded as scheduling logic:
- Who breaks down the task (planner agent)
- Who executes (coder agents, possibly several in parallel)
- Who reviews (reviewer agent, running the checklists from L2)
- Who merges (merger, deciding from the verdict whether it goes back for rework)
- What happens on failure — degrade, roll back, or escalate to a human
What lives here is ten years of your judgment as a TL: when to parallelize, when serial is mandatory, which node has to block on a human, which bug an agent is allowed to retry three times on its own. This layer cannot live in a wiki, because it has to be code that runs.
Which lessons are worth preserving, and which are wasted
Not all senior experience is worth feeding an agent. Some of it is high-ROI. Some of it is just burning context.
| Type of experience | Sediment ROI | Why |
|---|---|---|
| Recurring low-level rules | ★★★★★ | One L1 line kills a whole class of problem |
| Task decomposition patterns | ★★★★★ | Highest leverage in L2 |
| Domain glossary / API boundaries | ★★★★ | Gives the agent context, cuts wrong guesses |
| Root causes of past incidents | ★★ | Unless it converts into a defensive rule, it's just trivia |
| Design philosophy / aesthetic taste | ★ | Agents can't learn it; forcing it into rules hurts more than it helps |
| Org politics / cross-team maneuvering | 0 | Human-to-human. The agent isn't in that room. |
The mistake to avoid: one-click importing every wiki into agent context. Garbage in, garbage out — the context window fills with irrelevant history and the agent stops finding the parts that matter. The most absurd case I've seen: someone stuffed a 200-page onboarding handbook into the system prompt, and the agent recited five paragraphs of company values before writing a single line of code.
The right move is subtraction first: 80 wikis down to 8 cursorrules lines, 3 spec templates, and 1 harness config. Keep the other 70-odd wikis for humans, if humans still read them.
The reader changed, so the ROI curve changed
Traditional experience-sediment has linear ROI. You write 80 wikis, you cover 80 situations, one save each. Readership barely grows, because the number of people who voluntarily go read a wiki was always small and keeps shrinking.
Writing for agents has multiplicative ROI. One cursorrules line gets used on every task — ten thousand runs a year. The cumulative value of one good rule can exceed all the wikis you wrote in the previous decade.
There's a hidden entry barrier, though: you have to be able to tell what's worth writing down from what isn't. Which happens to be the exact gap between a senior engineer and a junior one.
A junior writing cursorrules dumps in everything he can think of. The file hits 800 lines, blows the context budget, gets re-read every run, and slows everything down. Worse, rules start contradicting each other and the agent ping-pongs between them — output ends up worse than with no rules at all.
The senior's advantage is knowing what not to write. And that skill — judging which experience deserves to be frozen — is itself a form of experience, and it can't be preserved. You can't write a rule that says "please apply my judgment here."
Which produces a slightly perverse situation: in the AI era, the person who preserves experience is scarcer than the experience itself. Someone who can cut a team wiki down to 8 cursorrules lines is worth far more than the person who wrote 200 wiki pages.
Concrete actions for three audiences
Senior ICs: open the project you have open most often and write the first version of its cursorrules. Cap it at 20 rules, and every rule has to come from a real trap you can still describe in detail. Run it for two weeks, see which ones did nothing and which saved you, iterate. Don't try to write it all at once.
TLs: take the 3 task types your team repeats most — releases, bug hunts, adding a new API — and turn each into a spec template in the repo. Have every new hire run the templates once in their first week; it beats half an hour of you talking in a meeting. Six months later, check how often your spec templates get edited: that rate tells you how mature your L2 sediment is.
Managers / EMs: stop asking engineers to write their experience into the company wiki system. In the AI era that format is dead on arrival. Switch to "every repo maintains its own agent rules file," and put it in the OKRs. The quality of a team's cursorrules tells you more about their capability than the number of RFCs they wrote.
Closing
The logic of preserving experience hasn't changed in ten years: write the wiki, write the RFC, write the onboarding doc, run the new-hire training. The reader was always "a future colleague."
But at some point, the most frequent reader of all that stuff stopped being human.
80% of your team's PRs are drafted by an agent, the agent uses the rules you wrote, and the agent doesn't read your company wiki. All three of those are already true. Most senior engineers just haven't connected them to the phrase "preserving experience" yet.
The adjustment isn't complicated: take the mental list of "things I wish every new hire understood in week one" and write it somewhere the agent will read, not in the company wiki system.
Different format, different reader, dozens of times the leverage. But it requires admitting one thing first: the genuinely scarce asset you built up over ten years isn't the knowledge — it's knowing which knowledge is worth teaching an agent.