TLDR.md

A repo-local orientation layer for the fastest safe path to competence in a codebase.

TLDR.md is a short, maintained file at the root of a repository that tells a new human developer or AI coding agent what to inspect first, what matters, what is risky, how to validate changes, and where deeper documentation lives. It is not persistent memory, a README replacement, an agent rules file, or a docs index. It is a practical orientation layer that helps teams reduce rediscovery as codebases grow.

TLDR.md usually belongs at the repository root. For monorepos, multi-service systems, or multi-repository products, it may be useful to maintain a root TLDR.md for system-level orientation and additional TLDR.md files inside major service, package, or project folders for local context.

Public repository: https://github.com/Hello-GregKulp/TLDR.md. GitHub preserves the repository name casing, but users may see or share lowercase variants in URLs. Keep the public project name as TLDR.md.

The distinction

• README.md explains what the project is.
• Docs explain the system in depth.
• AGENTS.md and other agent rules tell tools how to behave.
• Persistent memory stores preferences across sessions.
• TLDR.md gives the fastest safe path to competence in this repo.

TLDR.md is a repo-local skill for understanding a codebase. Here, "skill" means a reusable capability or workflow. TLDR.md itself is the local orientation and context for one repository.

TLDR.md and AGENTS.md

TLDR.md is the orientation layer. It tells a human or agent what this repo is, what to inspect first, what matters, what is dangerous, and how to validate changes.

AGENTS.md is the behavior layer. It tells AI coding agents how to operate in the repo: read TLDR.md before non-trivial work, follow repo-specific workflow rules, handle conflicts, run checks, and communicate uncertainty.

The two files are complementary:

• Put repo orientation in TLDR.md.
• Put agent behavior instructions in AGENTS.md.
• In AGENTS.md, point agents to TLDR.md.
• Do not turn TLDR.md into an agent conduct file.
• Do not bury the repo map inside AGENTS.md, where humans may not know to look.

The problem

As repositories grow, humans and agents repeatedly rediscover the same orientation context. New contributors need to know which files matter, which docs are current, which commands are trustworthy, and where risky changes live.

AI coding agents can spend large amounts of context scanning broadly, infer architecture incorrectly, or touch unsafe areas because the repo does not expose its practical map. New human developers often need an experienced maintainer to sequence what to read first.

This is not a failure of README files or docs. It is a missing layer between "what is this project?" and "how do I safely become useful here?"

The solution

Add a short, maintained TLDR.md file at the repository root. It should tell humans and agents:

• what this repo is
• what to inspect first
• how the system fits together
• what not to touch casually
• how to validate changes
• where deeper docs live

The simplicity is the feature. TLDR.md should make repo knowledge explicit without adding a new toolchain, schema, package manager, build step, test suite, or service.

Why not just README?

README files usually serve many audiences: users, evaluators, contributors, package consumers, hiring candidates, and maintainers. They explain purpose, installation, usage, screenshots, badges, releases, and community expectations.

TLDR.md has a narrower job: orient someone who is about to work inside the codebase. It can mention architecture, risky files, generated code, validation commands, ownership boundaries, and "read these three files first" without making the README noisy.

Why not persistent memory?

Persistent memory stores preferences and remembered context across sessions, often outside the repository. That can be useful, but it is not enough for repo orientation.

TLDR.md travels with the code. It can be reviewed in pull requests, updated with architecture changes, and shared by every human and agent that opens the repository. It should not store private memory, user preferences, secrets, credentials, or sensitive operational details.

Why not just agent rules?

Agent rules, including AGENTS.md, tell a tool how to behave: coding style, shell safety, test expectations, communication preferences, and workflow constraints.

TLDR.md tells a newcomer what to understand: the entry points, system shape, risky areas, validation path, and current source of truth. Agent rules can tell an agent to read TLDR.md before non-trivial work, but the TLDR.md remains AI-agnostic and useful to humans too.

Install

Option 1: start from the template

Fetch the canonical template directly from the public repository:

