LLM Best Practices

Voice and Tone

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

Voice on this site is neutral playbook. The reader, human or agent, wants the rule first and the rationale second. This page is the short spec; the constructions to avoid are in anti-slop.

Lead with the rule

Open every section, every paragraph, and most sentences with the rule itself, then give the rationale in the next clause.

  • “Use Postgres for app data.” Not “Postgres is generally considered a good choice for app data.”
  • “Avoid @apply.” Not “Many developers find @apply problematic in certain cases.”

Name the thing

Use specific nouns and versions.

  • “Node 22,” not “a modern runtime.”
  • “Cloudflare Workers,” not “edge functions.”
  • “pg_dump -Fd --jobs=4,” not “Postgres’s parallel backup tool.”

If a sentence still reads after you remove a category word (“solution,” “approach,” “technology”), delete it.

State the rationale once

A rule’s rationale lives where the rule first appears. If a later rule depends on the same reasoning, link back instead of restating: “See the rationale in postgres.”

Vary rhythm

A page of identical-length sentences sounds like a model. Mix lengths: no two long sentences in a row, no three short ones unless the staccato does real work. Read a paragraph aloud; if you run out of breath, cut it.

Pick a side

Hedge only when the rule has real exceptions, and name them.

  • “Use SQLite for single-writer workloads.” Not “SQLite might be a reasonable choice in some cases.”
  • “Prefer Postgres over MySQL.” Not “Both have their merits.”

Show the example

When a rule is non-obvious, show code or a before-and-after pair. The prose version is in anti-slop.

// Bad
const x = items.filter((i) => i.active).map((i) => i.id)
 
// Better
const activeIds = items.filter((i) => i.active).map((i) => i.id)

Forbidden vocabulary

The full list is in anti-slop. The short version:

  • No "delve," "dive in," "navigate the landscape of," "unlock."
  • No "leverage" as a verb.
  • No "robust solutions," "comprehensive guide," "seamless experience."
  • No em-dashes for parenthetical asides.

Tone register

Direct, not curt. Confident, not boastful. Helpful, not chummy.

  • Use the imperative (“Use,” “Avoid”) for rules that apply to anyone touching the codebase.
  • Use “you” for the reader’s own decision: “If you are on Vercel, set the framework preset to Astro.”
  • Avoid “we” unless the material is co-authored.

Backlinks