# How to organise a project's knowledge for AI coding agent and an engineer
**作者**: Sergii Makarevych
**日期**: 2026-10-23T17:17:51.000Z
**来源**: [https://x.com/sermakarevich/status/2113681318852600222](https://x.com/sermakarevich/status/2113681318852600222)
---
This is how I manage a project knowledge base on consulting projects. It helps me understand a client's documentation and requirements faster, and it makes automated AI coding faster and more reliable, because the coding agent works from a detailed spec that is always up to date when the project documentation changes. In short: every project document is sliced into readable chunks, each chunk gets a summary, the summaries roll up into one index per source and one per project, views are written from the summaries for a reader or a feature, a spec is written from a view when a feature is to be implemented, and every summary, view and spec links to the chunks it was built from, so when a document changes, a script follows the links to everything built on it and rewrites it in the same run. After reading you will be able to lay out the folders, define what a fact and an artifact carry, run a create workflow that turns design documents, tickets and code into checked pages, run an update workflow that carries a changed requirement to everything built on it, pick a search method, choose a reading path through the system, and write the spec a coding agent implements from, out of a view in the same store. The same tree, with two parts left out, serves a person learning a research field from papers, and Level 9 says which parts. Each figure comes from a public paper, vendor post or practitioner write-up.
## Quick grasp
A project knowledge base for agents is a folder of text files. It holds everything known about one system: design documents, requirements, decisions, tickets, and the parts of the code that explain behaviour. Two readers use it.
- A language model, which acts on what it finds. It answers questions, writes code and writes specs.
- An engineer, who needs to understand the system.
Nearly every published design treats the model as the only user and leaves the engineer out. This design serves both. The engineer has to be able to learn the system from the store, and most of what they read is not the stored documents but the summaries and views the model generates from them. So the quality of those generated pages matters as much as the documents. The engineer also has to be able to judge how well the model acts on the material, for example on a project's documentation or on one requirement. That judgment takes the form of evaluations, tests or validations of the model's output, and writing those takes understanding.
One term is used throughout. A hash is a short fingerprint computed from the content of a file. It changes whenever the content changes, so comparing two hashes shows whether something changed without reading it.
The design is five operations over one tree of Markdown files.
1. Store. The shape of the store itself: what kinds of files it holds, how they are kept apart, and how they are arranged on disk. Everything else operates on this shape.
- Three kinds of content live in separate folders and are never mixed: raw sources, facts and artifacts.
- Raw sources are the original material, saved as captured and never edited, often in a form that is hard to read, such as a PDF.
- Facts are the same sources made readable. The text is converted by a tool, then sliced into chunks that each end at a complete thought. Each chunk is one fact: the original span, word for word, and beside it a rewrite that reads on its own, with tables and figures turned into text. Anyone can check the rewrite against the original in a minute.
- Artifacts are everything the model summarised or wrote from the facts.
- Every fact has a summary, written from the chunk. The summaries of a source sit together in that source's index, one line per chunk. The project's index holds one summary per source, written from the chunk summaries, so it is a summary of summaries, and the index at the top of the store holds one line per project. Summaries are one level deep. Below a summary is the chunk itself.
- Views are the artifacts a person reads. Each view is one document about the project from one angle, written from the summaries, with the fact chunks opened where the summaries are not enough, and every statement citing its fact. Three views exist by default: a digest, a user view and a developer view. Further views are written on request, for one feature, one use case or one question.
- Specs are the artifact a coding agent implements from, in project stores only. A spec is a view transformed into what is required to be delivered, one per feature, written when the engineer decides the feature is to be implemented. Every critical statement in it is validated against a fact and links to it, and the spec links to the view it was written from, so a changed requirement reaches the views and specs built on it.
- Every artifact links to the facts it was built from, and the links are the only record of that.
- Folders are topics, and a topic is a project. A feature is a set of pages inside a project folder, not a folder of its own. Each project folder holds its own raw sources, facts and artifacts, and carries a short abstract of what is inside.
- Every folder has a generated index: its abstract, then one line per thing inside. Each index is short enough to read whole, and a project that grows gets more levels rather than a longer index.
2. Create. How new material enters the store: a design document, a requirements page, a ticket, a decision record, a module of code. The sources of a project are known in advance, so each project folder holds a sources file that lists them, with a link to the raw folder each one was saved to. One source goes in. A folder of checked facts and the artifacts built on them come out, in the right place in the tree.
- A new source goes through a fixed pipeline, in this order.
- Pipeline step 1: fetch it, convert it to text with a tool, and record it in the sources file.
- Pipeline step 2: slice the text into chunks of a manageable size, each ending at a complete thought, and store each chunk in a readable form beside its original words; these are the facts.
- Pipeline step 3: write a summary from each chunk, into the source's index.
- Pipeline step 4: write the source's summary from the chunk summaries, into the project's index.
- Pipeline step 5: write or refresh the views from the summaries, opening the chunks where needed.
- Pipeline step 6: check each page as it is written.
- Everything the model generates passes two guardrails before it enters the store. They check that what the model wrote is grounded in the source:
- Guardrail 1: every link in a page must point at something that exists.
- Guardrail 2: a page must say nothing that the facts it links to do not say.
- The first is plain code. The second is one model call that reads only the page and its facts. The original words of every chunk stay in the store beside the rewrite, so any check can go back to them.
3. Update. What happens when a fact changes, for example when a project requirement is revised.
- The update runs after something changed, started by a person or on a schedule.
- It refetches the sources and compares each one's hash with the hash recorded in the sources file. A changed source is converted and sliced again, all of its facts and their summaries are replaced, and everything built from that source is rebuilt in the same run.
- From each changed source it follows the links backward and collects every artifact built on it, directly or through another artifact. Those artifacts are rewritten in the same run, automatically, starting with the ones closest to the change. Nothing is left for a person to notice. If a rewritten artifact says the same thing as before, nothing above it is touched. A revised requirement usually changes one sentence of one page and leaves the summaries above it as they were.
- Each rewritten artifact passes the same guardrails as a new one before the artifact above it is rebuilt from it, so one bad rewrite cannot spread upward.
- A new artifact, one that did not exist before, is not an update. It goes through the create step.
4. Retrieve. The agent finds what it needs by progressive disclosure: it reads a little at each level and opens the next level only where the question points.
- The index files are the agent's starting point. It reads the index of projects, opens the project index and reads the source summaries, opens the source index and reads the chunk summaries, and then opens the one chunk the question points at.
- It stops as soon as it has enough. A source of a thousand pages is reached through a handful of short reads, and the agent reads the single chunk that holds the detail, not the whole source.
- Every lookup is logged. Keyword ranking, embeddings and a reranker are added in that order, and only when the log shows questions the index could not answer.
5. Teach. The store makes a person faster at understanding the material, because the same information exists as summaries and as full chunks, and because the views present it from the angle the reader needs.
- A person can read top-down, from the project's abstract through the source summaries to the chunks that matter, or bottom-up, starting from one chunk and climbing to see how it fits. Which way is a matter of preference. Both are a handful of short reads instead of the whole material.
- The three default views give three readers their own entry. The digest tells anyone what the project is and does. The user view tells someone who uses the system how it behaves. The developer view tells someone who changes the system how it is built. A view requested for one feature gives everything known about that feature in one place, drawn from many sources.
- Each view is an artifact like any other. It links to the facts and summaries it was built from and is rewritten by the update step when those change, so the view always says what its sources say.
Use this when a system's documentation keeps changing and is read many times, by more than one tool, or by an engineer who must learn it. For a one-off question over a few documents, put the documents in the prompt.
> Important: In the two measured tests of derived content, rebuilding by recorded inputs kept every plan and every cached answer in step with its source, while checking by age let 30 of 30 outdated plans through and let time-keyed caches serve 46 outdated answers (arXiv 2609.03340, 2607.26076).
> What it means for us: Every artifact links to what it was built from, and when a source changes the update run follows those links and rewrites every dependent artifact in the same run.
> Why it matters: Agents trust the page in front of them. An outdated page is believed over the agent's own knowledge most of the time, so no page is allowed to wait for a rewrite.
## Core ideas
1. Raw documents produce facts, facts produce artifacts, and the three are chained. A fact is one chunk of a raw document made readable, with the original words kept beside the rewrite. Every fact points at the span it came from and every artifact points at the facts it was built from, so when a raw document is updated, everything that depends on it is updated as well.
2. Views from different angles make the information easier for a person to consume, and they are the starting point for feature specs. A reader can go top-down from a project abstract or bottom-up from one chunk, and can read the project as a digest, as a user or as a developer, or read about one feature in isolation. A spec is written from the view that details the feature, so it starts from the current facts about that feature rather than from someone's memory of them.
3. Progressive disclosure limits token consumption and supports top-down drilling, by the model and by the person. Each level is read a little at a time, and the next level is opened only where the question points.
4. Chunking and summaries allow documents of any size to be processed. A document is sliced into complete thoughts, each chunk is rewritten and summarised on its own, and the source's summary is written from the chunk summaries, so no single step depends on the document's length.
5. A hierarchical structure keeps a huge project manageable, by adding levels instead of letting documents grow. Every index covers one level only, so each stays a size a model or a person can read whole however large the project becomes. When a folder outgrows that size, the store adds a level below it rather than a longer file.
## The levels
- Level 0. One change through the whole store. The folder layout, and one requirements document traced from its arrival, through a view and a spec, to a change in the document.
- Level 1. The tree and the index. What the store looks like on disk, how one workflow fills it, what facts, summaries, views and specs are, and how the agent and a person read them. Four parts: 1.1 the shape of the store, 1.2 how the store is populated, 1.3 what each folder delivers, 1.4 how the agent and a person read it.
- Level 2. Facts. What a fact is, how a document of any size is sliced into facts, how tables and figures become text, and how a fact is replaced.
- Level 3. Artifacts. Summaries, views and specs, and what a page's path and links tell a script.
- Level 4. Create. The workflow that turns a source of any length into checked pages, step by step.
- Level 5. Update. What happens after a source changes: detect the change, collect the dependents by script, rewrite them in the same run, stop early, check each hop.
- Level 6. Retrieval. Progressive disclosure through the index files, when plain search stops being enough, and whether the agent looks at all.
- Level 7. Reading paths for people. Summaries and chunks read top-down or bottom-up, and the three default views.
- Level 8. Specs. The spec written from a view and validated against the facts, who decides when, and the evidence that spec completeness decides agent success.
- Level 9. The research variant and the harness. What changes for a store of papers, and what survives a change of harness.
- A decision guide, takeaways and references.
## Level 0. One change through the whole store
This level answers: what are the parts of the store, and what happens to one requirements document from the moment it enters the store to the spec built from it?
A typical project's documentation sits in several places.
- Slide decks and PDFs from design reviews.
- Requirement pages in a wiki such as Confluence.
- Design notes, decision records and READMEs in the git repository.
- Tickets that changed behaviour, and the code itself.
Those documents form a chain, even when nobody has drawn it.
1. Requirements say what the system must do.
2. Design decisions say how the team chose to do it and why.
3. The spec says what is to be delivered, in enough detail for the agent to implement it.
The store keeps that chain explicit. Each view and each spec points back at the facts it came from. When a requirement changes, the update run rewrites the views and specs built on it, automatically. Artifacts are always up to date with the facts they are based on. A second kind of store, one a person builds to learn a research field from papers, differs in a few places. Level 9 lists them.
The store is one folder tree, organised by project. Each project gets a folder with three fixed subfolders: raw, facts and artifacts.
- raw - holds the sources exactly as they were captured, in whatever format they came. Nobody edits them.
- facts - holds each source made readable: the text as a tool converted it, one page per chunk with the original span and a rewrite that reads on its own, every table and figure as an image with a text version beside it, and an index with one summary per chunk.
- artifacts - holds everything the agent wrote from those facts: the views that present the project as a digest, to a user, to a developer or around one feature, and the specs written from those views when a feature is to be implemented.
Every folder carries a generated index file. The top of the store holds only such an index, which lists the projects. A project's index opens with the project's abstract, then gives one summary per source, written from that source's chunk summaries, then one line per folder. A source's index under facts gives one summary per chunk, in source order. A project folder also holds a sources file that lists the project's sources and links each one to its raw folder.
Everything about one project sits in one folder that a person can open, move or share. The type of content is the last turn in the path. The agent reads the index files, and each index says what its folder holds.
```
kb/
index.md generated: the list of projects, one line each
<project>/
index.md generated: project abstract, one summary per source, one line per folder
sources.yml the project's sources, each linked to its raw folder
raw/<source>/ exactly as fetched, content-hashed, never edited
facts/<source>/ the source made readable: converted text, one page per chunk, figures as text
index.md one summary per chunk, in source order
artifacts/ everything written from the facts
views/ digest, user, developer, and any view written on request
specs/ one spec per feature, written from its view
```
A requirements document enters the store. Someone finishes a new version of a requirements document and adds it to the sources file of the project it describes. The create workflow then runs.
1. It fetches the document, hashes it, stores it in that project's raw subfolder and records that folder and the hash in the sources file. A tool converts it to plain text and page images under the facts subfolder. No model has touched anything yet.
2. It slices the text into chunks that each end at a complete thought. For each chunk it writes a fact page: the original span, then a rewrite that reads on its own, with the tables and figures in that span turned into text.
3. It writes a summary from each chunk into the source's index, then the source's summary from those into the project's index.
4. It writes or refreshes the digest, user and developer views from the summaries, opening the chunks where a summary is not enough. Every statement in a view links to the fact it came from, and a script checks that every link resolves.
5. It adds one line for the source to the project's index and one line for the project to the root index if it is new.
That is the first part of the chain. A document became facts, and the facts became summaries and views, each linking to the facts it was built from.
A feature is developed. An engineer asks the agent for a view of one feature, for example every requirement about one part of the system, drawn from the facts across the store.
1. The view is written as an artifact. It is a narrow and detailed collection of what the store knows about that feature, each statement linking to the fact it came from.
2. The engineer reads the view instead of the documents. When the feature is to be implemented, the engineer asks for a spec written from the view. The spec states what is required to be delivered.
3. Every critical statement in the spec is validated against a fact and links to it.
4. The coding agent implements from the spec.
The view and the spec are artifacts like any other. When a requirement behind them changes, the update run rewrites them.
A requirement changes. Later the document is revised and one rule in it changes. The engineer starts the update workflow.
1. It refetches every source listed in the project's sources file and finds that one raw hash changed.
2. It converts and slices that document again and replaces all of its facts and their summaries. Version control keeps the previous ones.
3. A script collects every page that links into the document's facts, and everything that links to those: the source's summary in the project index, the views that cite the facts, and the specs that cite them. The rest of the run rewrites them in order.
4. The source's summary is rebuilt first. It comes out with the same meaning, so the project abstract above it is left as it is.
5. The views and the specs are rebuilt, because their affected sections cite facts of the changed document, and each is checked against its facts.
6. The decision records the rule rests on are separate sources whose hashes did not change, so their facts stay as they are. The rebuilt spec cites the revised requirement and the unchanged decision.
What the store is for. The views let a person, or an agent, consume one slice of the project's knowledge quickly, without reading the documents it came from. From that slice a spec is written when the feature is to be implemented, and the coding agent implements from the spec. Every mechanism below serves one of those two ends.
Carry forward
- Topic comes first in every path: a project is a folder and a feature is a set of pages inside it. Each project folder holds raw, facts and artifacts, with the views and the specs inside artifacts, plus a sources file and an index that opens with the project's abstract. At the top of the store sits only the index of projects.
- A source becomes facts, one per chunk with its original words kept, and facts become summaries and views. Each page links to what it was built from, and a script derives the reverse map from those links whenever the update needs it.
- A view is the slice a person reads and the input a spec is written from. The engineer asks for the view, and asks for the spec when the feature is to be implemented.
- A changed requirement is detected by hash. The same run follows the links backward and rewrites everything built on it, nearest first, stopping where the meaning is unchanged.
## Level 1. The tree and the index
This level answers: what does the store look like on disk, how is it filled, what does each folder deliver, and how do the agent and a person read it?
1.1 The shape of the store
The store is one folder tree of Markdown files. Read from the top down, it has three layers.
- The top of the store holds only a generated index that lists the projects, one line each.
- One folder per project sits below. Each project folder holds a generated index that opens with the project's abstract and gives one summary per source, a sources file that lists the project's sources and links each one to its raw folder, and three fixed subfolders: raw, facts and artifacts.
- Inside a project, each source has one folder under raw, holding it exactly as fetched, and one folder under facts, holding it made readable: the tool's text conversion, one page per chunk, its tables and figures as images with text beside them, and an index with one summary per chunk. The artifacts folder holds everything a model wrote from the facts, in two subfolders: views, the documents a person reads, and specs, the documents a coding agent implements from.
Below is a store with one project and one source, expanded all the way down.
```
kb/
index.md generated: the list of projects, one line each
<project>/
index.md generated: project abstract, one summary per source, one line per folder
sources.yml the project's sources: url or path, fetch method, last hash, raw folder
raw/
index.md one line per source
<source-id>/
original.pdf exactly as fetched, in whatever format it came
meta.yml url, fetched date, sha256
facts/
index.md one line per source
<source-id>/ the source made readable
index.md one summary per chunk, in source order, each linking to its page
text.md one tool conversion of the whole source, hashed, no model
pages/p-004.png page images at a fixed resolution
figures/table-03.png a table or figure cut from a page image
figures/table-03.md its text form: the table as Markdown, or a description with the values shown
<chunk-slug>.md one fact: the original span, then the rewrite that reads on its own
artifacts/
index.md one line each for views and specs
views/
index.md one line per view
digest.md what the project is and does, for anyone
user.md how the system behaves, for someone who uses it
developer.md how the system is built, for someone who changes it
<feature-or-question>.md a view written on request, around one feature, use case or question
specs/
index.md one line per rule
<feature>.md one spec per feature, written from its view when it is implemented
```
1.2 How the store is populated
Nothing in the tree except the raw files is written by hand. One workflow, described step by step in Level 4, fills the rest. In outline it runs like this for every source.
1. Fetch and convert. The source is copied into the project's raw folder exactly as found, hashed, and recorded in the sources file. A tool, not a model, converts it to plain text and page images under the facts folder.
2. Slice into facts. The text is sliced into chunks that each end at a complete thought. Each chunk becomes a fact page: the original span, word for word, and below it a rewrite that reads on its own, with the tables and figures of that span turned into text. Level 2 describes the slicing.
3. Summarise each chunk. A model writes a short summary from each chunk. The summaries go into the source's index, one per chunk, in source order, each linking to its fact page.
4. Summarise the source. From the chunk summaries the model writes one summary of the source, and that summary becomes the source's entry in the project's index. The project's abstract at the top of that index is rewritten from the source summaries when they change.
5. Write the views. Every page written from here on links to what it was built from, and that is the only record of the dependency. From the summaries the model writes or refreshes the digest, user and developer views, opening the fact chunks wherever a summary is not detailed enough, and citing a fact by path for every statement.
6. Check each page. Every page is checked as it is written, by a script and then by one model call, before the next page is built from it.
Specs are the one artifact this run does not produce. They are written when the engineer asks for one, from the view that details the feature. Level 8 covers them.
1.3 What each folder delivers
Four kinds of thing come out of that workflow, and each has its place in the tree.
Facts. One folder per source under facts, holding the source made readable and nothing more. It has the tool's text conversion of the whole source, one page per chunk, and a figures folder where every table and image from the source sits as a picture with a text version beside it. A fact page holds one line naming the pages of the original it came from, the original span, and a rewrite of it that reads on its own. Facts are the unit the agent reads when it needs the detail behind a summary. Level 2 covers them.
Summaries. One level of them, stored in the index files. The source's index holds one summary per chunk. The project's index holds one summary per source, written from the chunk summaries. The root index holds one line per project. A reader of any kind takes a source in through these three steps and opens a chunk only when the question needs it.
Views. The documents a person reads, under the views folder. A project tree answers one kind of question well: where is the material about this project? It answers another badly: what does this project do, how does it behave for a user, how is it built, what is known about this one feature? A view answers the second kind. To write one, the model reads the summaries to find which facts matter for the angle asked for, opens those fact chunks where the summaries are not enough, and writes one document for that angle, each statement citing its fact wherever that fact sits. Three views are written by default, the digest, the user view and the developer view. Any further view is written on request: for one feature, one use case or one question, and it may draw on several projects. Every view is rebuilt by the update step when anything it links to changes, and none is written by hand.
Specs. A view transformed into what is required to be delivered, one spec per feature under the specs folder, written when the engineer decides the feature is to be implemented. Every critical statement in it is validated against a fact and links to it, and the spec links to the view it was written from. Level 8 covers them.
1.4 How the agent and a person read it
Every folder's index describes the folder, then lists what is inside, so a reader can stop at any depth.
- The root index lists the projects.
- A project index gives the project's abstract and one summary per source.
- A source's index gives one summary per chunk.
- Below that is the chunk itself.
This is progressive disclosure: read one short index at each level, and open the next level only where the question points.
The agent and the person use the tree differently.
- The agent starts at the index of the project its task names, or at the root index when it does not know the project. It reads the source summaries, picks a source, reads its chunk summaries, and opens the one chunk that holds the detail. It stops at the first level that answers the question. When no line fits, it searches every index file by keyword instead of guessing.
- A person mostly reads views. The digest, the user view and the developer view give the project from three angles, and a requested view gives everything about one feature in one place. Only when a question needs the detail do they follow a view's links down to a chunk, or start at the chunk a ticket names and climb up through the summaries to see where it sits.
> Important: In the one controlled test of how agents navigate files (He et al., arXiv 2607.17598), a one-line-per-file index scored 0.462 against 0.257 for raw files, and a second routing layer with misleading group summaries fell to 0.267 because the agent picked the wrong group and never came back.
> What it means for us: An index in every folder, each line a real summary of what it points at, each index short enough to read whole, with a search across all index files as the way back from a wrong turn.
> Why it matters: A nested index fails when its summaries are bad or its levels are long. The design pays for depth with real summaries on every index line and indexes short enough to read whole.
Carry forward
- Every folder has a generated index: its abstract, then one line per thing inside. The agent descends it one short index at a time and searches all index files when no line fits. A person mostly reads the views and goes down to a chunk only for detail.
- One workflow fills the tree from the raw files: convert, slice into facts, summarise each chunk, summarise the source, write the views, check each page. Specs are written from views on request.
- Summaries are one level deep and live in the index files: chunk summaries in the source's index, source summaries in the project's index, one line per project at the root.
- Three default views, digest, user and developer, plus any view written on request. Each is a rebuilt artifact whose links may reach several projects.
## Level 2. Facts
This level answers: what is a fact, how is a document of any size sliced into facts, what happens to tables and figures, and how does a fact change?
Facts are the raw source in a form an agent can read: Markdown instead of a PDF, a scan or a spreadsheet, and chunked so that it is simpler to process and to consume. A pipeline step works on one chunk at a time instead of a whole document, and an agent reads the one chunk a question points at instead of the whole source. Each chunk is a fact page with two parts. The original span is copied in by script, word for word, and stays as it was converted. Beside it a model writes a rewrite that reads on its own and keeps the facts of the span. The original is the record and the rewrite is the readable form of it, and because both sit in one file, the rewrite can be compared with the original by a person, a model or a script at any time. The source hash decides when a fact is replaced.
The fact page. Each fact is one Markdown file in the source's folder under facts, named by a short slug of its content. One line at the top says where it came from: the pages of the original document and the line span in the converted text. Then the original span, word for word, then the rewrite.
- First line: Source: original.pdf, pages 12 to 14. text.md lines 410 to 468.
- A heading Original, then the span word for word, as the tool converted it.
- A heading Rewritten, then the same content, readable on its own.
The path identifies the file, and the source hash tracks its change. The original section is copied by script from the converted text. The rewrite is the part a reader uses: every pronoun and back-reference resolved so the chunk reads on its own, and each table or chart in the span transcribed from the page image into text. The source's index lists each fact in source order with its page range and its summary.
How a document of any size is sliced. A model cannot read a 300-page functional requirements document in one pass, and a cut at a fixed size lands in the middle of an argument, separating a result from the condition that made it true. So the converted text is sliced by meaning, not by count.
- A window opens at the cursor and grows sentence by sentence to a floor of about 2,000 tokens. The model is asked one question: does this window end at a complete thought, and if not, which is the last sentence that does? It must answer with that sentence word for word. A script checks that the sentence appears in the converted text, retries once, and otherwise falls back to the last sentence boundary. The window is capped at about 4,000 tokens, so a run-on section cannot stall the run.
- The chunk's original span is copied by script into the fact page. The model then writes the rewrite, and from it a one or two sentence summary and a content slug that becomes the file name.
- Each call sees the chunk before, the summaries of the chunks so far, and the chunk in hand, under a fixed token budget. The model never sees the whole document, which is what makes the step indifferent to length: a two-page architectural decision record and a 600-page design document are processed by calls of the same size.
- The run saves a checkpoint after every chunk, so a run interrupted at page 400 resumes at page 400.
Tables and figures. A text conversion flattens tables and loses charts and diagrams. So each page of the source is also rendered as an image at a fixed resolution, and every table, chart and diagram is cut out of its page into the figures folder as a picture. A vision model writes a text file beside each one: a table becomes a Markdown table, a chart becomes a description with the values it shows, a diagram becomes a list of its parts and the arrows between them. The fact whose span holds the figure links the text file and includes its content in the rewrite, so a reader of the fact sees the table without opening the image. The picture is kept because the text can be wrong, and because an image is read once by a model and its text many times.
The rewrite reads on its own. The rewrite is the chunk transformed into a readable form. Pronouns and implied references are resolved, a line of framing is added where the chunk starts abruptly, the facts, numbers, names and dates of the span are kept at the same density, nothing is added beyond the span and its context, and the tables and charts of the span are transcribed from the page images. The Filesystem-Based Memory study is the reason the density is kept. Moving an agent's files into folders without editing them scored 86.1 on the LoCoMo conversation benchmark, the same as a store curated over many rewrite rounds. A condensed rewrite that dropped detail scored 79.1 there and 41.2 on a second benchmark where every other variant scored 77.6 (arXiv 2607.26637). Organising costs nothing in accuracy. Condensing costs up to half the answers. The original span stays in the same file so that the rewrite can be read against it, and every statement in an artifact links to its fact so that an artifact can be read against the original too.
The source hash. The sources file holds one hash per source. When a source is fetched again and its hash differs, it is converted and sliced again, all of its facts and their summaries are replaced, and every page that links into them is rewritten in the same run. Version control keeps the previous facts. No model edits a fact in place, and no fact is removed while its source is still listed. A project's requirements change rarely and on purpose, so rebuilding everything built on a changed document is the right default, and the same-meaning stop of Level 5 keeps the rebuild from climbing further than it must.
> Important: A store whose files were organised but left as written scored 86.1 on the LoCoMo benchmark, the same as a curated store, while a condensed rewrite scored 79.1 there and 41.2 on a second benchmark where every other variant scored 77.6 (arXiv 2607.26637).
> What it means for us: The rewrite makes a chunk readable and keeps its content at the same density, and the original stays beside it in the same file.
> Why it matters: Condensing is where a store loses answers, and a rewrite that can be read against its original is a rewrite anyone can check.
Carry forward
- A fact is one chunk: a line naming its pages in the original, the original words, and a rewrite that reads on its own. Tables and figures live beside it as pictures with text. The source's index lists each fact's pages and its summary.
- Slicing ends every chunk at a complete thought, verified against the text by script, so a two-page note and a 600-page document are processed by calls of the same size.
- A changed source replaces its facts and their summaries whole and version control keeps the old ones. The original beside every rewrite is what any reader compares against.
## Level 3. Artifacts
This level answers: what must a page the agent wrote carry so that it can be trusted and rebuilt, and what are the kinds of artifact?
An artifact is anything a model wrote from facts. The design has three kinds.
- Summaries. One per chunk, written from the chunk, stored in the source's index. One per source, written from the chunk summaries, stored in the project's index. The project's abstract and the root index line compress again.
- Views. One document per angle. The digest, the user view and the developer view exist for every project. Further views are written on request, for one feature, one use case or one question. The model reads the summaries to find which facts matter, opens the fact chunks where the summaries are not enough, and writes the document for that one angle.
- Specs. A view transformed into what is required to be delivered, written on request when a feature is to be implemented, with every critical statement validated against a fact.
An artifact is cheap to make and expensive to trust, so every statement in it links to the fact it came from, inline, and a view or a spec can be read back to the source line by line.
What a page is. A page is prose and links, and three things in the tree tell a script everything it needs about it.
- Its path says what it is. A page under views is the view its filename names. A page under specs is the spec of the feature its filename names. A summary sits in the index of the folder it summarises.
- Its links say what it was built from. A summary links down to the chunk or the chunks beneath it. A view links to the facts and summaries it drew on, wherever they sit. A spec links to the view it was written from and to the fact behind each critical statement. A script that needs to know what was built on a page finds every page that links to it, which takes seconds and no model tokens.
- The sources file says when a source changed. The file holds one hash per source. When a refetch finds a different hash, every page built from that source is rewritten.
Dependent artifacts update automatically. The update run refetches every source and compares its hash with the one in the sources file. For each source that changed it replaces the facts and their summaries, follows the links backward to every page built on them, and rewrites those pages in the same run, nearest the change first. A new document in the store, or a new version of one, therefore means new summaries, new views and new specs at the end of that run, with no step where a person decides which pages to redo. The rewrite has to be automatic, because agents believe what is in front of them.
- Across more than 1,200 questions, models replaced a correct answer they already knew with an incorrect retrieved passage over 60 percent of the time (ClashEval, arXiv 2404.10198).
An outdated page would override the truth, so the store never holds one past the run that detected the change.
Markdown throughout. The agent and the person read the same Markdown files. Markdown is dense, easy to diff, and readable in any editor, a git host or a wiki renderer, so one format serves both readers and nothing is built twice.
Carry forward
- Three kinds of artifact: summaries, views and specs. A page is prose and links: the path says what it is, the links say what it was built from, and the sources file says when a source changed.
- When a source changes, the update run follows the links backward and rewrites every dependent artifact in the same run. Agents override their own knowledge with outdated text most of the time, so no page waits.
- One format, Markdown, for both readers.
## Level 4. Create
This level answers: what happens, in order, when a new source arrives, and where does a script decide instead of the model?
Create is the operation that fills the store. It needs a fixed shape because errors enter here and compound later. The model drafts everything, and a script checks each page before the next is built from it.
Step 1. Fetch and convert. In a project store the source is first added to the sources file of the project it belongs to, with its location and its fetch method. The create workflow and the update workflow then read the same list. The source is fetched, hashed and saved into that project's raw subfolder exactly as captured, in whatever format it came, and never touched again. A tool then converts it to plain text and renders every page to an image at a fixed resolution, both under the source's folder in facts. No model is involved in the conversion, so the text can be checked against the page images and the page images against the original.
Step 2. Slice into facts. The converted text is sliced into chunks that each end at a complete thought, by the method of Level 2, and each chunk becomes a fact page: the original span copied by script, and a rewrite by the model that reads on its own, with the tables and figures of that span turned into text from their images. The complete-thought boundary matters most here: a chunk whose condition sits in the previous chunk is the chunk a rewrite gets wrong. The model does not write prose about the source yet. Keeping the whole text of every chunk, and writing pages only afterwards, is what lets every later sentence point at a checkable anchor.
Step 3. Summarise each chunk. From each rewrite the model writes a summary of one or two sentences and a content slug that names the file. The summaries go into the source's index, in source order, each linking to its fact page. Each call sees the chunk in hand and the summaries so far, under a fixed budget, so a source of any length is summarised by calls of one size.
Step 4. Summarise the source. From the chunk summaries the model writes one summary of the source, which becomes the source's entry in the project's index, and the project's abstract at the top of that index is rewritten from the source summaries. Writing bottom-up means everything a summary links to exists before the summary does, so the link check of step 6 can run the moment it is written.
Step 5. Write the views. From the summaries the model writes or refreshes the digest, the user view and the developer view. For each it reads the project's summaries to find the facts that matter for that angle, opens the fact chunks where a summary is not detailed enough, and writes the document with every statement citing its fact by path. A view written on request, for one feature or one question, is produced the same way when asked for.
Step 6. Check each page as it is written. Two checks per page, in order.
- A script checks that every link resolves and points at a fact or a page that exists. On failure it retries the model with the failure list, up to a fixed count. In a wiki compiled by a model over three multi-hop question sets, dangling links made up 29 to 64 percent of all structural errors (arXiv 2605.25480).
- One model check reads the page against the facts and pages it links to, and nothing else, and answers one question: does the page say anything they do not?
The per-page timing follows the measured behaviour of multi-stage generation.
- In a four-stage pipeline, the share of errors that slipped past each boundary was 24.6, 48.3 and 89.3 percent as the stages went on. Gates at every boundary cut the errors that survived to the end from 58.4 to 16.2 percent, while one check at the end gained 2.3 points (arXiv 2608.14588).
- Where a check can run as code, run it: a requirement-rewriting agent resolved 46 of 100 issues when each requirement had to pass ten generated tests, and 34 when an LLM judge replaced the tests (arXiv 2604.06861).
A pipeline checked only at the end is a pipeline that polishes its mistakes.
Step 7. Index. The source gets its line in the project's index and, if the project is new, the project gets its line in the root index. Nothing in the store is edited in place: a rebuilt page replaces its predecessor whole, and version control keeps the predecessor.
> Important: Gates at every stage boundary cut the share of errors surviving a four-stage pipeline from 58.4 to 16.2 percent, while a single final check improved it by 2.3 points, and executable checks beat a model judge 46 to 34 on the same task (arXiv 2608.14588, 2604.06861).
> What it means for us: Check every page as it is written, with a script first and a model second, and never rely on a review of the finished store.
> Why it matters: The create pipeline is where every later page's truth is decided, and a late check cannot find an early misreading.
Carry forward
- Seven steps: fetch and convert, slice into facts, summarise each chunk, summarise the source, write the views, check each page, index.
- The model drafts at steps 2 to 5. Scripts decide at steps 1, 6 and 7. A source of any length is read in windows of one size.
- Every page is checked as it is written, by the link check and then by one model call, before the next page is built from it.
## Level 5. Update
This level answers: when a source changes, what happens to the pages built on it, in what order, and why not simply rebuild everything?
The update step runs whenever a source is fetched again with a different hash. It is a script, and the model is called only to rewrite. Four steps, each answering a different objection.
Step 1. Collect the dependents by script. For each changed source, a script takes its facts folder and its summaries, then every page that links into them, then every page that links to those, until it finds nothing new. A page in another project that links to the source's facts is collected like any other, so the walk crosses projects without special handling. This takes seconds and no model tokens. It is how a spreadsheet finds the cells to recalculate after one cell changes, and how incremental build systems such as Adapton find what to rebuild: the walk is cheap and follows every link, so it is done completely. The objection it answers comes from Level 3. An outdated page overrides the truth most of the time, so the set of pages to rewrite has to come from the links, never from a person remembering which pages mention the topic.
Step 2. Rewrite them in the same run. The update workflow is started by a person after a batch of changes, or on a schedule. It detects every changed input, collects the dependents of all of them, and rewrites that whole set in one pass. Running it per batch rather than per change matters because each rewrite costs model tokens and is a chance to introduce an error. Several changes to one document should produce one rewrite of each dependent, not one rewrite per change. Nothing is handed back to a person except what the guardrails reject.
Step 3. Stop early. The page closest to the change is rebuilt first. If its new text means the same as the old, the rebuild stops there and every page above it is left as it is. This is the early cutoff rule of the Salsa and Jane Street Incremental build systems, with one change: the comparison is not exact text but same meaning. A cheap classifier answers yes or no with a probability, and an exact-text match is the free first pass. The objection answered is cost. A revised requirement usually changes one sentence of one page and leaves the source summary above it saying the same thing, so most updates end one level up.
Step 4. Check each hop. Every rebuilt page goes through the two per-page checks of Level 4 before the next page above it is rebuilt from it. Errors compound through stages, and the pipeline measurement from Level 4 is the reason: unchecked, more than half of early errors survive to the end, and only a gate at every boundary brings that down to about a sixth. A view rebuilt from an unchecked rebuilt summary inherits its mistake and hides it one level higher.
Why rebuild by inputs and not check by date. Two systems have been measured on exactly this choice.
- Planfence gave a chain of agents plans derived from a shared memory and tested whether they noticed when that memory changed. Checking a plan by its age let an outdated plan through in 30 of 30 five-agent workflows, and none of them completed. Rebuilding it from its recorded inputs let none through and completed all 30, at about 15 percent more tokens per task (arXiv 2609.03340). The same study makes the case for checking each hop. A control that refreshed only the first agent picked the right action in 28 of 30 runs and still completed 0 of 30, because the agent after it worked from the old plan.
- FinCacheServe keyed cached answers to a hash of the evidence they used. It skipped 53 percent of model calls and served no outdated answer, where caches keyed on time served 46 outdated answers in a 208-request stress test (arXiv 2607.26076).
> Important: Rebuilding derived plans from their recorded inputs kept 30 of 30 workflows in step with the change, while checking them by age let an outdated plan through in all 30 (arXiv 2609.03340).
> What it means for us: Follow the links backward from each changed source to every page built on it and rewrite them in the same run, stopping where the meaning does not change.
> Why it matters: Full rebuilds cost tokens and add errors, and leaving pages for a person to notice means agents read outdated pages and believe them.
Carry forward
- Collect the dependents by script, through the links, completely.
- Rewrite them in the same run that detected the changed source. Stop when a rebuilt page means the same as before. Check each hop before the next.
- The set of pages to rewrite comes from the source hashes and the links.
## Level 6. Retrieval
This level answers: how does the agent find the right chunk, when does reading the index files stop being enough, and how do you know whether the agent looked at all?
The question that organises this level is cost per correct answer, not recall. The methods form a ladder, and each rung is added only when logged failures of the rung below justify it.
Rung one: the index files and progressive disclosure. The index of the project the task names is the agent's first read, or the root index when the project is unknown. Each index is short enough to be read whole. The agent takes the material in steps of growing size.
1. The project's abstract and its one summary per source.
2. The chosen source's index, one summary per chunk.
3. The one chunk that holds the detail.
It stops at the first step that answers the question, so most lookups cost a few hundred tokens and a handful of small reads. When no line in an index fits, the agent searches every index file by keyword, which gives it the flat list of pages on demand, and descends from the hit. The Filesystem-Based Memory study found that putting files into folders cut cost per query by about 60 percent at large store sizes without changing accuracy (arXiv 2607.26637). A store of a few thousand chunks with real summaries on every index line needs nothing more.
Rung two: keyword ranking over index lines. When a keyword search over the index files returns too many lines, a BM25 index ranks them. BM25 is a standard keyword ranking method that needs no model call. It is built over the index lines, so what it matches is the summary of each chunk, which is why those lines have to be real summaries and not titles.
Rung three: embeddings and a reranker. Add these only when the logs show queries phrased in words the pages do not use. Index the fact chunks, and prepend the heading chain to each: source, section, subsection. That header alone raised the ranking score by about 24 percent on a 196,000-chunk Markdown corpus, with no model call (arXiv 2608.00824). Retrieve a small budget, because long context degrades. Chroma's context-rot measurement across 18 models found that a model's accuracy on a fixed question falls as irrelevant tokens are added.
Rung four: a graph. Only for stores where many facts change over time and questions hop between them. A project store of this kind does not need it.
Does the agent look? The retrieval failure nobody budgets for is that the agent does not search at all. Vercel found that an 8 KB compressed index placed in the always-loaded file passed every evaluation case. The same content offered as an on-demand skill passed 53 percent, no better than no documentation, because the skill was never invoked in 56 percent of cases. The design's answer is structural. The project index is the agent's first read and costs nothing to reach, not something behind a tool the agent must choose to call. Retrieval is logged, and the log of misses is what decides whether the next rung is built.
Carry forward
- The index files and progressive disclosure carry thousands of chunks: project abstract, source summaries, chunk summaries, chunk. Add BM25 over index lines, then embeddings with heading-chain headers, then a graph, each only on logged failures.
- Make the project index the agent's first read and cost nothing to reach. An agent that must choose to look often does not.
## Level 7. Reading paths for people
This level answers: what makes the store faster for an engineer to learn from than the documents it was built from?
The engineer reads the same tree the agent does. Two properties of the tree make it faster to learn from than a folder of design documents. First, every piece of information exists twice, as a summary and as the full chunk, with the source summary and the project abstract above. Second, the same facts are presented from more than one angle in the views. Both properties already exist for the agent, so they cost nothing extra to keep.
Two directions. Every project carries an abstract, every source a summary, every chunk a summary and its full text. That gives two reading paths.
- Top-down starts at the project abstract, goes down to the source summaries, then to the chunk summaries, then to the chunk, and stops where the reader has enough. This is the path for a newcomer. An outline read before the material, which the learning literature calls an advance organiser, helps modestly in Luiten's meta-analysis of Ausubel's work.
- Bottom-up starts at the chunk a ticket or a question points to, reads it, and climbs to the summaries to see where it sits and what its neighbours are. This path must exist, and the summaries must be skippable, because an expert given a novice's scaffolding is slowed down by it. Kalyuga called this the expertise reversal effect.
Which path a person takes depends on preference and prior knowledge, and the store should not choose for them. The caution comes from the same literature. A study of more than 10,000 participants found that people who read an LLM summary instead of working through the material came away with shallower knowledge and gave less confident advice (Melumad and Yun 2025). The summaries are a map. Learning happens at the chunk, and a path that ends at the summary is not a reading path.
Three angles, and more on request. The views of Level 1 are the other grouping. The digest tells anyone what the project is and does. The user view tells someone who uses the system how it behaves. The developer view tells someone who changes the system how it is built. A newcomer reads the digest, then the view for their role, and follows its links down to the chunks that matter, instead of discovering source by source what the project contains. When a question cuts across the default angles, a view is written for it on request: one feature, one use case, one question, drawn from every source and every project that touches it. The views are rebuilt by the update step when anything they link to changes, so they stay as true as the facts they cite.
> Important: People who read a model's summary instead of working through the material came away with shallower knowledge and gave less confident advice in a study of more than 10,000 participants (Melumad and Yun 2025).
> What it means for us: Keep every chunk under its summary and every project in several views so an engineer can choose a path, but make the path end at the chunk.
> Why it matters: The same layers that make the store cheap for the agent let a person stop at the summary, and the evidence says that is where understanding is lost.
Carry forward
- Every project, source and chunk exists as a summary and, for the chunk, as full text, readable top-down or bottom-up. The summary is a map, not the destination.
- Three default views, digest, user and developer, and a view on request for any feature or question, each rebuilt when anything it links to changes.
## Level 8. Specs
This level answers: how is a spec written from a view that details one feature, aspect or use case, who decides when, and what does the evidence say decides whether the agent succeeds?
The specs folder under artifacts is the part of the tree that exists for the coding agent. A spec states what is required to be delivered for one feature, and it sits beside the facts and the view it was written from. Two decisions belong to the engineer. The first is to ask for a view: a narrow and detailed collection of what the store knows about one feature, use case or aspect, written from the summaries with the fact chunks opened where needed. The second is to ask for a spec from that view, when the feature is to be implemented.
The spec decides. The Specification Gap paper gave coding agents the same tasks with different amounts of specification (arXiv 2603.24284).
- One agent resolved about 89 percent of tasks with full docstrings and about 56 percent with bare signatures.
- Two agents splitting the work resolved 58 percent with full docstrings and 25 percent with bare signatures. Restoring the specification alone brought the pair back to 89 percent.
From view to spec.
1. A view is written for the feature, from the summaries and the fact chunks of the parts the feature touches. The engineer reads it and widens or narrows the request if it misses a part.
2. When the feature is to be implemented, the engineer asks for the spec. It is written from the view and states what is required to be delivered.
3. Every critical statement in the spec is validated against a fact and links to it. The two per-page checks of Level 4 run on the spec as on any page.
4. The coding agent implements from the spec.
The spec is an artifact. When a fact behind it changes, the update step of Level 5 rewrites it together with the view it came from, so the agent never implements from a spec the facts no longer support.
> Important: Two agents sharing a task resolved 25 percent of it with bare signatures and 89 percent with full specifications, and restoring the specification alone brought them back to 89 (arXiv 2603.24284).
> What it means for us: Write the spec from a view of the feature, validate every critical statement against a fact, and hand the agent the spec.
> Why it matters: The spec is the one input I control, and in the measurement it moved success by about a third.
Carry forward
- A spec is written from a view of one feature, on the engineer's request, when the feature is to be implemented. It states what is required to be delivered.
- Every critical statement in the spec is validated against a fact and links to it. The spec is an artifact under the same checks and the same update step.
- The coding agent implements from the spec.
## Level 9. The research variant and the harness
This level answers: what changes when the store holds papers instead of a project, and what in this design survives a change of harness?
The research variant. A person learning a field from papers uses the same tree with two parts removed and one changed. The topics are subjects rather than projects. A retrieval researcher's store has a folder for graph retrieval, and a 2025 paper's raw PDF, its fact pages and its summaries sit in the same places a requirements document occupies in a project store.
- No source list in advance. Sources arrive as they are found rather than being known beforehand, so the sources file is filled as they come, the create workflow runs per source and the update workflow has little to refetch. Papers do not change. An update is a retraction, an erratum or a newer result that supersedes a fact, and it is handled exactly as the revised requirement was.
- No specs. Nothing is implemented from the store.
- Views change angle. The digest stays. The user and developer views give way to views written on request, for one method, one benchmark or one question across the papers, and when a topic holds more than a few sources, a view that lists their agreements, disagreements and open questions is what a person reads before any single paper.
Everything else is unchanged: the facts, the guardrails, the index and the reading paths.
Harness-agnostic parts. Every mechanism above is a file, a script or a convention: Markdown pages, a generated index, and scripts for the link check, the hash check and the dependency walk. None of it depends on a vendor's memory feature. Whatever instruction file a harness reads at start, such as a project file in Claude Code or Cursor or an agents.md file, holds the root index, or the project index for a single-project store, or a link to it, and nothing else. The reason to keep the index in that file rather than behind a skill is the Vercel result of Level 6. A vendor's memory feature serves session continuity and is treated as a cache, never as the place where a fact lives.
Carry forward
- Files, links and scripts survive any harness. The harness's instruction file holds the index, and vendor memory is a cache.
- A research store is the same tree without specs and without a source list written in advance, with views written per method, benchmark or question.
## Decision guide
- Is a knowledge base worth building at all? Use: one only if the documentation keeps changing and is read many times, by more than one tool, or by a person who must learn it. Then check: would putting the documents in the prompt answer the same questions?
- Is this a project store or a research store? Use: a project store when a system is built from it, with a sources file written in advance, specs, and the digest, user and developer views; a research store when nothing is implemented from it, with no specs, a sources file that grows as papers are found, and views by method or benchmark. Then check: does anything ship from this store?
- How deep should the tree go? Use: as deep as size demands, with a generated index in every folder and a new level whenever an index grows past what is read whole. Then check: is any index too long to read whole, and when the agent takes a wrong turn, does it search the index files or keep descending?
- How should folders and files be named? Use: a project slug for the folder, then one of three fixed subfolders, raw, facts or artifacts, with views and specs inside artifacts; fact pages named by a slug of their content; views named by their angle; fixed names for generated files. Then check: can a newcomer tell what a page says from the directory listing alone, and does one project folder hold everything about that project?
- How do I take in a source longer than the model's window? Use: windows of about 2,000 to 4,000 tokens that end at a complete thought, each rewritten to read on its own with the original kept, each summarised, and the source summarised from the chunk summaries. Then check: does every boundary match the source verbatim, and does the run resume from a checkpoint?
- What counts as a fact? Use: one chunk of a source that ends at a complete thought, with its original span and a rewrite that reads on its own, its tables and figures as text, and a line naming its pages in the original. Then check: does the rewrite read on its own with the original beside it, and does every statement in a page link to a fact?
- What happens when a source changes? Use: replace all of its facts and their summaries, collect every page that links into them and everything that links to those, rewrite them in the same triggered run, stop at same meaning, check each hop. Then check: after a run, does any page still link to a fact that no longer exists?
- How do I search? Use: the index files and progressive disclosure first, project abstract, source summaries, chunk summaries, chunk; BM25 over index lines; embeddings with heading-chain headers over the chunks; a graph only for time-changing multi-hop stores. Then check: are retrieval misses logged?
- How does an engineer read the store? Use: the digest, then the view for their role, then top-down from the project abstract or bottom-up from the chunk a ticket names; a view on request when the question is one feature or one use case. Then check: does the reader's path end at the chunk?
- How is a spec written? Use: the engineer asks for a view of the feature, then for a spec from that view when the feature is to be implemented, with every critical statement validated against a fact. Then check: does each critical statement in the spec link to a fact that still exists?
- Which harness feature should hold the store? Use: none; the harness's instruction file holds the root index and vendor memory is a cache. Then check: could the store move to another harness by copying a folder?
## Takeaways
1. A project knowledge base serves two readers, a coding agent that acts and an engineer who must understand the system, and nearly every published design serves only the first.
2. Nest folders for people, topic first and type last, so one folder holds a project's raw sources, facts and artifacts. A project is the folder and a feature is a set of pages inside it. Put a generated index in every folder, each line a real summary of what it points at, and add a level rather than lines when a project grows.
3. A fact is one chunk of a source, its original words beside a rewrite that reads on its own, with tables and figures as text. The original stays in the file so the rewrite can be read against it, and every statement in a page links to a fact.
4. Slice by complete thought, verified against the text by script, so a source of any length is processed by model calls of one size.
5. Keep the rewrite at the density of the original. Condensing lost up to half the answers on one benchmark.
6. Summaries are one level deep and live in the index files: one per chunk in the source's index, one per source in the project's index, one line per project at the root.
7. Views are what a person reads: a digest, a user view and a developer view for every project, and a view on request for any feature or question, each written from the summaries with the chunks opened where needed, each statement citing its fact.
8. An artifact is prose and links. Its path says what it is and its links say what it was built from. When a source changes, the update run follows the links backward and rewrites every dependent artifact in the same run.
9. Create is seven steps: fetch and convert, slice into facts, summarise each chunk, summarise the source, write the views, check each page, index. The model drafts and scripts check.
10. Check each page as it is written. Gates at every boundary cut surviving errors from 58.4 to 16.2 percent. A final check gained 2.3 points.
11. Update by inputs, never by date. Collect the dependents by script, rewrite them in the same run, stop where the meaning is unchanged, and check each hop. Age-based checks let 30 of 30 outdated plans through.
12. Retrieval is a ladder climbed on logged misses: the index files and progressive disclosure, BM25 over index lines, embeddings with heading headers, a graph last. Make the project index the agent's first read, because an agent that must choose to look often does not.
13. A person reads top-down or bottom-up through the same summaries the agent uses, and the project from the angle of their role in the views. The summary is a map. Reading that stops there measured as shallower knowledge.
14. A spec is written from a view of one feature, when the engineer decides the feature is to be implemented, and states what is required to be delivered. Every critical statement is validated against a fact. A full specification moved agent success from 56 to 89 percent.
15. A research store is the same tree without the specs and without a source list written in advance, with views per method, benchmark or question. Nothing here depends on a harness. Files, links and scripts move by copying a folder.
## References
- He et al. 2026. Is Progressive Disclosure All You Need for Long-Context Agents? arXiv 2607.17598.
- Zhou, Yu, Wei et al. 2026. Filesystem-Based Memory for LLM Agents: Organization, Evolution, and Sustainability. arXiv 2607.26637.
- Wu et al. 2024. ClashEval: Quantifying the tug-of-war between an LLM's internal prior and external evidence. arXiv 2404.10198.
- Retrieval as Reasoning: Self-Evolving Agent-Native Retrieval via LLM-Wiki. 2026. arXiv 2605.25480.
- Singh and Pawar 2026. The Hallucination Snowball. arXiv 2608.14588.
- Kuang et al. 2026. REAgent: requirement-driven issue resolution. arXiv 2604.06861.
- Chen, Wang, Brinton 2026. Fresh Memory, Stale Plans: Derivation Currency for Distributed LLM-Agent Memory (Planfence). arXiv 2609.03340.
- FinCacheServe 2026. Dependency-Consistent Answer Reuse for RAG Serving over Mutable Enterprise Documents. arXiv 2607.26076.
- Hammer et al. 2014. Adapton: composable, demand-driven incremental computation. PLDI 2014. Jane Street. Incremental, Cutoff documentation. ocaml.org.
- Salsa algorithm reference. salsa-rs.github.io. Microsoft. Excel recalculation. learn.microsoft.com.
- Structure-Aware Semantic Chunking with Title-Chain Prefixes. arXiv 2608.00824.
- Chroma 2025. Context Rot. trychroma.com/research/context-rot.
- Vercel 2026. AGENTS.md outperforms skills in our agent evals. vercel.com/blog.
- Luiten, Ames, Ackerson 1980. A meta-analysis of the effects of advance organizers on learning and retention. American Educational Research Journal 17(2).
- Chen, Kalyuga, Sweller 2017. The expertise reversal effect is a variant of the more general element interactivity effect. Educational Psychology Review. doi 10.1007/s10648-016-9359-1.
- Melumad and Yun 2025. LLM summaries versus web search. PNAS Nexus. doi 10.1093/pnasnexus/pgaf316.
- Chacón Sartori 2026. The Specification Gap: Coordination Failure Under Partial Knowledge in Code Agents. arXiv 2603.24284.
## 相关链接
- [Sergii Makarevych](https://x.com/sermakarevich)
- [@sermakarevich](https://x.com/sermakarevich)
- [11K](https://x.com/sermakarevich/status/2113681318852600222/analytics)
- [text.md](http://text.md/)
- [agents.md](http://agents.md/)
- [ocaml.org](http://ocaml.org/)
- [salsa-rs.github.io](http://salsa-rs.github.io/)
- [trychroma.com/research/context-rot](http://trychroma.com/research/context-rot)
- [AGENTS.md](http://agents.md/)
- [vercel.com/blog](http://vercel.com/blog)
- [Upgrade to Plus](https://x.com/i/premium_sign_up)
- [1:17 AM · Oct 24, 2026](https://x.com/sermakarevich/status/2113681318852600222)
- [11.9K Views](https://x.com/sermakarevich/status/2113681318852600222/analytics)
- [View quotes](https://x.com/sermakarevich/status/2113681318852600222/quotes)
---
*导出时间: 2026/10/26 09:59:22*
---
## 中文翻译
# 如何为 AI 编码代理和工程师组织项目知识
**作者**: Sergii Makarevych
**日期**: 2026-10-23T17:17:51.000Z
**来源**: [https://x.com/sermakarevich/status/2113681318852600222](https://x.com/sermakarevich/status/2113681318852600222)
**阅读**: 11914
**点赞**: 204
**转发**: 30
**回复**: 30
---
这就是我在咨询项目中管理项目知识库的方式。它帮助我更快地理解客户的文档和需求，也让自动化 AI 编码更快、更可靠，因为编码代理依据的是一份详细的规格说明，而当项目文档变化时，这份规格说明始终是最新的。简而言之：每份项目文档都被切分成可读的块，每个块都有一份摘要，摘要向上汇总为每个来源一份索引和每个项目一份索引，视图从摘要中写出，供读者或某个功能使用，当某个功能要实现时，再从视图写出规格说明，而每份摘要、视图和规格说明都链接到它所依据的块，因此当文档变化时，脚本会沿着链接找到基于它构建的一切，并在同一次运行中重写它们。读完之后，你将能够布置文件夹结构，定义事实和产物各自承载什么，运行创建工作流，把设计文档、工单和代码转化为经过检查的页面，运行更新工作流，把变化的需求传递到基于它构建的一切，选择搜索方法，选择穿过系统的阅读路径，并从同一存储中的视图写出编码代理所实现的规格说明。同一棵树，去掉两个部分，就能服务于从论文中学习研究领域的人，第 9 层说明了是哪些部分。每张图都来自公开论文、厂商文章或实践者的记述。
## 快速掌握
面向代理的项目知识库是一个文本文件文件夹。它保存关于一个系统的所有已知信息：设计文档、需求、决策、工单，以及解释行为的代码部分。有两类读者使用它。
- 语言模型，它根据找到的内容采取行动。它回答问题、编写代码并编写规格说明。
- 工程师，他需要理解这个系统。
几乎所有已发表的设计都把模型当作唯一的用户，而把工程师排除在外。本设计同时服务于两者。工程师必须能够从存储中学习系统，而他们读到的大部分内容不是存储的文档，而是模型从文档生成的摘要和视图。因此，这些生成页面的质量与文档本身同样重要。工程师还必须能够判断模型在材料上的表现如何，例如在项目文档上或某个需求上。这种判断以对模型输出的评估、测试或验证的形式进行，而编写这些需要理解。
全文使用一个术语。哈希是从文件内容计算出的短指纹。只要内容变化它就会变化，因此比较两个哈希就能在不读取内容的情况下看出某些东西是否发生了变化。
本设计是对一棵 Markdown 文件树的五种操作。
1. 存储。存储本身的形态：它保存哪些类型的文件，它们如何彼此分开，以及它们在磁盘上如何排列。其他一切都基于这个形态运作。
- 三类内容存放在不同的文件夹中，绝不混合：原始来源、事实和产物。
- 原始来源是原始材料，按捕获时的样子保存，从不编辑，通常以难以阅读的形式存在，例如 PDF。
- 事实是同一来源的可读形式。文本由工具转换，然后切分成每个都以完整思想结尾的块。每个块就是一个事实：原始片段，逐字保留，旁边是一个可独立阅读的重写版本，表格和图表被转化为文本。任何人都可以在一分钟内对照原文检查重写版本。
- 产物是模型从事实中总结或写出的一切。
- 每个事实都有一份摘要，从块写出。一个来源的摘要集中在该来源的索引中，每个块一行。项目的索引保存每个来源一份摘要，从块摘要写出，因此它是摘要的摘要，而存储顶部的索引保存每个项目一行。摘要只有一层深度。摘要之下是块本身。
- 视图是人阅读的产物。每个视图是从一个角度关于项目的一份文档，从摘要写出，在摘要不够的地方打开事实块，每个陈述都引用其事实。默认存在三个视图：摘要、用户视图和开发者视图。进一步的视图按需编写，针对一个功能、一个用例或一个问题。
- 规格说明是编码代理所实现的产物，仅存在于项目存储中。规格说明是一个视图转化为需要交付的内容，每个功能一份，在工程师决定要实现该功能时编写。其中的每个关键陈述都对照事实进行验证并链接到它，而规格说明链接到它所依据的视图，因此变化的需求会到达基于它的视图和规格说明。
- 每个产物都链接到它所依据的事实，而这些链接是唯一的记录。
- 文件夹是主题，而主题就是项目。功能是项目文件夹内的一组页面，而不是它自己的文件夹。每个项目文件夹保存自己的原始来源、事实和产物，并带有关于其中内容的简短摘要。
- 每个文件夹都有一个生成的索引：它的摘要，然后里面每样东西一行。每个索引都短到可以整体阅读，而增长的项目会获得更多层级，而不是更长的索引。
2. 创建。新材料如何进入存储：一份设计文档、一个需求页面、一个工单、一份决策记录、一个代码模块。项目的来源是预先已知的，因此每个项目文件夹保存一个来源文件，列出它们，并链接到每个来源被保存到的原始文件夹。一个来源进入。一个经过检查的事实文件夹以及基于它们构建的产物出来，位于树中的正确位置。
- 一个新来源经过一条固定的流水线，按此顺序。
- 流水线步骤 1：获取它，用工具将其转换为文本，并在来源文件中记录它。
- 流水线步骤 2：将文本切分成大小可控的块，每个都以完整思想结尾，并将每个块以可读形式存储在其原始文字旁边；这些就是事实。
- 流水线步骤 3：从每个块写出一份摘要，放入来源的索引。
- 流水线步骤 4：从块摘要写出来源的摘要，放入项目的索引。
- 流水线步骤 5：从摘要写出或刷新视图，在需要的地方打开块。
- 流水线步骤 6：在写入每个页面时检查它。
- 模型生成的一切在进入存储之前都要经过两道护栏。它们检查模型写的内容是否基于来源：
- 护栏 1：页面中的每个链接都必须指向存在的东西。
- 护栏 2：页面不得说出它所链接的事实没有说的内容。
- 第一个是纯代码。第二个是一次模型调用，只读取页面及其事实。每个块的原始文字与重写版本一起保存在存储中，因此任何检查都可以回到它们。
3. 更新。当一个事实变化时会发生什么，例如当一个项目需求被修订时。
- 更新在某个东西变化后运行，由人启动或按计划运行。
- 它重新获取来源，并将每个来源的哈希与来源文件中记录的哈希进行比较。变化的来源被再次转换和切分，其所有事实及其摘要被替换，基于该来源构建的一切在同一次运行中重建。
- 从每个变化的来源，它向后沿着链接，收集基于它构建的每个产物，无论是直接的还是通过另一个产物。这些产物在同一次运行中被自动重写，从最接近变化的开始。没有任何东西留给人去注意。如果重写的产物说的和之前一样，它上面的任何东西都不被触碰。修订的需求通常只改变一个页面的一句话，并让它上面的摘要保持原样。
- 每个重写的产物在从它重建上面的产物之前，都要经过与新产物相同的护栏，因此一个糟糕的重写不会向上传播。
- 一个新产物，一个以前不存在的产物，不是更新。它经过创建步骤。
4. 检索。代理通过渐进式披露找到它需要的东西：它在每一层读一点，只在问题指向的地方打开下一层。
- 索引文件是代理的起点。它读取项目索引，打开项目索引并读取来源摘要，打开来源索引并读取块摘要，然后打开问题指向的那一个块。
- 一旦有足够的信息它就停止。一个一千页的来源通过几次短读取就能到达，而代理读取包含细节的那一个块，而不是整个来源。
- 每次查找都被记录。关键词排序、嵌入和重排序器按此顺序添加，且仅在日志显示索引无法回答的问题时才添加。
5. 教学。存储让人更快地理解材料，因为同样的信息既以摘要形式存在，也以完整块形式存在，而且视图从读者需要的角度呈现它。
- 人可以自上而下阅读，从项目的摘要通过来源摘要到重要的块，或者自下而上，从一个块开始并向上攀升以了解它如何契合。哪种方式取决于偏好。两者都是几次短读取，而不是整个材料。
- 三个默认视图给三类读者各自的入口。摘要告诉任何人项目是什么、做什么。用户视图告诉使用系统的人它如何表现。开发者视图告诉改变系统的人它如何构建。为一个功能请求的视图在一个地方给出关于该功能的所有已知信息，来自许多来源。
- 每个视图都像任何其他产物一样。它链接到它所依据的事实和摘要，并在它们变化时由更新步骤重写，因此视图始终说出其来源所说的内容。
当系统的文档不断变化并被多次阅读、被多个工具阅读、或被必须学习它的工程师阅读时，使用这个。对于涉及几份文档的一次性问题，把文档放进提示中。
> 重要：在两项对派生内容的实测中，按记录的输入重建使每个计划和每个缓存答案都与其来源保持同步，而按年龄检查让 30 个过时计划中的 30 个通过，并让按时间键控的缓存提供了 46 个过时答案（arXiv 2609.03340, 2607.26076）。
> 这对我们意味着什么：每个产物都链接到它所依据的东西，而当来源变化时，更新运行沿着这些链接并在同一次运行中重写每个依赖产物。
> 为什么重要：代理信任它面前的页面。过时的页面在大多数时候会压过代理自己的知识，因此不允许任何页面等待重写。
## 核心思想
1. 原始文档产生事实，事实产生产物，三者链式相连。事实是原始文档的一个块的可读形式，原始文字保留在重写版本旁边。每个事实指向它来自的片段，每个产物指向它所依据的事实，因此当原始文档更新时，依赖它的一切也更新。
2. 不同角度的视图让人更容易消费信息，它们是功能规格说明的起点。读者可以自上而下从项目摘要开始，或自下而上从一个块开始，可以以摘要、用户或开发者的身份阅读项目，或孤立地阅读一个功能。规格说明从详述该功能的视图写出，因此它从关于该功能的当前事实开始，而不是从某人对它们的记忆开始。
3. 渐进式披露限制 token 消耗并支持自上而下的钻取，无论对模型还是对人。每一层一次读一点，只在问题指向的地方打开下一层。
4. 分块和摘要允许处理任何大小的文档。文档被切分成完整思想，每个块被单独重写和总结，来源的摘要从块摘要写出，因此没有单一步骤依赖于文档的长度。
5. 分层结构通过增加层级而不是让文档增长来保持巨大项目的可管理性。每个索引只覆盖一层，因此无论项目变得多大，每个索引都保持在模型或人可以整体阅读的大小。当一个文件夹超出该大小时，存储在其下增加一层，而不是一个更长的文件。
## 各层级
- 第 0 层。一次变化穿过整个存储。文件夹布局，以及一份需求文档从到达、经过视图和规格说明、到文档中一次变化的追踪。
- 第 1 层。树和索引。存储在磁盘上是什么样子，一个工作流如何填充它，事实、摘要、视图和规格说明是什么，以及代理和人如何阅读它们。四个部分：1.1 存储的形态，1.2 存储如何被填充，1.3 每个文件夹交付什么，1.4 代理和人如何阅读它。
- 第 2 层。事实。事实是什么，任何大小的文档如何被切分成事实，表格和图表如何变成文本，以及事实如何被替换。
- 第 3 层。产物。摘要、视图和规格说明，以及页面的路径和链接告诉脚本什么。
- 第 4 层。创建。将任何长度的来源转化为经过检查的页面的工作流，一步一步。
- 第 5 层。更新。来源变化后会发生什么：检测变化，由脚本收集依赖项，在同一次运行中重写它们，提前停止，检查每一跳。
- 第 6 层。检索。通过索引文件的渐进式披露，普通搜索何时不再足够，以及代理是否真的查看。
- 第 7 层。人的阅读路径。自上而下或自下而上阅读摘要和块，以及三个默认视图。
- 第 8 层。规格说明。从视图写出并对照事实验证的规格说明，谁决定何时，以及规格说明的完整性决定代理成功的证据。
- 第 9 层。研究变体和运行框架。论文存储有什么变化，以及更换运行框架后什么仍然成立。
- 决策指南、要点和参考文献。
## 第 0 层。一次变化穿过整个存储
这一层回答：存储的各个部分是什么，以及一份需求文档从进入存储到基于它构建的规格说明会发生什么？
一个典型项目的文档分布在几个地方。
- 设计评审的幻灯片和 PDF。
- 诸如 Confluence 之类 wiki 中的需求页面。
- git 仓库中的设计笔记、决策记录和 README。
- 改变了行为的工单，以及代码本身。
这些文档形成一条链，即使没有人画出来。
1. 需求说明系统必须做什么。
2. 设计决策说明团队选择如何做以及为什么。
3. 规格说明说明要交付什么，详细到足以让代理实现它。
存储让这条链显式化。每个视图和每个规格说明都指回它来自的事实。当需求变化时，更新运行自动重写基于它的视图和规格说明。产物始终与其所依据的事实保持最新。第二种存储，即一个人为从论文中学习研究领域而构建的存储，在几个地方有所不同。第 9 层列出了它们。
存储是一棵文件夹树，按项目组织。每个项目获得一个文件夹，包含三个固定子文件夹：raw、facts 和 artifacts。
- raw - 保存来源的原始捕获形式，无论它们以什么格式到来。没有人编辑它们。
- facts - 保存每个来源的可读形式：工具转换后的文本，每个块一页，包含原始片段和一个可独立阅读的重写版本，每个表格和图表作为图像并附有文本版本，以及一个索引，每个块一份摘要。
- artifacts - 保存代理从这些事实写出的一切：将项目呈现为摘要、面向用户、面向开发者或围绕一个功能的视图，以及当功能要实现时从这些视图写出的规格说明。
每个文件夹都带有一个生成的索引文件。存储的顶部只保存这样的索引，它列出项目。项目的索引以项目的摘要开头，然后给出每个来源一份摘要，从该来源的块摘要写出，然后每个文件夹一行。facts 下每个来源的索引按来源顺序给出每个块一份摘要。项目文件夹还保存一个来源文件，列出项目的来源并将每个链接到其原始文件夹。
关于一个项目的一切都放在一个文件夹中，人可以打开、移动或分享。内容类型是路径的最后一环。代理读取索引文件，每个索引说明其文件夹保存什么。
```
kb/
index.md 生成的：项目列表，每个一行
<project>/
index.md 生成的：项目摘要，每个来源一份摘要，每个文件夹一行
sources.yml 项目的来源，每个链接到其原始文件夹
raw/<source>/ 完全按获取时的样子，内容哈希，从不编辑
facts/<source>/ 来源的可读形式：转换后的文本，每个块一页，图表作为文本
index.md 每个块一份摘要，按来源顺序
artifacts/ 从事实写出的一切
views/ 摘要、用户、开发者，以及任何按需编写的视图
specs/ 每个功能一份规格说明，从其视图写出
```
一份需求文档进入存储。有人完成了一份需求文档的新版本，并将其添加到它所描述项目的来源文件中。然后创建工作流运行。
1. 它获取文档，对其进行哈希，将其存储在该项目的 raw 子文件夹中，并在来源文件中记录该文件夹和哈希。一个工具将其转换为纯文本和页面图像，放在 facts 子文件夹下。此时还没有模型触碰任何东西。
2. 它将文本切分成每个都以完整思想结尾的块。对于每个块，它写一个事实页面：原始片段，然后是一个可独立阅读的重写版本，该片段中的表格和图表被转化为文本。
3. 它从每个块写出一份摘要到来源的索引，然后从这些摘要写出来源的摘要到项目的索引。
4. 它从摘要写出或刷新摘要、用户和开发者视图，在摘要不够的地方打开块。视图中的每个陈述都链接到它来自的事实，而脚本检查每个链接都能解析。
5. 它在项目的索引中为来源添加一行，如果是新项目，则在根索引中为项目添加一行。
这是链的第一部分。一份文档变成了事实，而事实变成了摘要和视图，每个都链接到它所依据的事实。
一个功能被开发。工程师向代理请求一个功能的视图，例如关于系统某一部分的每个需求，从整个存储的事实中提取。
1. 视图作为产物写出。它是存储关于该功能所知内容的狭窄而详细的集合，每个陈述都链接到它来自的事实。
2. 工程师阅读视图而不是文档。当功能要实现时，工程师请求从该视图写出的规格说明。规格说明陈述需要交付的内容。
3. 规格说明中的每个关键陈述都对照事实验证并链接到它。
4. 编码代理从规格说明实现。
视图和规格说明像任何其他产物一样。当它们背后的需求变化时，更新运行重写它们。
一个需求变化。后来文档被修订，其中一条规则改变。工程师启动更新工作流。
1. 它重新获取项目来源文件中列出的每个来源，发现一个原始哈希变化了。
2. 它再次转换和切分该文档，并替换其所有事实及其摘要。版本控制保留之前的。
3. 一个脚本收集链接到该文档事实的每个页面，以及链接到那些页面的一切：项目索引中来源的摘要、引用这些事实的视图，以及引用它们的规格说明。运行的其余部分按顺序重写它们。
4. 来源的摘要首先重建。它得出的含义相同，因此它上面的项目摘要保持原样。
5. 视图和规格说明被重建，因为它们受影响的章节引用了变化文档的事实，每个都对照其事实检查。
6. 规则所依据的决策记录是单独的来源，其哈希没有变化，因此它们的事实保持原样。重建的规格说明引用修订的需求和未变的决策。
存储的用途。视图让人或代理快速消费项目知识的一个切片，而无需阅读它来自的文档。当功能要实现时，从该切片写出规格说明，编码代理从规格说明实现。下面的每个机制都服务于这两个目的之一。
要点传承
- 主题在每个路径中优先：项目是一个文件夹，功能是其中的一组页面。每个项目文件夹保存 raw、facts 和 artifacts，其中视图和规格说明在 artifacts 内，外加一个来源文件和一个以项目摘要开头的索引。存储的顶部只有项目索引。
- 一个来源变成事实，每个块一个，保留其原始文字，而事实变成摘要和视图。每个页面链接到它所依据的东西，脚本在更新需要时从这些链接推导出反向映射。
- 视图是人阅读的切片，也是规格说明写出的输入。工程师请求视图，并在功能要实现时请求规格说明。
- 变化的需求通过哈希检测。同一次运行向后沿着链接并重写基于它构建的一切，最近的优先，在含义未变的地方停止。
## 第 1 层。树和索引
这一层回答：存储在磁盘上是什么样子，它如何被填充，每个文件夹交付什么，以及代理和人如何阅读它？
1.1 存储的形态
存储是一棵 Markdown 文件的文件夹树。自上而下读，它有三层。
- 存储的顶部只保存一个生成的索引，列出项目，每个一行。
- 下面每个项目一个文件夹。每个项目文件夹保存一个生成的索引，以项目的摘要开头并给出每个来源一份摘要，一个来源文件列出项目的来源并将每个链接到其原始文件夹，以及三个固定子文件夹：raw、facts 和 artifacts。
- 在项目内，每个来源在 raw 下有一个文件夹，保存它完全按获取时的样子，在 facts 下有一个文件夹，保存它的可读形式：工具的文本转换，每个块一页，其表格和图表作为图像并附有文本，以及一个索引，每个块一份摘要。artifacts 文件夹保存模型从事实写出的一切，分两个子文件夹：views，人阅读的文档，和 specs，编码代理所实现的文档。
下面是一个有一个项目和一个来源的存储，完全展开。
```
kb/
index.md 生成的：项目列表，每个一行
<project>/
index.md 生成的：项目摘要，每个来源一份摘要，每个文件夹一行
sources.yml 项目的来源：url 或路径，获取方法，最后哈希，原始文件夹
raw/
index.md 每个来源一行
<source-id>/
original.pdf 完全按获取时的样子，无论什么格式
meta.yml url，获取日期，sha256
facts/
index.md 每个来源一行
<source-id>/ 来源的可读形式
index.md 每个块一份摘要，按来源顺序，每个链接到其页面
text.md 整个来源的一次工具转换，哈希，无模型
pages/p-004.png 固定分辨率的页面图像
figures/table-03.png 从页面图像中切出的表格或图表
figures/table-03.md 其文本形式：表格作为 Markdown，或带所示值的描述
<chunk-slug>.md 一个事实：原始片段，然后是独立阅读的重写版本
artifacts/
index.md 视图和规格说明各一行
views/
index.md 每个视图一行
digest.md 项目是什么、做什么，面向任何人
user.md 系统如何表现，面向使用它的人
developer.md 系统如何构建，面向改变它的人
<feature-or-question>.md 按需编写的视图，围绕一个功能、用例或问题
specs/
index.md 每条规则一行
<feature>.md 每个功能一份规格说明，在实现时从其视图写出
```
1.2 存储如何被填充
树中除原始文件外没有任何东西是手写的。一个工作流，在第 4 层逐步描述，填充其余部分。对于每个来源，它大致这样运行。
1. 获取和转换。来源被完全按找到的样子复制到项目的 raw 文件夹，哈希，并在来源文件中记录。一个工具，而不是模型，将其转换为纯文本和页面图像，放在 facts 文件夹下。
2. 切分成事实。文本被切分成每个都以完整思想结尾的块。每个块变成一个事实页面：原始片段，逐字，下面是可独立阅读的重写版本，该片段的表格和图表被转化为文本。第 2 层描述切分。
3. 总结每个块。模型从每个块写出一份简短摘要。摘要进入来源的索引，每个块一份，按来源顺序，每个链接到其事实页面。
4. 总结来源。从块摘要，模型写出来源的一份摘要，该摘要成为来源在项目索引中的条目。该索引顶部的项目摘要在其变化时从来源摘要重写。
5. 写出视图。从这里开始写的每个页面都链接到它所依据的东西，而这是依赖关系的唯一记录。从摘要，模型写出或刷新摘要、用户和开发者视图，在摘要不够详细的地方打开事实块，并为每个陈述按路径引用一个事实。
6. 检查每个页面。每个页面在写入时都被检查，先由脚本，然后由一次模型调用，然后才从它构建下一个页面。
规格说明是这次运行不产生的唯一产物。它们在工程师请求时写出，从详述该功能的视图。第 8 层涵盖它们。
1.3 每个文件夹交付什么
四类东西从该工作流出来，每个在树中都有自己的位置。
事实。facts 下每个来源一个文件夹，保存来源的可读形式，仅此而已。它有整个来源的工具文本转换，每个块一页，以及一个 figures 文件夹，来源中的每个表格和图像都作为图片存在，旁边有文本版本。一个事实页面有一行命名它来自的原始页面，原始片段，以及一个可独立阅读的重写版本。事实是代理在需要摘要背后的细节时读取的单元。第 2 层涵盖它们。
摘要。一层，存储在索引文件中。来源的索引保存每个块一份摘要。项目的索引保存每个来源一份摘要，从块摘要写出。根索引保存每个项目一行。任何类型的读者通过这三个步骤了解一个来源，只在问题需要时打开一个块。
视图。人阅读的文档，在 views 文件夹下。项目树很好地回答一类问题：关于这个项目的材料在哪里？它糟糕地回答另一类：这个项目做什么，对用户如何表现，如何构建，关于这一个功能已知什么？视图回答第二类。要写一个视图，模型读取摘要以找出哪些事实对该角度重要，在摘要不够的地方打开那些事实块，并为该角度写一份文档，每个陈述都引用其事实，无论该事实在哪里。默认写三个视图：摘要、用户视图和开发者视图。任何进一步的视图按需编写：针对一个功能、一个用例或一个问题，它可以借鉴多个项目。每个视图在它所链接的任何东西变化时由更新步骤重建，没有一个是手写的。
规格说明。一个视图转化为需要交付的内容，每个功能一份规格说明，在 specs 文件夹下，在工程师决定要实现该功能时编写。其中的每个关键陈述都对照事实验证并链接到它，而规格说明链接到它所依据的视图。第 8 层涵盖它们。
1.4 代理和人如何阅读它
每个文件夹的索引描述该文件夹，然后列出里面的东西，因此读者可以在任何深度停止。
- 根索引列出项目。
- 项目索引给出项目的摘要和每个来源一份摘要。
- 来源的索引给出每个块一份摘要。
- 下面是块本身。
这就是渐进式披露：在每一层读一个短索引，只在问题指向的地方打开下一层。
代理和人以不同方式使用树。
- 代理从任务所指项目的索引开始，或在不知道项目时从根索引开始。它读取来源摘要，选择一个来源，读取其块摘要，并打开包含细节的那一个块。它在回答问题的第一层停止。当没有一行合适时，它按关键词搜索每个索引文件，而不是猜测。
- 人主要阅读视图。摘要、用户视图和开发者视图从三个角度给出项目，而请求的视图在一个地方给出关于一个功能的一切。只有当问题需要细节时，他们才沿着视图的链接向下到一个块，或从工单所指的块开始并向上攀升通过摘要以了解它所在的位置。
> 重要：在一项关于代理如何导航文件的受控测试中（He 等，arXiv 2607.17598），每文件一行的索引得分为 0.462，而原始文件为 0.257，而带有误导性组摘要的第二路由层降至 0.267，因为代理选错了组且再也没有回来。
> 这对我们意味着什么：每个文件夹都有一个索引，每行都是它所指向内容的真实摘要，每个索引都短到可以整体阅读，并以跨所有索引文件的搜索作为从错误转向中返回的方式。
> 为什么重要：当嵌套索引的摘要糟糕或其层级很长时，它会失败。本设计用每个索引行上的真实摘要和短到可以整体阅读的索引来为深度付出代价。
要点传承
- 每个文件夹都有一个生成的索引：它的摘要，然后里面每样东西一行。代理一次一个短索引地下降，当没有一行合适时搜索所有索引文件。人主要阅读视图，只在需要细节时向下到一个块。
- 一个工作流从原始文件填充树：转换、切分成事实、总结每个块、总结来源、写出视图、检查每个页面。规格说明按需从视图写出。
- 摘要只有一层深度并存在于索引文件中：块摘要在来源的索引中，来源摘要在项目的索引中，根处每个项目一行。
- 三个默认视图，摘要、用户和开发者，加上任何按需编写的视图。每个都是重建的产物，其链接可以到达多个项目。
## 第 2 层。事实
这一层回答：什么是事实，任何大小的文档如何被切分成事实，表格和图表会发生什么，以及事实如何变化？
事实是原始来源的可供代理阅读的形式：Markdown 而不是 PDF、扫描件或电子表格，并且分块以便更简单地处理和消费。流水线步骤一次处理一个块而不是整个文档，而代理读取问题指向的那一个块而不是整个来源。每个块是一个事实页面，有两部分。原始片段由脚本逐字复制进来，并保持转换时的样子。旁边模型写一个可独立阅读并保留该片段事实的重写版本。原文是记录，重写版本是它的可读形式，因为两者在同一个文件中，重写版本可以随时由人、模型或脚本与原文比较。来源哈希决定事实何时被替换。
事实页面。每个事实是 facts 下来源文件夹中的一个 Markdown 文件，以其内容的短 slug 命名。顶部一行说明它来自哪里：原始文档的页面和转换文本中的行范围。然后是原始片段，逐字，然后是重写版本。
- 第一行：Source: original.pdf, pages 12 to 14. text.md lines 410 to 468.
- 一个标题 Original，然后是片段逐字，按工具转换的样子。
- 一个标题 Rewritten，然后是相同内容，可独立阅读。
路径标识文件，来源哈希跟踪其变化。Original 部分由脚本从转换文本复制。Rewritten 部分是读者使用的：每个代词和回指都被解析，使块可独立阅读，片段中的每个表格或图表都从页面图像转录为文本。来源的索引按来源顺序列出每个事实及其页面范围和摘要。
任何大小的文档如何被切分。模型无法一次读完一份 300 页的功能需求文档，而按固定大小切割会落在论证中间，把结果与使其成立的条件分开。因此转换后的文本按含义切分，而不是按数量。
- 一个窗口在光标处打开，逐句增长到约 2,000 token 的下限。模型被问一个问题：这个窗口是否以完整思想结尾，如果不是，哪一句是最后一句？它必须逐字用那句话回答。脚本检查该句出现在转换文本中，重试一次，否则回退到最后一个句子边界。窗口上限约为 4,000 token，因此一个冗长的章节不能使运行停滞。
- 块的原始片段由脚本复制到事实页面。然后模型写重写版本，并从中写一到两句摘要和一个成为文件名的内容 slug。
- 每次调用在固定的 token 预算下看到前一个块、到目前为止的块摘要和手中的块。模型从不看到整个文档，这正是使该步骤对长度不敏感的原因：一份两页的架构决策记录和一份 600 页的设计文档由相同大小的调用处理。
- 运行在每个块之后保存检查点，因此在第 400 页中断的运行从第 400 页恢复。
表格和图表。文本转换会压平表格并丢失图表和示意图。因此来源的每一页也以固定分辨率渲染为图像，每个表格、图表和示意图都从其页面切出到 figures 文件夹作为图片。视觉模型在每个旁边写一个文本文件：表格变成 Markdown 表格，图表变成带所示值的描述，示意图变成其部件和它们之间箭头的列表。片段包含该图的事实链接到文本文件并在重写版本中包含其内容，因此事实的读者无需打开图像就能看到表格。图片被保留是因为文本可能出错，也因为图像被模型读取一次而其文本被读取多次。
重写版本可独立阅读。重写版本是块转化为可读形式。代词和隐含引用被解析，在块突然开始的地方添加一行框架，片段的数字、名称和日期以相同密度保留，除了片段及其上下文之外不添加任何东西，片段的表格和图表从页面图像转录。Filesystem-Based Memory 研究是保持密度的原因。将代理的文件移入文件夹而不编辑它们，在 LoCoMo 对话基准上得分为 86.1，与经过多轮重写整理的存储相同。一个丢弃细节的压缩重写在那里得分为 79.1，在第二个基准上为 41.2，而其他每个变体得分为 77.6（arXiv 2607.26637）。组织不损失准确性。压缩最多损失一半的答案。原始片段保留在同一文件中，以便重写版本可以对照它阅读，而产物中的每个陈述都链接到其事实，以便产物也可以对照原文阅读。
来源哈希。来源文件为每个来源保存一个哈希。当来源被再次获取且其哈希不同时，它被再次转换和切分，其所有事实及其摘要被替换，而链接到它们的每个页面在同一次运行中被重写。版本控制保留之前的事实。没有模型就地编辑事实，也没有事实在其来源仍被列出时被移除。项目的需求很少且有意地变化，因此重建基于变化文档构建的一切是正确的默认，而第 5 层的同义停止防止重建攀升得超过必要。
> 重要：一个文件被组织但保持原样的存储在 LoCoMo 基准上得分为 86.1，与整理过的存储相同，而压缩重写在那里得分为 79.1，在第二个基准上为 41.2，而其他每个变体得分为 77.6（arXiv 2607.26637）。
> 这对我们意味着什么：重写版本使块可读并以相同密度保留其内容，而原文保留在同一文件中它旁边。
> 为什么重要：压缩是存储丢失答案的地方，而一个可以对照原文阅读的重写版本是任何人都可以检查的重写版本。
要点传承
- 事实是一个块：一行命名它在原文中的页面，原始文字，以及一个可独立阅读的重写版本。表格和图表作为图片与文本一起存在于它旁边。来源的索引列出每个事实的页面及其摘要。
- 切分使每个块以完整思想结尾，由脚本对照文本验证，因此一份两页的笔记和一份 600 页的文档由相同大小的调用处理。
- 变化的来源整体替换其事实及其摘要，版本控制保留旧的。每个重写版本旁边的原文是任何读者比较的对象。
## 第 3 层。产物
这一层回答：代理写的页面必须携带什么才能被信任和重建，以及产物有哪些种类？
产物是模型从事实写出的任何东西。本设计有三种。
- 摘要。每个块一份，从块写出，存储在来源的索引中。每个来源一份，从块摘要写出，存储在项目的索引中。项目的摘要和根索引行再次压缩。
- 视图。每个角度一份文档。摘要、用户视图和开发者视图为每个项目存在。进一步的视图按需编写，针对一个功能、一个用例或一个问题。模型读取摘要以找出哪些事实重要，在摘要不够的地方打开事实块，并为那一个角度写文档。
- 规格说明。一个视图转化为需要交付的内容，在功能要实现时按需编写，每个关键陈述都对照事实验证。
产物制作成本低而信任成本高，因此其中的每个陈述都内联链接到它来自的事实，而视图或规格说明可以逐行读回来源。
页面是什么。页面是散文和链接，而树中的三样东西告诉脚本关于它所需的一切。
- 它的路径说明它是什么。views 下的页面是其文件名所指的视图。specs 下的页面是其文件名所指功能的规格说明。摘要位于它所总结文件夹的索引中。
- 它的链接说明它依据什么构建。摘要向下链接到它下面的块或块们。视图链接到它借鉴的事实和摘要，无论它们在哪里。规格说明链接到它所依据的视图以及每个关键陈述背后的事实。需要知道基于一个页面构建了什么脚本会找到链接到它的每个页面，这只需几秒钟且不消耗模型 token。
- 来源文件说明来源何时变化。该文件为每个来源保存一个哈希。当重新获取发现不同的哈希时，基于该来源构建的每个页面都被重写。
依赖产物自动更新。更新运行重新获取每个来源并将其哈希与来源文件中的哈希比较。对于每个变化的来源，它替换事实及其摘要，向后沿着链接到基于它们构建的每个页面，并在同一次运行中重写那些页面，最接近变化的优先。因此，存储中的新文档，或它的新版本，意味着在该运行结束时产生新的摘要、新的视图和新的规格说明，没有由人决定重做哪些页面的步骤。重写必须是自动的，因为代理相信它们面前的东西。
- 在超过 1,200 个问题中，模型在超过 60% 的情况下用不正确的检索段落替换了它们已经知道的正确答案（ClashEval, arXiv 2404.10198）。
过时的页面会覆盖真相，因此存储绝不在检测到变化的运行之后保留过时页面。
全程 Markdown。代理和人阅读相同的 Markdown 文件。Markdown 密集、易于 diff，并可在任何编辑器、git 主机或 wiki 渲染器中阅读，因此一种格式服务于两类读者，没有任何东西被构建两次。
要点传承
- 三种产物：摘要、视图和规格说明。页面是散文和链接：路径说明它是什么，链接说明它依据什么构建，来源文件说明来源何时变化。
- 当来源变化时，更新运行向后沿着链接并在同一次运行中重写每个依赖产物。代理在大多数时候用过时文本覆盖自己的知识，因此没有页面等待。
- 一种格式，Markdown，服务于两类读者。
## 第 4 层。创建
这一层回答：当新来源到达时，按顺序会发生什么，以及脚本在哪里代替模型做决定？
创建是填充存储的操作。它需要固定的形态，因为错误在这里进入并在之后复合。模型起草一切，而脚本在从它构建下一个之前检查每个页面。
步骤 1。获取和转换。在项目存储中，来源首先被添加到它所属项目的来源文件中，带有其位置和获取方法。创建工作流和更新工作流然后读取同一个列表。来源被获取、哈希并完全按捕获的样子保存到该项目的 raw 子文件夹，无论什么格式，且再也不被触碰。然后一个工具将其转换为纯文本并将每一页渲染为固定分辨率的图像，两者都在 facts 下来源的文件夹中。转换中不涉及模型，因此文本可以对照页面图像检查，页面图像可以对照原文检查。
步骤 2。切分成事实。转换后的文本按第 2 层的方法切分成每个都以完整思想结尾的块，每个块变成一个事实页面：原始片段由脚本复制，重写版本由模型写出且可独立阅读，该片段的表格和图表从它们的图像转化为文本。完整思想边界在这里最重要：条件位于前一个块的块是重写版本会出错的块。模型此时还不写关于来源的散文。保留每个块的全文，只在之后写页面，是让之后每个句子都能指向可检查锚点的原因。
步骤 3。总结每个块。从每个重写版本，模型写一到两句摘要和一个命名文件的内容 slug。摘要进入来源的索引，按来源顺序，每个链接到其事实页面。每次调用在固定预算下看到手中的块和到目前为止的摘要，因此任何长度的来源都由一种大小的调用总结。
步骤 4。总结来源。从块摘要，模型写出来源的一份摘要，它成为来源在项目索引中的条目，而该索引顶部的项目摘要从来源摘要重写。自下而上写意味着摘要链接的一切在摘要之前存在，因此步骤 6 的链接检查可以在它写出的那一刻运行。
步骤 5。写出视图。从摘要，模型写出或刷新摘要、用户视图和开发者视图。对于每个，它读取项目的摘要以找出对该角度重要的事实，在摘要不够详细的地方打开事实块，并写出每个陈述都按路径引用其事实的文档。按需编写的视图，针对一个功能或一个问题，在被请求时以相同方式产生。
步骤 6。在写入每个页面时检查它。每个页面两次检查，按顺序。
- 脚本检查每个链接都能解析并指向存在的事实或页面。失败时它用失败列表重试模型，最多固定次数。在一个由模型在三个多跳问题集上编译的 wiki 中，悬空链接占所有结构错误的 29% 到 64%（arXiv 2605.25480）。
- 一次模型检查对照页面所链接的事实和页面读取页面，仅此而已，并回答一个问题：页面是否说了它们没有说的任何东西？
每页的时机遵循多阶段生成的实测行为。
- 在一个四阶段流水线中，随着阶段推进，越过每个边界的错误份额分别为 24.6%、48.3% 和 89.3%。每个边界的门控将存活到最后的错误从 58.4% 降至 16.2%，而最后的一次检查只获得 2.3 个百分点（arXiv 2608.14588）。
- 在检查可以作为代码运行的地方，就运行它：一个需求重写代理在每条需求必须通过十个生成的测试时解决了 100 个问题中的 46 个，而当 LLM 评判者取代测试时解决了 34 个（arXiv 2604.06861）。
只在最后检查的流水线是一条打磨其错误的流水线。
步骤 7。索引。来源在项目的索引中获得其行，如果是新项目，项目在根索引中获得其行。存储中没有任何东西被就地编辑：重建的页面整体替换其前身，而版本控制保留前身。
> 重要：每个阶段边界的门控将四阶段流水线中存活的错误份额从 58.4% 降至 16.2%，而单次最终检查只将其改善 2.3 个百分点，且可执行检查在同一任务上以 46 比 34 胜过模型评判者（arXiv 2608.14588, 2604.06861）。
> 这对我们意味着什么：在写入每个页面时检查它，先脚本后模型，绝不依赖对完成存储的审查。
> 为什么重要：创建流水线是决定之后每个页面真相的地方，而晚期检查无法发现早期的误读。
要点传承
- 七个步骤：获取和转换、切分成事实、总结每个块、总结来源、写出视图、检查每个页面、索引。
- 模型在步骤 2 到 5 起草。脚本在步骤 1、6 和 7 决定。任何长度的来源都以一种大小的窗口读取。
- 每个页面在写入时都被检查，先链接检查然后一次模型调用，然后才从它构建下一个页面。
## 第 5 层。更新
这一层回答：当来源变化时，基于它构建的页面会发生什么，按什么顺序，以及为什么不简单地重建一切？
每当来源以不同的哈希被再次获取时，更新步骤运行。它是一个脚本，模型只在重写时被调用。四个步骤，每个回答一个不同的反对意见。
步骤 1。由脚本收集依赖项。对于每个变化的来源，脚本取其事实文件夹及其摘要，然后取链接到它们的每个页面，然后取链接到那些的每个页面，直到找不到新的。另一个项目中链接到该来源事实的页面像任何其他页面一样被收集，因此遍历跨越项目而无需特殊处理。这只需几秒钟且不消耗模型 token。这就是电子表格在一个单元格变化后找到要重新计算的单元格的方式，也是 Adapton 等增量构建系统找到要重建内容的方式：遍历成本低且沿着每个链接，因此它被完整地完成。它回答的反对意见来自第 3 层。过时的页面在大多数时候覆盖真相，因此要重写的页面集合必须来自链接，绝不来自某人记得哪些页面提到了该主题。
步骤 2。在同一次运行中重写它们。更新工作流由人在一批变化后启动，或按计划启动。它检测每个变化的输入，收集所有输入的依赖项，并在一次遍历中重写整个集合。按批次而不是按变化运行它很重要，因为每次重写都消耗模型 token 并且是引入错误的机会。对一份文档的多次变化应该产生每个依赖项的一次重写，而不是每次变化一次重写。除了护栏拒绝的内容，没有任何东西交回给人。
步骤 3。提前停止。最接近变化的页面首先重建。如果它的新文本含义与旧的一样，重建在那里停止，它上面的每个页面保持原样。这是 Salsa 和 Jane Street Incremental 构建系统的提前截断规则，有一个变化：比较不是精确文本而是相同含义。一个廉价的分类器以概率回答是或否，而精确文本匹配是免费的第一遍。回答的反对意见是成本。修订的需求通常只改变一个页面的一句话，并让它上面的来源摘要说同样的话，因此大多数更新在一层之上结束。
步骤 4。检查每一跳。每个重建的页面在从它重建上面的下一个页面之前，都要经过第 4 层的两次每页检查。错误通过阶段复合，而第 4 层的流水线测量是原因：不检查时，超过一半的早期错误存活到最后，而只有每个边界的门控才能将其降至约六分之一。从不受检查的重建摘要重建的视图继承其错误并在高一层隐藏它。
为什么按输入重建而不是按日期检查。两个系统恰好在这个选择上被测量过。
- Planfence 给一个代理链提供从共享记忆派生的计划，并测试它们是否注意到该记忆何时变化。按年龄检查计划让过时计划在 30 个五代理工作流中的 30 个通过，且没有一个完成。从其记录的输入重建它让没有一个通过并完成了全部 30 个，每个任务多约 15% 的 token（arXiv 2609.03340）。同一研究为检查每一跳提供了理由。一个只刷新第一个代理的对照在 30 次运行中的 28 次选择了正确动作，但仍然完成 0/30，因为它之后的代理依据旧计划工作。
- FinCacheServe 将缓存答案键控到它们所用证据的哈希。它跳过了 53% 的模型调用且没有提供过时答案，而按时间键控的缓存在 208 请求压力测试中提供了 46 个过时答案（arXiv 2607.26076）。
> 重要：从其记录的输入重建派生计划使 30 个中的 30 个工作流与变化保持同步，而按年龄检查它们让过时计划在全部 30 个中通过（arXiv 2609.03340）。
> 这对我们意味着什么：从每个变化的来源向后沿着链接到基于它构建的每个页面，并在同一次运行中重写它们，在含义不变的地方停止。
> 为什么重要：完全重建消耗 token 并增加错误，而把页面留给人去注意意味着代理阅读过时页面并相信它们。
要点传承
- 由脚本通过链接完整地收集依赖项。
- 在检测到变化来源的同一次运行中重写它们。当重建的页面含义与之前相同时停止。在下一个之前检查每一跳。
- 要重写的页面集合来自来源哈希和链接。
## 第 6 层。检索
这一层回答：代理如何找到正确的块，读取索引文件何时不再足够，以及你如何知道代理是否真的查看了？
组织这一层的问题是每个正确答案的成本，而不是召回率。这些方法形成一架梯子，每一级只在下一级的记录失败证明其合理时才添加。
第一级：索引文件和渐进式披露。任务所指项目的索引是代理的第一次读取，或在项目未知时是根索引。每个索引都短到可以整体阅读。代理以逐渐增大的步骤吸收材料。
1. 项目的摘要及其每个来源一份摘要。
2. 所选来源的索引，每个块一份摘要。
3. 包含细节的那一个块。
它在回答问题的第一步停止，因此大多数查找花费几百个 token 和几次小读取。当索引中没有一行合适时，代理按关键词搜索每个索引文件，这按需给它页面的扁平列表，并从命中处下降。Filesystem-Based Memory 研究发现，将文件放入文件夹在大型存储规模下将每次查询成本降低约 60% 而不改变准确性（arXiv 2607.26637）。一个几千块且每个索引行都有真实摘要的存储不需要更多。
第二级：对索引行进行关键词排序。当对索引文件的关键词搜索返回太多行时，BM25 索引对它们排序。BM25 是一种标准的关键词排序方法，不需要模型调用。它建立在索引行之上，因此它匹配的是每个块的摘要，这就是为什么那些行必须是真实摘要而不是标题。
第三级：嵌入和重排序器。仅当日志显示查询用页面不使用的词表述时才添加这些。索引事实块，并在每个前面加上标题链：来源、章节、小节。仅该标题就在一个 196,000 块的 Markdown 语料库上将排序分数提高约 24%，无需模型调用（arXiv 2608.00824）。检索一个小预算，因为长上下文会退化。Chroma 对 18 个模型的上下文腐烂测量发现，模型在固定问题上的准确性随着无关 token 的添加而下降。
第四级：图。仅用于许多事实随时间变化且问题在它们之间跳跃的存储。这种项目存储不需要它。
代理会查看吗？没有人预算的检索失败是代理根本不搜索。Vercel 发现，一个放在始终加载文件中的 8 KB 压缩索引通过了每个评估案例。同样的内容作为按需技能提供时通过了 53%，并不比没有文档更好，因为该技能在 56% 的情况下从未被调用。本设计的答案是结构性的。项目索引是代理的第一次读取且到达成本为零，而不是藏在代理必须选择调用的工具后面。检索被记录，而未命中的日志决定是否构建下一级。
要点传承
- 索引文件和渐进式披露承载数千个块：项目摘要、来源摘要、块摘要、块。在索引行上添加 BM25，然后带标题链头的嵌入，然后图，每个只在记录的失败上添加。
- 让项目索引成为代理的第一次读取且到达成本为零。必须选择查看的代理常常不查看。
## 第 7 层。人的阅读路径
这一层回答：是什么让存储比它所依据的文档更快地供工程师学习？
工程师阅读与代理相同的树。树的两个属性使它比一个设计文档文件夹更快地学习。第一，每条信息存在两次，作为摘要和作为完整块，上面有来源摘要和项目摘要。第二，相同的事实从视图中的多个角度呈现。两个属性已经为代理存在，因此保持它们不花费额外成本。
两个方向。每个项目带有摘要，每个来源一份摘要，每个块一份摘要及其全文。这给出两条阅读路径。
- 自上而下从项目摘要开始，向下到来源摘要，然后到块摘要，然后到块，并在读者有足够信息的地方停止。这是新手的路径。在材料之前阅读的大纲，学习文献称之为先行组织者，在 Luiten 对 Ausubel 工作的元分析中有适度帮助。
- 自下而上从工单或问题指向的块开始，阅读它，并攀升到摘要以了解它所在的位置及其邻居是什么。这条路径必须存在，而摘要必须可跳过，因为给专家新手脚手架会拖慢他们。Kalyuga 称之为专业知识反转效应。
一个人走哪条路径取决于偏好和先验知识，而存储不应该替他们选择。警告来自同一文献。一项超过 10,000 名参与者的研究发现，阅读 LLM 摘要而不是钻研材料的人获得的知识更浅薄，给出的建议更不自信（Melumad 和 Yun 2025）。摘要是地图。学习发生在块，而结束于摘要的路径不是阅读路径。
三个角度，更多按需。第 1 层的视图是另一种分组。摘要告诉任何人项目是什么、做什么。用户视图告诉使用系统的人它如何表现。开发者视图告诉改变系统的人它如何构建。新手阅读摘要，然后阅读其角色的视图，并沿着其链接向下到重要的块，而不是逐个来源地发现项目包含什么。当一个问题横切默认角度时，按需为它写一个视图：一个功能、一个用例、一个问题，从触及它的每个来源和每个项目提取。视图在它们链接的任何东西变化时由更新步骤重建，因此它们与它们引用的事实一样真实。
> 重要：在一项超过 10,000 名参与者的研究中，阅读模型摘要而不是钻研材料的人获得的知识更浅薄，给出的建议更不自信（Melumad 和 Yun 2025）。
> 这对我们意味着什么：将每个块保留在其摘要之下，并将每个项目保留在多个视图中，以便工程师可以选择路径，但让路径结束于块。
> 为什么重要：使存储对代理廉价的相同层次让人可以停在摘要，而证据表明理解正是在那里丢失的。
要点传承
- 每个项目、来源和块都作为摘要存在，对于块还作为全文存在，可自上而下或自下而上阅读。摘要是地图，不是目的地。
- 三个默认视图，摘要、用户和开发者，以及任何功能或问题的按需视图，每个在它所链接的任何东西变化时重建。
## 第 8 层。规格说明
这一层回答：如何从详述一个功能、方面或用例的视图写出规格说明，谁决定何时，以及证据说是什么决定代理是否成功？
artifacts 下的 specs 文件夹是树中为编码代理存在的部分。规格说明陈述一个功能需要交付的内容，它位于它所依据的事实和视图旁边。两个决定属于工程师。第一个是请求一个视图：存储关于一个功能、用例或方面所知内容的狭窄而详细的集合，从摘要写出，在需要的地方打开事实块。第二个是在功能要实现时从该视图请求规格说明。
规格说明决定。Specification Gap 论文给编码代理相同的任务但不同数量的规格说明（arXiv 2603.24284）。
- 一个代理在完整 docstring 下解决了约 89% 的任务，在裸签名下约 56%。
- 两个代理分工在完整 docstring 下解决了 58%，在裸签名下 25%。仅恢复规格说明就让这一对回到 89%。
从视图到规格说明。
1. 为功能写一个视图，从功能触及部分的摘要和事实块。工程师阅读它，如果它遗漏了某部分则扩大或缩小请求。
2. 当功能要实现时，工程师请求规格说明。它从视图写出并陈述需要交付的内容。
3. 规格说明中的每个关键陈述都对照事实验证并链接到它。第 4 层的两次每页检查像任何页面一样在规格说明上运行。
4. 编码代理从规格说明实现。
规格说明是一个产物。当它背后的事实变化时，第 5 层的更新步骤连同它来自的视图一起重写它，因此代理绝不从事实不再支持的规格说明实现。
> 重要：两个共享任务的代理在裸签名下解决了 25%，在完整规格说明下解决了 89%，而仅恢复规格说明就让它们回到 89（arXiv 2603.24284）。
> 这对我们意味着什么：从功能的视图写出规格说明，对照事实验证每个关键陈述，并把规格说明交给代理。
> 为什么重要：规格说明是我控制的一个输入，而在测量中它使成功移动了约三分之一。
要点传承
- 规格说明从单个功能的视图写出，在工程师请求时，当功能要实现时。它陈述需要交付的内容。
- 规格说明中的每个关键陈述都对照事实验证并链接到它。规格说明是在相同检查和相同更新步骤下的产物。
- 编码代理从规格说明实现。
## 第 9 层。研究变体和运行框架
这一层回答：当存储保存论文而不是项目时有什么变化，以及本设计中什么在更换运行框架后仍然成立？
研究变体。一个从论文学习领域的人使用同一棵树，去掉两个部分并改变一个。主题是学科而不是项目。一个检索研究者的存储有一个图检索文件夹，而一篇 2025 年论文的原始 PDF、其事实页面及其摘要位于需求文档在项目存储中占据的相同位置。
- 没有预先的来源列表。来源在找到时到达而不是预先已知，因此来源文件随它们到来而填充，创建工作流按来源运行，而更新工作流几乎没有要重新获取的。论文不变化。更新是撤稿、勘误或取代某个事实的更新结果，它完全像修订的需求一样处理。
- 没有规格说明。没有东西从存储实现。
- 视图改变角度。摘要保留。用户和开发者视图让位于按需编写的视图，针对一个方法、一个基准或跨论文的一个问题，而当主题包含超过几个来源时，一个列出它们的一致、分歧和开放问题的视图是人在任何单篇论文之前阅读的。
其他一切不变：事实、护栏、索引和阅读路径。
与运行框架无关的部分。上面的每个机制都是文件、脚本或约定：Markdown 页面、生成的索引，以及用于链接检查、哈希检查和依赖遍历的脚本。它们都不依赖于厂商的记忆功能。无论运行框架在启动时读取什么指令文件，例如 Claude Code 或 Cursor 中的项目文件或 agents.md 文件，都保存根索引，或单项目存储的项目索引，或指向它的链接，仅此而已。将索引保留在该文件中而不是藏在技能后面的原因是第 6 层的 Vercel 结果。厂商的记忆功能服务于会话连续性，被视为缓存，绝不是事实居住的地方。
要点传承
- 文件、链接和脚本在任何运行框架下都成立。运行框架的指令文件保存索引，而厂商记忆是缓存。
- 研究存储是同一棵树，没有规格说明，没有预先写好的来源列表，视图按方法、基准或问题编写。
## 决策指南
- 知识库到底值不值得建？使用：仅当文档不断变化并被多次阅读、被多个工具阅读、或被必须学习它的人阅读时才建。然后检查：把文档放进提示中会回答相同的问题吗？
- 这是项目存储还是研究存储？使用：当系统从它构建时用项目存储，带有预先写好的来源文件、规格说明，以及摘要、用户和开发者视图；当没有东西从它实现时用研究存储，没有规格说明，来源文件随论文被找到而增长，视图按方法或基准。然后检查：有任何东西从这个存储交付吗？
- 树应该多深？使用：按大小需要多深就多深，每个文件夹有一个生成的索引，每当索引增长超过可整体阅读时增加一个新层级。然后检查：有任何索引太长无法整体阅读吗，当代理走错路时，它搜索索引文件还是继续下降？
- 文件夹和文件应该如何命名？使用：文件夹用项目 slug，然后是三个固定子文件夹之一，raw、facts 或 artifacts，视图和规格说明在 artifacts 内；事实页面以其内容的 slug 命名；视图以其角度命名；生成文件用固定名称。然后检查：新来者仅从目录列表就能看出页面说什么吗，一个项目文件夹保存关于该项目的一切吗？
- 我如何吸收比模型窗口更长的来源？使用：约 2,000 到 4,000 token 的窗口，以完整思想结尾，每个重写为可独立阅读并保留原文，每个被总结，而来源从块摘要总结。然后检查：每个边界都与来源逐字匹配吗，运行从检查点恢复吗？
- 什么算作事实？使用：来源的一个以完整思想结尾的块，带有其原始片段和一个可独立阅读的重写版本，其表格和图表作为文本，以及一行命名它在原文中的页面。然后检查：重写版本在原文旁边可独立阅读吗，页面中的每个陈述都链接到事实吗？
- 当来源变化时会发生什么？使用：替换其所有事实及其摘要，收集链接到它们的每个页面以及链接到那些的一切，在同一次触发的运行中重写它们，在相同含义处停止，检查每一跳。然后检查：一次运行后，有任何页面仍然链接到不再存在的事实吗？
- 我如何搜索？使用：首先索引文件和渐进式披露，项目摘要、来源摘要、块摘要、块；对索引行用 BM25；对块用带标题链头的嵌入；仅对时间变化的多跳存储用图。然后检查：检索未命中被记录了吗？
- 工程师如何阅读存储？使用：摘要，然后其角色的视图，然后自上而下从项目摘要或自下而上从工单所指的块；当问题是一个功能或一个用例时按需视图。然后检查：读者的路径结束于块吗？
- 规格说明如何写？使用：工程师请求功能的视图，然后在功能要实现时从该视图请求规格说明，每个关键陈述都对照事实验证。然后检查：规格说明中的每个关键陈述都链接到仍然存在的事实吗？
- 哪个运行框架功能应该保存存储？使用：没有；运行框架的指令文件保存根索引，而厂商记忆是缓存。然后检查：存储能通过复制一个文件夹移动到另一个运行框架吗？
## 要点
1. 项目知识库服务于两类读者，一个采取行动的编码代理和一个必须理解系统的工程师，而几乎所有已发表的设计只服务于第一个。
2. 为人物嵌套文件夹，主题在前类型在后，因此一个文件夹保存项目的原始来源、事实和产物。项目是文件夹，功能是其中的一组页面。在每个文件夹放一个生成的索引，每行都是它所指向内容的真实摘要，当项目增长时增加层级而不是行。
3. 事实是来源的一个块，其原始文字旁边是一个可独立阅读的重写版本，表格和图表作为文本。原文保留在文件中，以便重写版本可以对照它阅读，而页面中的每个陈述都链接到事实。
4. 按完整思想切分，由脚本对照文本验证，因此任何长度的来源都由一种大小的模型调用处理。
5. 保持重写版本与原文相同的密度。压缩在一个基准上损失了多达一半的答案。
6. 摘要只有一层深度并存在于索引文件中：来源索引中每个块一份，项目索引中每个来源一份，根处每个项目一行。
7. 视图是人阅读的：每个项目一个摘要、一个用户视图和一个开发者视图，以及任何功能或问题的按需视图，每个从摘要写出并在需要的地方打开块，每个陈述都引用其事实。
8. 产物是散文和链接。它的路径说明它是什么，它的链接说明它依据什么构建。当来源变化时，更新运行向后沿着链接并在同一次运行中重写每个依赖产物。
9. 创建是七个步骤：获取和转换、切分成事实、总结每个块、总结来源、写出视图、检查每个页面、索引。模型起草而脚本检查。
10. 在写入每个页面时检查它。每个边界的门控将存活错误从 58.4% 降至 16.2%。最终检查获得 2.3 个百分点。
11. 按输入更新，绝不按日期。由脚本收集依赖项，在同一次运行中重写它们，在含义不变的地方停止，并检查每一跳。基于年龄的检查让 30 个过时计划中的 30 个通过。
12. 检索是一架在记录未命中上攀爬的梯子：索引文件和渐进式披露、对索引行的 BM25、带标题头的嵌入、最后是图。让项目索引成为代理的第一次读取，因为必须选择查看的代理常常不查看。
13. 人通过代理使用的相同摘要自上而下或自下而上阅读，并从视图中其角色的角度阅读项目。摘要是地图。停在那里的阅读被测量为更浅薄的知识。
14. 规格说明从单个功能的视图写出，在工程师决定要实现该功能时，并陈述需要交付的内容。每个关键陈述都对照事实验证。完整规格说明将代理成功从 56% 移动到 89%。
15. 研究存储是同一棵树，没有规格说明，没有预先写好的来源列表，视图按方法、基准或问题。这里没有任何东西依赖于运行框架。文件、链接和脚本通过复制一个文件夹移动。
## 参考文献
- He 等 2026。Is Progressive Disclosure All You Need for Long-Context Agents? arXiv 2607.17598。
- Zhou, Yu, Wei 等 2026。Filesystem-Based Memory for LLM Agents: Organization, Evolution, and Sustainability。arXiv 2607.26637。
- Wu 等 2024。ClashEval: Quantifying the tug-of-war between an LLM's internal prior and external evidence。arXiv 2404.10198。
- Retrieval as Reasoning: Self-Evolving Agent-Native Retrieval via LLM-Wiki。2026。arXiv 2605.25480。
- Singh 和 Pawar 2026。The Hallucination Snowball。arXiv 2608.14588。
- Kuang 等 2026。REAgent: requirement-driven issue resolution。arXiv 2604.06861。
- Chen, Wang, Brinton 2026。Fresh Memory, Stale Plans: Derivation Currency for Distributed LLM-Agent Memory (Planfence)。arXiv 2609.03340。
- FinCacheServe 2026。Dependency-Consistent Answer Reuse for RAG Serving over Mutable Enterprise Documents。arXiv 2607.26076。
- Hammer 等 2014。Adapton: composable, demand-driven incremental computation。PLDI 2014。Jane Street。Incremental, Cutoff documentation。ocaml.org。
- Salsa 算法参考。salsa-rs.github.io。Microsoft。Excel recalculation。learn.microsoft.com。
- Structure-Aware Semantic Chunking with Title-Chain Prefixes。arXiv 2608.00824。
- Chroma 2025。Context Rot。trychroma.com/research/context-rot。
- Vercel 2026。AGENTS.md outperforms skills in our agent evals。vercel.com/blog。
- Luiten, Ames, Ackerson 1980。A meta-analysis of the effects of advance organizers on learning and retention。American Educational Research Journal 17(2)。
- Chen, Kalyuga, Sweller 2017。The expertise reversal effect is a variant of the more general element interactivity effect。Educational Psychology Review。doi 10.1007/s10648-016-9359-1。
- Melumad 和 Yun 2025。LLM summaries versus web search。PNAS Nexus。doi 10.1093/pnasnexus/pgaf316。
- Chacón Sartori 2026。The Specification Gap: Coordination Failure Under Partial Knowledge in Code Agents。arXiv 2603.24284。
## 相关链接
- [Sergii Makarevych](https://x.com/sermakarevich)
- [@sermakarevich](https://x.com/sermakarevich)
- [11K](https://x.com/sermakarevich/status/2113681318852600222/analytics)
- [text.md](http://text.md/)
- [agents.md](http://agents.md/)
- [ocaml.org](http://ocaml.org/)
- [salsa-rs.github.io](http://salsa-rs.github.io/)
- [trychroma.com/research/context-rot](http://trychroma.com/research/context-rot)
- [AGENTS.md](http://agents.md/)
- [vercel.com/blog](http://vercel.com/blog)
- [Upgrade to Plus](https://x.com/i/premium_sign_up)
- [1:17 AM · Oct 24, 2026](https://x.com/sermakarevich/status/2113681318852600222)
- [11.9K Views](https://x.com/sermakarevich/status/2113681318852600222/analytics)
- [View quotes](https://x.com/sermakarevich/status/2113681318852600222/quotes)
---
*导出时间: 2026/10/26 09:59:22* 
