LLM Best Practices

Team Vaults

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 solo vault has one hard problem, thinking. A shared vault adds coordination without corruption: two people editing one note, racing to name one idea, or splitting one atom differently will destroy link density and provenance unless the design removes the conflict. This page covers the multi-author layer on vault-architecture; the review gate that enforces it is in vault-pull-request-review.

Use Git, not a file syncing service

File replicators resolve concurrent edits by last write wins, which is silent data loss for a team. Git gives three things a replicator cannot.

  • A merge model. Edits to different regions merge; edits to the same region raise a conflict for a human.
  • Immutable history. This is what enforces the frozen pre-decision section: a hindsight rewrite shows as a diff against a region that should never change (decision-journals).
  • Review gates. A second author checks atomicity, sources, and naming before a note lands.

Commit the spec and tooling. Ignore per-user editor state (workspace.json, caches, local trash) and track shared plugin config so everyone runs the same templates and queries. Schema changes travel the same path as any change (vault-evolution); branch conventions are in git.

Design conflicts out with atomicity and append conventions

Atomicity is a concurrency discipline. Two people editing two atoms never conflict; one 2,000-word note three people must touch is a permanent merge hotspot.

  • Append-only regions get an append convention. Decision outcomes, map link lists, and daily notes take one bullet per line, newest at the bottom, with no reflowing of existing lines. Disjoint appends merge cleanly; a reflow turns one into a conflict.
  • Frontmatter keeps a fixed field order, so a one-field change is a one-line diff. Do not auto-bump modified on every keystroke; it manufactures conflicts on untouched notes.
  • Split high-traffic maps early. A map three people edit weekly wants to be three sub-maps (linking-and-tags).

When a conflict happens, the note’s author arbitrates, not whoever pulled last.

Hold one naming authority

Filenames are primary keys. Two authors creating compound-interest-beats-linear.md and compound-interest-outpaces-linear-saving.md for one idea split the link density across two notes that should be one.

Keep a lightweight naming ledger where an author proposes a title first when the idea might exist. One maintainer owns the taxonomy: the domain tag tree, note-type prefixes, and map names. A fork between #domain/finance/macro and #domain/macro-finance is expensive to reconcile.

Treat renames and atom splits as scope-freeze operations. A rename breaks every inbound link until the links are rewritten, so state the path list and referring notes, get sign-off, and commit the rename with its link updates together. For a split, the proposer names the seam and the two resulting titles in the ledger, the note’s author confirms, and it lands as one change. The audit surfaces candidates; people agree the cut (vault-audit).

Keep atoms communal and decisions owned

Anyone may improve any atom. Permanent notes are the communal core, with contributions attributed in an append-only authors field. Decision notes have exactly one owner, the person who decided; a reviewer may comment on a pre-decision section and never edit it. Projects and inbox captures can carry a light owner convention so two people are not racing in one scratch space.

Backlinks