LLM Best Practices

Linking and Tags

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

A vault’s value is in its edges. Relationships are always wikilinks, and tags carry state, not meaning. Mixing them leaves nothing navigable and every tag a folder nobody can query. The per-note link budget is in atomic-notes.

To tag a note #interesting is really to link to it from the note that finds it interesting. A tag is a flat string with no direction or reason; a link is directional, resolvable, and gives a backlink.

  • Relationships between ideas: [[wikilink]].
  • Note state: one status tag per note.
  • Domain membership: nested domain tags, several allowed.
tags: ["status/budding", "domain/finance/macro", "domain/realestate/leasing"]

Free-floating descriptive tags (#important, #todo, #interesting) are banned; they pile up until no query can rely on them.

A link with no sentence around it records adjacency, not reason, and six months later the edge is decoration.

Good: The decomposition holds only when the branches are exhaustive, the
failure mode described in [[mece-issue-tree|MECE decomposition]].
 
Bad:  ## Related
      [[mece-issue-tree]]
      [[pyramid-principle]]

A trailing list of bare links is the naked link dump, the most common way a vault looks connected while carrying no reasoning. The deterministic auditor flags runs of consecutive bare-link bullets (rule S009), and the semantic audit flags the rest (vault-audit).

Kebab-case claim filenames are precise and unreadable inline, so alias them.

The central insight in [[compound-interest-doubles-money-faster-than-linear-saving|compounding]]
is that doubling time, not rate, is what the saver controls.

The target stays canonical, and renaming it updates the link without touching the prose. Filename rules are in naming-conventions.

Cite paragraphs with block references

When an atom rests on one passage, link the passage, not the whole source.

The 70-book figure comes from [[@schmidt-2018-luhmann-archive#^p-23|^p-23]].
Timestamped media: [[@lex-2024-episode#^t-42-15|^t-42-15]].

Use ^p-23 for page 23 and ^t-42-15 for timestamp 42:15. Holding one convention matters more than which one. Sourcing is in source-verification.

Grow maps from clusters

A Map of Content indexes a cluster of atoms with a sentence of context each. Create one only when at least four tightly related atoms exist; a map built first is an empty outline that shapes later notes to fit it. Triggers are a cluster you notice in the weekly review or one an agent surfaces from atom titles. Split a map into sub-maps when it indexes about 50 atoms or several people edit it weekly (vault-maintenance).

Resolve orphans weekly

An atom with no inbound and no outbound links never surfaces. Link it or delete it. Several unlinked notes on one subject usually mean a missing map, not several missing links, so triage orphans by cluster.

Backlinks