LLM Best Practices

Article Structure

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

An article on this site has a lede that states the claim, sections that open with rules, and an ending that stops on its last real point. This page is the skeleton spec; sentence-level rules are in voice and anti-slop.

Use the default skeleton

  1. Lede, one to three sentences: the claim or the question. No throat-clearing.
  2. Stakes, one short paragraph: why the reader should continue.
  3. Body, two to six H2 sections, each opening with a rule.
  4. Example or case, with the code or artifact shown.
  5. Caveats, only if the rule has real exceptions.
  6. Hand-off, one sentence linking to what to read next, or nothing.

Skip sections; never fake them. A piece with no real caveats gets no caveats section.

Open with the claim, the question, or the artifact

  • Claim: “Postgres beats MySQL for application data.”
  • Question: “When is SQLite the right database?”
  • Artifact: “Below is the migration that finally made the table fast.”

“In this article,” “Today we’ll look at,” and "Let's dive into" all delete cleanly.

Make each H2 one rule

The H2 states the rule; the body gives rationale and examples. Heading case and keyword rules are in headlines.

  • Use H3 only when an H2 splits into named sub-cases. Avoid H4.
  • If two H2s repeat a point, merge them. If one H2 carries most of the page, split the page.

Keep paragraphs to one idea

Open with the idea, develop it, stop. Skip takeaway sentences and paragraph-end transitions (“With that in mind”); the next paragraph starts with its own idea.

Choose lists by item shape

Use a list when items are parallel and order or count matters. Use prose when items need connective tissue. Nested lists past one level mean the content should be sub-sections.

End on the last real point

A summary paragraph that restates the lede is a slop tell. If a hand-off helps, make it one sentence with a link: “For the deployment story, see github-pages.”

Size the piece to the argument

  • Reference pages: 250 to 600 words. A page that passes about 700 should split, with a wikilink between the parts; see internal-linking for the hub-and-spoke rules.
  • Long-form: split a piece that passes about 2,000 words into linked pieces.

Revise in two passes

  1. Cut the first paragraph if the second works as the lede. Repeat until the opening earns its place.
  2. Cut the closer if the previous paragraph ends the piece cleanly.

Then read it aloud once and rewrite any sentence that trips.

Backlinks