tasks.md

tasks.md is an ordinary text file that belongs to a software project. It contains a list of tasks that still need to be done. The extension .md stands for Markdown, a very simple way of writing text: a hyphen at the start of a line creates a bullet point, hash signs create headings. The name is not an official rule, but a convention that many developers have agreed on. What is new is that this file is no longer read only by humans, but also by programs that write code themselves.

Why a simple text file steers the assistant

Programs that write code on command have a fundamental problem: they forget. Every new session starts from zero, because they don’t remember yesterday’s conversation. Anything that is meant to be remembered must therefore be written down somewhere. This is exactly the role that tasks.md takes on.

The file thereby acts like a handover log in a hospital. The night shift doesn’t know what was discussed during the day, but it reads up on what’s pending and what’s already done. An assistant does the same thing: it opens the file, sees the current state, and keeps working.

A second reason is the size of the jobs. An instruction like “Build me an online shop” is too vague to implement in one go. A list of twenty small items, on the other hand, is verifiable. After each item, one can test whether the result is correct before moving on.

From the assignment to the checked-off list

The file usually comes into being in two steps. First, one describes in ordinary sentences what the program should be able to do. Then one asks the assistant to turn this into a list of individual work steps. This list ends up as tasks.md in the project folder.

The entries follow a widespread Markdown notation: “- [ ] Build login form” for open, “- [x] Set up database” for done. The square brackets are displayed as clickable checkboxes on many platforms. For the assistant, they are simply a character that it can read and change. After each finished task, it sets the x itself.

It’s important to note the difference from a related file that often sits next to it. README.md or AGENTS.md contain permanent rules: which programming language applies, how the code is formatted. tasks.md, by contrast, only states what needs to be done right now. This file changes constantly, while the rules file stays largely the same.

A common mistake is to make the list as detailed as possible. Overly long lists cause the assistant to lose track and work on items twice. What has proven effective are tasks that can each be checked within a few minutes.

Where the file turns up in everyday practice

tasks.md is most commonly encountered in projects on platforms like GitHub, where software is publicly stored and jointly worked on. There it simply sits in the top-level folder next to the program code. Anyone can open it, since it’s plain text and requires no special software.

The file has become popular through tools like Claude Code, Cursor, or Codex. These assistants are allowed not only to read files in the project, but also to modify them. In these providers' guides, the task list appears as a recommended way of working. In articles on the subject, one often comes across the term “spec-driven development”, meaning development along a description laid out in advance.

The benefit remains, however, even without AI. Anyone working alone on a school project quickly loses the thread after a week’s break. A short list in the project folder answers the question of where one left off, within a few seconds.