{"slug": "your-ai-agent-rebuilds-context-from-scratch-every-session-one-file-gives-it-the", "title": "Your AI agent rebuilds context from scratch every session. One file gives it the map.", "summary": "A developer introduced FLOCK.md, a markdown file that maps where a repository's knowledge lives, to address the problem of AI agents generating unfindable documentation. The standard includes a docs map, a question chain for design-to-delivery, and history rules to prevent agents from re-litigating rejected decisions.", "body_md": "AI agents changed who writes the documents in my repositories. They didn't change who has to find them later.\n\nOver the past year, agents have written most of the plans, specs, and work logs in my projects. They write them fast, they write them well enough — and they write them wherever they were pointed at that day. `docs/`\n\n, `notes/`\n\n, `planning/`\n\n, the repo root, a gist someone pasted into a ticket. Every file made sense the day it was created.\n\nThen you come back six weeks later and try to answer a simple question: *why did we decide this?* The decision exists. It's written down somewhere. Neither you nor the agent that wrote it can find it — and an agent that can't find a decision doesn't stop. It confidently re-litigates it, or refactors it away.\n\nThat was the failure that kept repeating for me. Not missing documentation — **unfindable** documentation, written faster than anyone could organize it.\n\n`FLOCK.md`\n\nis a markdown file at the repository root that answers one question:\n\n*where does this repo's knowledge live?* No schema, no tooling, no build step.\n\nThe minimum useful version is a single table:\n\n```\n# FLOCK.md\n\n## Docs Map\n\n| Type | Where | Answers |\n|---|---|---|\n| readme | README.md | What is this project and how do I run it? |\n| design note | docs/ | Why is a piece of the system built the way it is? |\n| decision | docs/decisions/ | What did we decide, when, and what was rejected? |\n```\n\nThat's a conforming adoption. A location that isn't in the table is, by\n\ndefinition, not part of the repo's knowledge contract — which sounds bureaucratic until you watch an agent actually respect it.\n\nPoint an agent at a repo with a Docs Map and it stops inventing directory structures. It reads the table and puts the document where the table says.\n\nFor projects that run a full design-to-delivery cycle, the standard defines a lifecycle called the **question chain**. A unit of work is done when four questions have written answers, in order:\n\n| Question | Document | It answers |\n|---|---|---|\nWhy? |\n`brd` |\nWhy is this worth building, for whom, measured how? |\nWhat? |\n`feature` |\nWhat are we building, and what is the user experience? |\nHow? |\n`blueprint` |\nHow exactly will it be built? |\nWhat happened? |\n`worklog` |\nWhat actually happened while building it? |\n\nAn index answers the fifth question — *where is everything, in what state?* — in one line per item, for every unit of work at once.\n\nThe three documents of a feature link to each other, so landing on any one of them gets you to the other two. If you've ever opened a spec and wondered whether it was ever built — or opened code and wondered whether it ever had a spec — that's the failure three-way linking exists to close.\n\nThe split that matters most in practice is `blueprint`\n\nvs `worklog`\n\n: what we *planned* versus what *actually happened*. Agents are exceptionally good at writing plans and exceptionally bad at remembering that reality diverged from them. Keeping the two as separate documents means the divergence is recorded instead of papered over.\n\nThe standard's history rules are the piece I'd defend hardest, because they exist for a failure mode that barely existed before agents:\n\n`(decided 2026-08-22)`\n\n, inline, next to the decision.`SUPERSEDED`\n\nwith a date, with the new decision next to it.Here's why that third rule earns its keep: an agent reading your codebase has no memory of the debates you already had. If the rejected option isn't written down, the agent will propose it again — articulately, plausibly, and with total confidence — three weeks after you spent a day deciding against it. The recorded rejection is what stops the same debate from being reopened by something that argues for a living.\n\nNo — they're complementary, and the boundary is clean:\n\n| AGENTS.md | FLOCK.md | |\n|---|---|---|\n| Answers | How do I build, test, and write code here? |\nWhere does knowledge live, and how does work flow? |\n| Audience | Coding agents | Humans and agents |\n| Scope | Code conventions | Docs and project management |\n\nIf you have an `AGENTS.md`\n\n— or `CLAUDE.md`\n\n, or whatever instruction file your tool reads — one line connects them:\n\n`Docs and project conventions: see FLOCK.md.`\n\nThat line matters more than it looks, for a reason specific to this year: no model has a standard this new in its training data. An agent has never heard of FLOCK.md — but it already reads your instruction file at the start of every session, so it finds the map through a file it already trusts, from day one.\n\nAdoption is a declaration, not a migration. The spec's typical locations are defaults; your Docs Map declares your real paths — so nothing moves. In a fresh repo, copy the [minimal template](https://github.com/repoflock/flock.md/blob/main/examples/minimal/FLOCK.md) as shipped and its defaults *are* the adoption.\n\nIn a repo that already has documentation, write Docs Map rows pointing at where the documents already live, and don't backfill: the history conventions apply from adoption day forward. Either way, the standard is explicit that adopting must not move, rename, or rewrite an existing file.\n\nIf you'd rather hand the adoption itself to an agent, the repo's [Quick start](https://github.com/repoflock/flock.md#quick-start) routes by repository state — fresh, existing docs, migrating an established docs system, upgrading an old adoption — and carries a guardrailed prompt for each path that needs one. And when you want to verify the result, the spec repo ships its own conformance checker — `node tools/check.mjs <repo>`\n\n, zero dependencies — which fails only on MUST violations: everything not marked MUST is guidance, and the checker holds itself to the same line the spec draws.\n\nThe full spec fits on one page: [github.com/repoflock/flock.md](https://github.com/repoflock/flock.md).\n\nIt's CC BY 4.0 and deliberately tool-agnostic — it works with zero tooling, in any editor, with any agent. It was extracted from the working conventions behind [RepoFlock](https://repoflock.com/flock?utm_source=devto&utm_campaign=flock-standard), where an earlier form of it has been used in production across the project's own repositories, but nothing about it requires any particular tool. It's a markdown file. That's the point.\n\nI'd genuinely like to hear where it breaks. If your repo has a docs layout that doesn't fit the Docs Map shape, or your agent workflow has a failure mode the history rules don't cover — the issues are open.", "url": "https://wpnews.pro/news/your-ai-agent-rebuilds-context-from-scratch-every-session-one-file-gives-it-the", "canonical_source": "https://dev.to/beannt_dev/your-ai-agent-rebuilds-context-from-scratch-every-session-one-file-gives-it-the-map-1f00", "published_at": "2026-08-29 15:11:22+00:00", "updated_at": "2026-08-29 15:49:17.593124+00:00", "lang": "en", "topics": ["developer-tools", "ai-agents", "ai-tools"], "entities": [], "alternates": {"html": "https://wpnews.pro/news/your-ai-agent-rebuilds-context-from-scratch-every-session-one-file-gives-it-the", "markdown": "https://wpnews.pro/news/your-ai-agent-rebuilds-context-from-scratch-every-session-one-file-gives-it-the.md", "text": "https://wpnews.pro/news/your-ai-agent-rebuilds-context-from-scratch-every-session-one-file-gives-it-the.txt", "jsonld": "https://wpnews.pro/news/your-ai-agent-rebuilds-context-from-scratch-every-session-one-file-gives-it-the.jsonld"}}