LLM Best Practices

Monorepo and polyrepo

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

A monorepo holds several projects, services, and libraries in one repository with shared tooling and history, so one pull request can change a library and every call site. A polyrepo gives each project its own repository, history, CI, and release cycle. Choose a monorepo when packages change together often and cross-repo version bumps slow releases. Choose a polyrepo when teams ship on independent schedules, need separate access control, or publish packages to outsiders.

Rules

  • A monorepo pays off only with build caching and affected-only CI (pnpm workspaces with Turborepo, Nx, or Bazel); otherwise pipelines grow with the repo.
  • The polyrepo cost is coordination: a breaking change means a PR and release in the server repo, then a dependency-bump PR in each client (semantic-versioning).
  • Repository layout is independent of build system: apps/web and packages/ui in one repo is a layout choice, not a tool requirement.
  • The full trade-off matrix is in monorepo-vs-polyrepo.

Backlinks