Skip to content

Guides and resources for AI engineers: an agents course, five handbooks, a hands-on second-brain project and a vetted reading list.

2.1 KB
Raw Blame

One page, one idea

A page holds one idea, explained well enough that someone who has never seen the source understands it.

The rule exists because of how retrieval works. When the agent answers a question, it pulls in whole pages. A page covering four topics drags three irrelevant ones into context every time it is touched. A page covering one gets linked precisely, retrieved precisely, and updated without collateral damage.

What atomic means here

Not short. A concept page can run several hundred words. Atomic means it has one subject and you could give it an accurate title without using "and".

If the title needs "and", or the page has section headings for unrelated subjects, it is two pages.

Splitting a source

One article usually yields one to three concepts worth their own page, plus the source page recording what the article itself said.

The test for whether something deserves a page: can it be explained without referring back to this one source? An idea that only makes sense as "what this article argued" belongs inside the source page. An idea that will recur across other sources needs its own page, because that is where the other sources will attach.

The failure in both directions

Over-splitting produces ten pages from one article, each a restated paragraph, each linking only back to the source. The graph looks dense and says nothing. This is the more common failure with agents, because splitting feels like thoroughness.

Under-splitting produces source pages that are article summaries and a wiki with no concepts at all. You end up with a searchable archive, which you already had.

If you are unsure, write fewer pages. Merging later is cheap; untangling a hundred fragments is not.

Length

A concept page under about eighty words is usually a stub that failed, not a page that was efficient. Either the source did not really cover it, or the agent gave up. Both are worth catching in a lint pass.

A page over roughly a thousand words is usually two ideas that grew together. Read it and look for the seam.

Next

The four page types