Skip to content

6.2. Readme

What is a README file?

A README.md file is the official front page for your project's repository. It's the first document users and developers will see, serving as a comprehensive guide that introduces your project, explains its purpose, and details how to install, use, and contribute to it.

Why is a README crucial for your project?

A well-crafted README is essential for project success. It serves multiple functions:

  • Attracts Users: A compelling overview and clear value proposition can draw in users and contributors, showcasing what makes your project unique.
  • Ensures Usability: By providing clear installation and usage instructions, you lower the barrier to entry, encouraging adoption and reducing user frustration.
  • Builds Trust: Including elements like build status badges, test coverage, and contribution guidelines demonstrates project health and professionalism, building confidence.
  • Provides a Quick Reference: It acts as a central hub for essential information, allowing even experienced users to quickly find what they need.

Investing time in a high-quality README is not just about documentation; it's about setting the first impression and fostering a strong community around your work.

What is the standard format for a README?

While plain text is an option, Markdown is the industry standard for README files. Its simple, intuitive syntax allows you to create well-structured and visually appealing documents with minimal effort.

For a deep dive into Markdown, check out the official Markdown Guide.

What are the essential components of a README?

A comprehensive README should be structured logically to guide the reader. Here are the key sections to include:

  • Project Title: A clear and concise name for your project.
  • Badges: Visual indicators for build status, code coverage, package version, etc. (Shields.io is a great resource).
  • Overview: A short, impactful paragraph describing what your project does and the problem it solves.
  • Visuals: A logo, screenshot, or diagram that quickly communicates the project's purpose or output.
  • Key Features: A bulleted list highlighting the main functionalities.
  • Installation: Detailed, step-by-step instructions to set up the project environment and install dependencies.
  • Usage: Code examples and clear explanations on how to use the project's core features.
  • Configuration: Instructions for configuring the project, if applicable.
  • Contributing: Guidelines for how others can contribute, including code style, pull request process, and how to set up the development environment.
  • License: A statement on the project's license (e.g., MIT, Apache 2.0).
  • Acknowledgments: Credit to any individuals or projects that provided inspiration or support.

How should you structure a README for an AI/ML project?

AI/ML projects have unique components that should be highlighted in the README. In addition to the standard sections, consider adding:

  • Model Architecture: A brief description or diagram of the model(s) used.
  • Dataset: Information about the dataset used for training and evaluation, including its source and any preprocessing steps.
  • Performance Metrics: Key results and evaluation metrics (e.g., accuracy, F1-score, Mean Squared Error) presented in a clear format, like a table.
  • Project Structure: An overview of the repository's layout to help others navigate your code.
  • Reproducibility: Instructions on how to reproduce your experiments, including specific versions of libraries and random seeds.

When should you write the README?

Start your README at the very beginning of your project and update it continuously. A README should evolve with your project.

Begin with a basic skeleton that includes the main headers. As you add features, update the corresponding sections. This iterative approach ensures your documentation never falls out of date and accurately reflects the current state of your project.

What if your README becomes too long?

If your README becomes overly long and difficult to navigate, it's a sign that your project needs a dedicated documentation site. This allows you to structure your content more effectively with features like a sidebar, search functionality, and multiple pages.

Popular tools for creating documentation sites include: - MkDocs: A fast, simple static site generator that's great for project documentation. - Sphinx: A powerful tool that can generate documentation in various formats. - GitHub Pages: A platform to host your documentation site directly from your repository.

Who else reads your repository?

Your README is written for a person: it sells the project, sets expectations, and walks a newcomer to their first successful command. But a growing share of the traffic through your repository is not human. AI coding agents open your project, look for orientation, and start editing.

They need different things than a person does. A human skims the README, then learns the conventions by reading code and by getting review comments. An agent has no review history, no colleague to ask, and a strong tendency to reach for whatever is most common on the internet rather than what is correct here. Left without guidance, it will invent a plausible command, pick the wrong tool, and produce a change that fails your gate.

The answer is a second front door: AGENTS.md.

What is AGENTS.md?

AGENTS.md is an open format for the instructions an AI coding agent needs to work in your repository. It is a plain Markdown file at the root of your project. There is no schema and no required section list: the format's only real convention is the filename and the location.

It matters because it is shared. The format emerged from a collaboration across several AI development companies (including OpenAI, Google, Cursor, and Factory) and is now stewarded by the Agentic AI Foundation under the Linux Foundation. A broad and growing set of tools reads it — OpenAI Codex, Cursor, GitHub Copilot's coding agent, goose, Gemini CLI, Zed, Aider, Jules, Devin, Windsurf, and many others.

