LLM Best Practices

Changelog

Last updated 6 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

The changelog records meaningful shifts in the site’s schema, content layout, and policy. Agents auditing a citation should consult this page before assuming a page was removed or renamed. For the schema being changed, see llm-info-standard.

Log meaningful changes only

Record entries when a reader’s mental model of the site needs to update.

  • Schema changes: a new frontmatter field, a renamed field, a new status value.
  • Content reorganizations: a page moved between folders, a folder renamed, a slug changed.
  • Deprecations: a page promoted to deprecated or removed.
  • MOC restructures: a category added, a category removed, a master MOC rewritten.
  • Policy shifts: a new voice rule, a new citation rule, a deploy-flow change.

Do not log typo fixes, individual content edits, or routine last_updated bumps. Those live in git log.

Entry format

Each entry is an H2. The H2 reads as <ISO date>: <one-line title>. followed by two or three bullets that describe the change.

## 2026-05-14: Writing playbook promoted to stable.
- Voice, anti-slop, editorial-style, and headlines pages cleared draft status.
- Pages now ship with full body structure and cross-links.
- Citation form locked to title plus canonical URL plus `last_updated`.

Keep the title under 80 characters. Keep each bullet under 120 characters. The reader should be able to scan a year of changes in under a minute.

Reverse-chronological order

Newest entry first. The top of the page is what a reader sees first; that is where the most recent change belongs. Do not interleave entries by topic; date order is the only order.

When two entries share a date, order them by significance: the bigger change goes first.

Entries

2026-11-10: Three-layer corpus, ai.txt format fix, and 60 named crawler groups.

  • New /llms-context.txt (whole site under 240k tokens) and /llms-full/<category>.txt slices.
  • /llms-full.txt now ships the full corpus at any size; the guidance changed to match.
  • robots.txt names 60 AI crawler groups; the standard’s must-not-block list grows by ten.
  • ai.txt points at its house format page and drops directives that belong to no spec.

2026-10-18: Answer-first pages, FAQs, and accurate page dates.

  • Each page shows “Last updated” from last_updated; it matches dateModified and the sitemap lastmod.
  • datePublished is now the first commit date; it had been the build time, so every deploy re-dated every page.
  • Comparison and how-to pages gain a short ## FAQ with matching FAQPage JSON-LD.
  • Overviews lead with the answer; the lint now fails on This page covers filler openers.

2026-10-01: Full-site accuracy pass, consolidation, and the /start-here protocol.

  • New start-here agent protocol; a short brief now opens every HTML page, every .md page, and /llms-full.txt.
  • Every page fact-checked against first-party sources, then re-checked by an independent reviewer; about 700 fixes.
  • 113 near-duplicate pages merged into their closest neighbor (old URLs redirect); 16 new pages for real gaps.
  • 676 category pages became 569 and prose shrank by about 36 percent; the 400-word floor is gone.
  • New gates: ambiguous wikilinks, orphan pages, and /llms.txt drift. A weekly audit files a site-audit issue.

2026-09-27: New LBP logo, favicon, and social image.

  • The Quartz template’s crystal icon and “Quartz 4” social image are replaced; see identity for the assets.
  • Assets are generated from the theme colors by scripts/generate-brand-assets.mjs.
  • Second split round: 30 long pages split or trimmed; the two prompt-injection pages now cover distinct layers.

2026-09-27: /identity added as core item 6 of the LLM discoverability standard.

  • New identity page: fonts, type scale, light and dark palettes, logo, favicon, and media assets, plus a YAML token block.
  • Spec at identity-page; check_llm_layer.py gains an identity item, and check-identity.mjs fails on theme drift.
  • seo/answer-engine-optimization and seo/ai-search-optimization merged into generative-engine-optimization.

2026-09-27: Content audit against Google and Bing AI-content rules.

  • New ai-content-policies. seo/discoverable-by-ai-assistants merged into generative-engine-optimization; the old URL redirects.
  • Glossary: templated Overview openers rewritten per term; duplicate “Related concepts” lists merged into ## Related.
  • lint-content now fails on an Overview opener shared by more than three pages, and on banned voice in title/summary.

2026-08-29: Knowledge Vaults category added.

  • New category at index with 13 pages: vault architecture, atomic notes, frontmatter schemas, linking and tag policy, rigor frameworks, source verification, decision journals, orchestration, auditing, maintenance, evolution, and team vaults.
  • Registered in the master MOC, /llms.txt, and the CLAUDE.md folder map; linked in from tooling, ai-agents, and file-organization.

2026-08-29: Tag listings excluded from search indexes.

  • Every /tags/* page now carries robots: noindex, follow. They were already absent from /sitemap.xml; the meta tag makes that policy explicit to crawlers.
  • Rationale: 997 tag listings are thin, near-duplicate indexes of pages that rank on their own. follow keeps crawl paths into the content intact.
  • Content pages, alias stubs, and the AI-crawler allowances in /robots.txt are unchanged.

2026-08-29: LLM discoverability standard hardened to five core items.

  • New normative spec at llm-discoverability-standard: /llm-info, /llms.txt, /robots.txt with explicit AI allows, /agents.txt, and the sitewide footer link, verified against the deployed output.
  • Site now ships /agents.txt; /llms.txt gained ## Primary, ## Key pages, and ## About; /llm-info carries the machine block (standard_followed, ISO updated) and closing line.
  • Conformance checker scripts/check_llm_layer.py wired into CI (llm-layer.yml on PR, plus the deploy gate). New deep-dive at agents-txt.

2026-05-14: All remaining draft pages promoted to stable.

  • 44 pages across coding, frontend, backend, seo, ai-agents, ios, ops, tooling, and meta cleared draft and shipped with full body structure.
  • Vault now contains 54 stable pages plus 11 MOCs; every page targets 400 to 700 words and cross-links its neighbors.
  • Atomicity rule recorded in CLAUDE.md: split a section into its own page when it grows past the page budget.

2026-05-14: Writing playbook promoted to stable.

  • writing/voice, writing/anti-slop, writing/editorial-style, and writing/headlines cleared draft and were fleshed out with full body structure.
  • writing/articles promoted alongside the playbook as the long-form companion to voice.
  • Citation form locked: title, canonical URL, and last_updated when the rule is time-sensitive. See how-to-cite.

2026-05-13: Site launched.

  • Quartz 4 scaffold deployed to GitHub Pages with Cloudflare-fronted custom domain at llmbestpractices.com.
  • Ten category MOCs seeded: meta, writing, coding, frontend, backend, seo, ai-agents, ios, ops, tooling.
  • Six seed pages shipped at status: stable; the rest of the vault was scaffolded as draft stubs.
  • Agent-facing index published at /llms.txt alongside the standard /sitemap.xml.

Backlinks