LLM Best Practices

Editorial Style Guide

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

This is the copy-edit reference for punctuation, capitalization, numbers, code, links, and lists. For voice see voice; for banned constructions see anti-slop; for the frontmatter schema see llm-info-standard.

Punctuation

  • No em-dashes. Use a period, a semicolon, or a comma.
  • Use the serial comma: “Postgres, SQLite, and ChromaDB.”
  • One space after a period.
  • Write straight quotes in markdown source. Quartz’s GitHub-flavored markdown transformer enables SmartyPants by default, so the rendered page shows curly quotes.
  • Introduce a list, example, or quotation with a colon. Do not put a colon before a code block; let the prose lead in.

Capitalization

  • Sentence case for H2 and H3: “Lead with the rule,” not “Lead With The Rule.”
  • The page title (the H1) is sentence case or title case as the topic prefers, but stay consistent within a folder. The Topic: Best Practices pattern is title case.
  • Capitalize proper nouns: Postgres, TypeScript, GitHub, Claude Code, Next.js.
  • Lowercase generic terms: app, server, database, framework, agent.
  • Uppercase established acronyms: HTTP, CSS, SQL, JSON.

Numbers

  • Spell out zero through nine in prose; use numerals from 10.
  • Always use numerals for versions, dimensions, measurements, and counts in code or commands: “Node 22,” “2 GB,” “5 retries.”
  • Hyphenate compound modifiers: “10-second timeout,” “two-step process.”
  • Write 1,000 in prose; leave code unformatted.

Code references

  • Wrap filenames, commands, identifiers, and short strings in backticks: package.json, npm ci, useEffect, --ci.
  • Use a fenced block with a language tag for anything longer than one line.
  • Follow the surrounding language’s comment convention inside code blocks.

Headings

  • One H1 per page; Quartz renders it from title, so body content starts at H2.
  • An H2 reads as a rule, not a topic: “Lead with the rule,” not “Leads.” See headlines.
  • Use H3 only when an H2 splits cleanly into named sub-cases. Avoid H4; the page should split instead.
  • Use wikilinks for internal references: [[seo/llms-txt]].
  • Use the folder-prefixed form for any page outside the current folder, and always when the slug exists in more than one folder. A bare ambiguous wikilink renders as a broken link.
  • For external links, write a sentence that reads naturally around the linked phrase. Never link “here” or “this”; link the noun.

Lists

  • Use - for unordered lists, not * or +.
  • Leave one blank line before and after a list.
  • Use sentence case for items; end with a period when the item is a sentence, with no period for a fragment or label.

Citations

For citing pages on this site, see how-to-cite. The short form is title, URL, and last_updated when the rule is time-sensitive.

File names

  • Markdown files are kebab-case and the frontmatter slug matches the filename without extension.
  • Directories are lowercase and hyphenated: ai-agents/.
  • The same rules applied across code are in naming-conventions.

Backlinks