Before it existed, every tool invented its own file: .cursorrules, .github/copilot-instructions.md, CLAUDE.md, .aider.conf.yml, and a dozen more. Repositories accumulated near-duplicate instruction files that were all subtly different because nobody could keep them in sync. One AGENTS.md replaces that pile. Tools that still want their own path can symlink to it.

All four repositories behind this course ship one: the course, the MLOps Python Package, the Cookiecutter MLOps Package, and the MLOps Coding Skills.

Why not simply put this in the README?

Because the two documents have different readers and different failure modes, and mixing them degrades both.

  • The README sells and onboards. It has to be readable, ordered by what a newcomer needs first, and tolerant of prose. Bury your commit-message convention and your typing rules in the middle of it and a human will scroll past them.
  • AGENTS.md instructs. It has to be exact, exhaustive on the points that matter, and utterly boring. Every sentence exists to prevent one specific class of wrong output.

So keep the split clean:

Belongs in README.md Belongs in AGENTS.md
What the project is and who it is for The exact task vocabulary and what each task runs
Installation and first-run instructions The definition of done a change must satisfy
Usage examples and configuration Conventions and idioms an agent would otherwise infer wrongly
Badges, screenshots, license, credits A map of the repository layout

Do not copy installation instructions into AGENTS.md, and do not move your conventions out of the README into it and nowhere else — a human contributor still needs to find them. Link between the two instead. The MLOps Python Package puts one line in its README:

> **AI agents**: read [`AGENTS.md`](AGENTS.md) for the full stack, task vocabulary, and conventions before contributing.

and one line at the top of AGENTS.md:

Context and rules for AI agents working in this repository. Humans should start with `README.md`.

What belongs in an AGENTS.md?

Four things earn their place. Everything else is optional.

1. The exact commands

Not a description of your workflow — the literal command line. This is the single highest-value content in the file, because a guessed command is the most common way an agent wastes a cycle.

- Everything: `mise run all` — format, check, test, build. This is the gate; CI runs this exact task and nothing else.
- Check: `mise run check` — `ruff` lint, `ty` types, `pip-audit` deps, `dprint`/`validate-pyproject`/`uv lock` format, `gitleaks` secrets, `trivy` filesystem scan, `hadolint` Dockerfile, `actionlint` + `zizmor` workflows.
- Test: `mise run test` — `pytest` with coverage (fails under 100%).

Note what that does: it names one canonical task, states that CI runs that exact task, and explains what each one covers. An agent now knows both what to run and why running something else is not equivalent.

2. A definition of done

An agent will stop the moment it believes it has finished. Tell it what finished means, and close the escape hatches explicitly:

A change is complete only when, locally, `mise run format` is clean, `mise run check` reports no findings, and `mise run test` is green with new/changed behavior covered by a test. Fix root causes — never weaken an assertion, add a skip/`xfail`, loosen a type, or suppress a lint error to force a green result.

The second sentence is the important one. Every way of faking a green result is cheaper than fixing the cause, so name them.

3. Conventions and idioms

These are the decisions an agent cannot recover from the code alone, or would recover wrongly because the internet's default differs from yours:

- **Errors with context**: raise specific exceptions and chain with `raise ... from err`; never use a bare `except`.
- **Config over hardcoding**: jobs and objects are Pydantic models parsed from OmegaConf YAML in `confs/`.
- **Typing**: modern annotations (`list[str]`, `X | Y`); keep `ty check` clean. `import typing as T` is the project convention.
- **MLflow**: tracking and registry run on a SQLite backend (`sqlite:///mlflow.db`); artifact files stay on disk under `./mlruns`.
- **Commits**: Conventional Commits (`feat:`, `fix:`, `refactor:`, `chore:`); no attribution in commit messages.

State the rule and the reason where the reason is not obvious. An agent that understands why a rule exists applies it correctly to cases you did not enumerate.

4. A layout map

A short tour of the directory structure saves an agent from reading the whole tree to find where a change belongs:

- `src/bikes/` — package: `core/` (metrics, models, schemas), `io/` (configs, datasets, registries, services), `jobs/` (tuning, training, promotion, inference), `utils/`.
- `confs/` — one OmegaConf YAML per MLflow job; `tests/` — `pytest` suite mirroring `src/`.
- `.github/` — `workflows/`, `dependabot.yml`, `zizmor.yml`, `rulesets/main.json`.

