Skip to content

SPEC.md

Latest commit

 

History

History
226 lines (136 loc) · 6.34 KB

SPEC.md

File metadata and controls

226 lines (136 loc) · 6.34 KB
Raw

TLDR.md Specification

This document defines the recommended format for a TLDR.md file.

The specification is intentionally lightweight. TLDR.md is a Markdown convention, not a schema, package, service, or validator. The goal is a short orientation layer that helps a human or AI coding agent become useful safely in one repository.

File location

A repository that adopts this convention SHOULD place the file at:

TLDR.md

The file SHOULD live at the repository root.

Audience

TLDR.md MUST be useful to both humans and AI coding agents.

It SHOULD avoid vendor-specific framing. Tool-specific instructions belong in adapter files such as AGENTS.md, CLAUDE.md, CODEX.md, Cursor rules, or equivalent systems.

Relationship to AGENTS.md

TLDR.md is the orientation layer. It SHOULD describe the repo map: what the repo is, what to inspect first, what matters, what is risky, how to validate changes, and where deeper docs live.

AGENTS.md is the behavior layer. It SHOULD describe how AI coding agents operate in the repo: when to read TLDR.md, how to handle conflicts, which workflow rules to follow, how to communicate uncertainty, and what checks to run before finishing.

A repository MAY use both files. In that setup:

  • AGENTS.md SHOULD point agents to TLDR.md.
  • TLDR.md SHOULD remain useful to humans who never read AGENTS.md.
  • TLDR.md SHOULD NOT contain detailed agent conduct rules.
  • AGENTS.md SHOULD NOT become the only place where repo orientation lives.

Required sections

The exact headings MAY vary, but every TLDR.md SHOULD cover the following information.

1. What this repo is

MUST explain the repository in a few concrete sentences.

Good answers include:

  • product, library, service, app, platform, or infrastructure role
  • primary language or framework
  • production relevance, if applicable
  • what the repo is not, when that prevents confusion

2. Fastest safe path

MUST list the first files, directories, or docs a newcomer should inspect.

This section SHOULD be ordered. Sequence matters because it prevents broad, wasteful scanning and helps the reader build the right mental model.

3. What matters most

MUST identify the small set of ideas, invariants, workflows, or boundaries that explain how the repo works.

This section SHOULD be short and concrete. Prefer bullets over paragraphs.

4. Safe entry points

MUST identify files, commands, modules, or workflows that are reasonable places to start.

Examples:

  • app entry point
  • API router
  • package exports
  • test fixtures
  • local development command
  • documentation source of truth

5. Do not touch casually

MUST identify risky areas.

Examples:

  • migrations
  • generated files
  • security-sensitive code
  • billing logic
  • data deletion paths
  • production deployment config
  • public API contracts
  • compliance evidence

Warnings SHOULD be visible and specific. Do not hide them in long prose.

6. How to validate changes

MUST include practical validation guidance.

This MAY include:

  • test commands
  • typecheck commands
  • lint commands
  • local smoke checks
  • migration checks
  • fixture regeneration steps
  • manual review steps

Commands SHOULD be current and runnable. Do not include stale command output.

7. Where deeper docs live

MUST point to the most important deeper docs.

This section SHOULD link selectively. TLDR.md is not a docs index.

Optional sections

Use optional sections only when they prevent confusion or unsafe work.

Architecture map

MAY describe major components and how data or requests move through them.

Common tasks

MAY list the safest path for common work such as adding an endpoint, updating a UI component, adding a migration, or changing a background job.

Agent notes

MAY include repo-specific notes useful to agents, as long as they remain AI-agnostic.

Avoid tool-specific instructions such as "Claude should..." or "Codex must..." in TLDR.md. Put those in adapters.

Glossary

MAY define domain terms, acronyms, or internal names.

Ownership

MAY identify maintainers, code owners, or review expectations.

Do not include private personal data. Link to public ownership files where possible.

Recent decisions

MAY summarize recent architecture decisions that materially affect current work.

Prefer links to ADRs or issues over long summaries.

Known traps

MAY list recurring mistakes, confusing names, test pitfalls, or misleading files.

Generated files

MAY identify generated files and the command or source that produces them.

Security boundaries

MAY identify authentication, authorization, secret handling, encryption, or audit logging boundaries.

Do not include secrets.

Data boundaries

MAY identify sensitive data flows, schema ownership, retention rules, deletion paths, or privacy constraints.

Deployment path

MAY summarize how changes reach production or where deployment docs live.

Testing strategy

MAY explain which tests matter for which changes and where fixtures live.

Recommended size

TLDR.md SHOULD usually be 100-250 lines.

Small repositories MAY use less. Very large repositories SHOULD keep the root TLDR.md concise and link to subsystem docs.

If the file becomes a manual, split details into docs and keep TLDR.md as the orientation layer.

Language guidance

TLDR.md SHOULD use direct language:

  • "Start here."
  • "Validate with this command."
  • "Do not edit generated files."
  • "This path owns public API behavior."
  • "If changing migrations, read this doc first."

TLDR.md SHOULD NOT use vague confidence language:

  • "Probably important."
  • "Maybe start here."
  • "There are many things to know."

If uncertain, mark uncertainty clearly:

Unconfirmed: this appears to be the main worker entry point, but a maintainer should verify.

Anti-patterns

Avoid these:

  • turning TLDR.md into a full manual
  • duplicating README
  • hiding important warnings in long prose
  • making it agent-specific
  • using it as secret storage
  • using it as a substitute for tests
  • including stale command output
  • letting it become a dumping ground
  • listing every file in the repo
  • linking every doc instead of the few that matter first
  • describing aspirational architecture that is not true yet
  • storing private user or team memory

Compatibility

TLDR.md is plain Markdown. It should work in GitHub, GitLab, editors, terminals, and agent contexts.

No tooling is required for adoption.