LLM Best Practices

Changelog

4 min read

View markdown source

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-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 llm-seo-best-practices; 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