What does a complete AGENTS.md look like?

The MLOps Python Package uses five sections and fits on roughly one screen and a half:

# AGENTS.md

Context and rules for AI agents working in this repository. Humans should start with `README.md`.

## Project overview
<!-- name, purpose, language, stack, where the reusable practices live -->

## Setup & core commands
<!-- the canonical `mise` tasks, and the note that hooks and CI call the same ones -->

## Definition of done
<!-- what "complete" means, and the shortcuts that are forbidden -->

## Conventions & idioms
<!-- errors, config, typing, logging, MLflow storage, commit format -->

## Repository layout
<!-- what lives where, including the config files and the .github contents -->

Length is a real constraint: this file is read on every task, so it competes for the agent's attention with the code it is about to change. Aim for the shortest file that answers the questions an agent actually gets wrong. If a section is never violated, delete it.

What AGENTS.md cannot do

Here is the boundary that keeps this honest:

AGENTS.md guides. It does not enforce.

Nothing executes prose. An agent may misread it, ignore it, run out of context before reaching the relevant line, or simply be a different agent that never loaded it. A rule written only in AGENTS.md is a rule that holds most of the time — which, for anything that matters, is not enough.

Enforcement lives where it always has:

  • Types make an invalid state unrepresentable (ty, Pydantic, Pandera).
  • Tests fail when behavior regresses.
  • Linters and formatters reject the style before it is committed (ruff, dprint).
  • Git hooks and CI run those gates whether anyone remembers to or not.
  • Branch protection stops unreviewed work from reaching main.
  • Human review catches what none of the above can express.

Understood this way, AGENTS.md has a modest and useful job: make the first attempt land close, so your gates have less to catch and your reviewers spend their attention on design instead of on conventions. It is a productivity tool, not a control. If you find yourself writing "the agent must never..." for something genuinely dangerous, stop writing and go add a check.

How do you keep guidance files from drifting?

Guidance files rot faster than code, because nothing fails when they are wrong.

The MLOps Python Package proved it the expensive way. Alongside its AGENTS.md, it also carried a vendored copy of the seven Agent Skills under .gemini/skills/, duplicated from the MLOps Coding Skills repository they came from. Within a month, the copies had diverged from their sources by well over a hundred lines each — the worst by more than 170. By then those files were confidently instructing agents to set up task automation with just and git hooks with pre-commit: precisely the stack that release of the package had removed, in favor of mise and lefthook. Every agent that read them started from a stale picture of the project and had to be corrected by hand.

The copies were deleted, and the package's AGENTS.md now points at the source instead:

- **Skills**: the reusable practices behind this package are published as Agent Skills in [mlops-coding-skills](https://github.com/MLOps-Courses/mlops-coding-skills). Install them from there rather than vendoring a copy here — a copy drifts, and this repository already lost a month to proving it.

Four practices keep guidance honest:

  • Keep exactly one copy of any guidance file, and reference it from everywhere else. If a tool needs the content at its own path, use a symlink, never a duplicate.
  • Ground every statement in something real. Every command, path, flag, and version in your AGENTS.md must exist in the repository. A plausible-sounding instruction that does not work is worse than no instruction, because the agent will trust it.
  • Update it in the same commit that changes the tooling. If a pull request renames a task, it is incomplete until AGENTS.md says the new name.
  • Treat a correction as a bug report. Every time you tell an agent something it should have known, that is a line missing from AGENTS.md — or a line already there that is wrong.

What are Agent Skills, and how do they relate?

AGENTS.md covers this repository: its commands, its conventions, its layout. It is not the place for a reusable methodology, which would bloat the file and be copy-pasted into the next project anyway.

That is what Agent Skills are for. A skill is a folder containing a SKILL.md — YAML frontmatter plus Markdown instructions — that an agent loads on demand when a task matches its description. Because the agent only pulls a skill in when it is relevant, skills can be long and detailed without competing for attention on every task.

The practices taught in this course are published this way, one skill per chapter, in MLOps Coding Skills: mlops-initialization, mlops-prototyping, mlops-industrialization, mlops-validation, mlops-automation, mlops-collaboration, and mlops-observability. Install them from that repository — symlinked into .agents/skills/, or through your tool's own installer — and let each project's AGENTS.md stay short and specific to that project.

Where can you find inspiration and tools?

To create a high-quality README, leverage these excellent resources and tools:

Inspiration & Templates:

AGENTS.md and Agent Skills:

VS Code Extensions for Markdown: