LLM Best Practices

Knowledge Vaults

2 min read

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.

A knowledge vault is a folder of plain Markdown notes with typed frontmatter, explicit links, and a machine-checkable schema. It compounds when it is atomic, sourced, and audited, and rots when it becomes long documents nobody links.

Architecture

  • vault-architecture: Numbered folder tree, scoped note types, vault-spec.yaml as source of truth, generation over hand-building.
  • atomic-notes: One idea per note, claim titles, 100 to 500 words, three to seven explained links, deliberate promotion.
  • vault-frontmatter-schema: Per-type required fields, empty arrays over missing keys, framework extensions.
  • linking-and-tags: Links carry meaning, tags carry state, block references, MOCs grown from clusters.
  • rigor-frameworks: Map the domain to a framework (MECE, ADR, IRAC, and more), layer, or compose one.

Evidence and decisions

  • source-verification: One source note per work, dated verification, the corroboration gate.
  • decision-journals: Journal at decision time, freeze the pre-decision section, pre-mortem, review by class.

Operations

  • vault-orchestration: The capture-extract-link-audit-promote loop, the fixed agent prompts, bulk-write guardrails.
  • vault-audit: The deterministic auditor, rule catalog (C, S, M series), triage, autofix tier, re-run delta.
  • semantic-audit: The fixed-rubric LLM judge for defects code cannot detect.
  • vault-maintenance: Weekly, monthly, and quarterly reviews, Dataview gates, the maintenance budget.
  • vault-evolution: Add, deprecate, migrate; never rebuild. Includes the migration for a newly required field.
  • team-vaults: Git as substrate, conflict-free conventions, one naming authority, owned decisions.
  • vault-pull-request-review: Auditor as merge check, severity mapping, squash rules for atoms vs decisions.

How-to

14 items under this folder.