Thanks for helping improve TLDR.md.
This project should stay simple: a practical Markdown convention for repo-local orientation. Contributions should make it easier for humans and AI coding agents to understand a codebase safely without creating vendor lock-in or unnecessary tooling.
Good contributions usually do one of these:
- make the core idea clearer
- improve a template
- add or improve a realistic example
- add a small adapter for a common agent or editor
- improve prompts for generation, review, or maintenance
- remove wording that is vague, over-specific, or too heavy
Avoid changes that turn TLDR.md into:
- a full documentation framework
- a package manager or CLI requirement
- a schema-first project
- a replacement for README files
- a replacement for tests
- a vendor-specific convention
- a place to store secrets or persistent memory
- Use direct, practical language.
- Prefer concrete paths and commands.
- Avoid hype and exact token-saving claims.
- Keep examples generic and realistic.
- Keep TLDR.md AI-agnostic.
- Link out instead of duplicating long docs.
Before opening a PR, check:
- Does this make repo orientation clearer?
- Does it avoid becoming a README replacement?
- Is it AI-agnostic?
- Is it practical for both humans and agents?
- Does it avoid secrets?
- Does it include validation guidance?
- Does it preserve simplicity?
- Does it avoid vendor lock-in?
- Are examples realistic without referencing private systems?
- Are commands and paths plausible for the example being shown?
Examples should demonstrate a repository shape that many teams will recognize. They should include:
- what the repo is
- fastest safe path
- important boundaries
- risky areas
- validation guidance
- deeper docs
Do not include real secrets, customer names, private architecture, or company-specific details.
Adapters should be short. Their job is to tell an agent or editor to read TLDR.md before non-trivial work and to surface conflicts or staleness.
Do not move tool-specific behavior into the core TLDR.md format.