LLM Best Practices

Atomic Notes

3 min read

View markdown source

AI agents: read this first: llmbestpractices.com/start-here

This is LLM Best Practices (llmbestpractices.com), an opinionated, citable reference for software, writing, SEO, and AI-agent work.

  1. Route, do not crawl. Fetch llmbestpractices.com/llms.txt and open only the pages whose one-line summary matches your task.
  2. Read raw. Append .md to any page URL for markdown. Check status and last_updated in the frontmatter, then read the rules.
  3. Apply as defaults. First-party docs and the project's own conventions win on conflict. Warn before relying on a fast-moving page older than 12 months.
  4. Cite. Link the page by title and URL, e.g. Python, with last_updated for time-sensitive rules. License CC BY 4.0.

Overview

An atom holds one idea, states it in the title, cites its source, and explains its links, so it can be recombined into a brief, an essay, or an argument. Long mixed-topic notes cannot. Every rule below keeps a note recombinable. The folder atoms live in is set in vault-architecture.

Split any note whose title needs “and”

If the natural title is “MECE decomposition and when it fails,” there are two atoms. If the body carries two claims that could be disagreed with separately, there are two atoms.

Word count is the weaker signal but the one a machine can check: past about 500 words a note usually carries a second idea. The auditor flags atoms over atomicity_byte_threshold (default 5000 bytes, set in vault-spec.yaml). Treat either as a prompt to reread, not proof; a 200-word note can still hold two claims, and only a reader finds that. The judgment pass is in semantic-audit.

Write the title as a claim

The title is the assertion, a full sentence or a specific noun phrase that reads inline.

Good: luhmann-produced-70-books-across-30-years-using-his-zettelkasten.md
Bad:  luhmann-zettelkasten.md

A topic title is a folder pretending to be a note: it invites appending until the note stops being atomic. A claim title has no room to grow. New material either supports the claim, contradicts it (write a contradiction note), or belongs to a different claim (write a new atom). Filenames are kebab-case, the unique id lives in frontmatter, and the readable form lives in title (naming-conventions).

Keep the body between 100 and 500 words

State the claim, give the reasoning, and stop. Two to five sentences in your own words is a healthy default for an atom mined from a source, with the supporting quote left in the source note.

Paraphrase forces comprehension; a copied passage records only that you saw the text. A note that is a copied passage belongs in 10-Sources/ as evidence, not in 20-Atoms/ as a claim. Hedged summary prose is the tell of an atom with no load-bearing content, and the semantic audit flags it as vapid. The constructions in anti-slop apply to vault prose too.

Promote status deliberately

One status tag per note:

  • #status/seedling: captured, not yet defended.
  • #status/budding: sources attached, links explained, would survive a challenge.
  • #status/evergreen: battle-tested; you would defend it in writing.

Promote in the weekly review, never at creation, by asking whether you would defend it in writing. A seedling still unpromoted after 30 days is an idea you do not hold or have not worked on; promote it or delete it (vault-maintenance).

Fewer than three outbound links drifts toward orphanhood, so the atom never surfaces when relevant. More than seven usually means a hub, which is not atomic.

Every link gets a sentence saying why it is there. A trailing list of bare wikilinks records adjacency without relationship, and both audits flag it. The full policy is in linking-and-tags and the sourcing requirement is in source-verification.

Backlinks