curl -fsSL https://raw.githubusercontent.com/Hello-GregKulp/TLDR.md/main/templates/TLDR.template.md -o TLDR.md

Then edit the placeholders for your repository. This is a docs-only v0, so there is no CLI, package manager install, build step, or test suite required to adopt it.

Option 2: copy from a local clone

cp templates/TLDR.template.md /path/to/your/repo/TLDR.md

For small projects:

cp templates/TLDR.minimal.md /path/to/your/repo/TLDR.md

For multi-package repositories:

cp templates/TLDR.monorepo.md /path/to/your/repo/TLDR.md

Option 3: add an adapter note

Copy the relevant adapter into your own repo root or agent configuration. If your repo already has an AGENTS.md, add a short behavior instruction that points agents to TLDR.md instead of duplicating the orientation content there.

• adapters/AGENTS.md for AI-agnostic agent instructions
• adapters/CLAUDE.md for Claude
• adapters/CODEX.md for Codex
• adapters/CURSOR.md for Cursor
• adapters/.cursor/rules/tldr-md.mdc for Cursor rules

Minimal adapter text:

Before non-trivial edits, read TLDR.md at the repository root. TLDR.md is the orientation layer; this AGENTS.md file is the behavior layer. Follow TLDR.md's safe entry path, validation guidance, and warnings about risky areas. If it conflicts with user instructions or appears stale, surface the conflict before proceeding.

How to create a TLDR.md with an agent

Use prompts/generate-tldr.md with your preferred coding agent.

The agent should inspect the repository, identify real entry points, propose a reading sequence, find risky areas, and draft a TLDR.md. It should not invent facts. Uncertainty should be marked clearly and reviewed by a maintainer.

A good workflow:

1. Ask the agent to generate a draft using prompts/generate-tldr.md.
2. Review every command, warning, and architecture claim.
3. Delete anything speculative or redundant.
4. Add the file at the repository root as TLDR.md.
5. Add a short adapter note to your agent rules.

How to know it's working

TLDR.md is working when:

• a new contributor can name the main entry points after reading it
• an agent inspects the intended files before editing
• dangerous or expensive areas are visible before work starts
• validation commands are easy to find and actually run
• maintainers repeat less orientation context in issues and reviews
• stale or missing repo knowledge becomes easier to spot

Do not measure success by claiming exact token savings. The goal is a more direct pathway to useful, safe work.

Recommended size

Keep TLDR.md short enough to read quickly and long enough to prevent dangerous rediscovery.

For most repositories, prefer 100-250 lines. For very large repos, keep the root TLDR.md concise and link to deeper docs for subsystem details.

If TLDR.md becomes a full manual, split the details into docs and link out.

Maintenance

Update TLDR.md when any of these change:

• architecture or package layout
• main entry points
• validation commands
• generated files
• deployment path
• security, data, or migration boundaries
• areas that should not be touched casually
• docs that are now the source of truth

Treat TLDR.md like a small map that must stay close to the terrain.

Repository layout

README.md                 project overview and install guidance
TLDR.md                   this repo's own orientation file
SPEC.md                   file format and section guidance
PRINCIPLES.md             design principles
EXAMPLES.md               guide to example TLDR files
templates/                starter files for new repositories
examples/                 realistic example TLDR.md files
adapters/                 agent and editor adapter snippets
prompts/                  reusable prompts for generating and maintaining TLDR.md
CONTRIBUTING.md           contribution guidelines
LICENSE                   MIT license

Contributing

Contributions should preserve the core idea: TLDR.md is simple, local, AI-agnostic orientation. Good contributions improve examples, templates, prompts, adapter coverage, or wording clarity without turning the project into a framework.

See CONTRIBUTING.md for the PR checklist.

License

MIT. See LICENSE.

Summary

TLDR.md gives every repo a small, reviewable orientation layer: what to inspect first, what matters, what is dangerous, and how to validate change. It helps humans and agents reduce rediscovery and become useful faster without replacing README files, docs, tests, memory, or agent rules.