SOUL.md

In many software projects, alongside the actual program code, there are a few explanatory text files. They are written in the Markdown format, meaning plain text with a few characters for headings and lists. The best-known one is called README and explains how to install and use the project. SOUL.md is a more recent addition to this and answers a different question: why the project exists in the first place. It states what purpose it serves, which principles apply, what tone is desired, and what explicitly should not be built. The name alludes to the fact that it records the “soul” of the project rather than its technology.

Why projects are suddenly writing down their stance

The trigger for such files is AI-based coding assistants. These tools read in a project and, on request, write new code for it. They are very good at following rules that are written down somewhere. Anything that exists only in the team’s collective mind is invisible to them.

That is exactly where a problem arises. A team might have known for years that it doesn’t build in annoying pop-ups and doesn’t pass user data on to third parties. No one ever wrote that down, because it seemed obvious to everyone. An AI doesn’t know these unwritten rules and cheerfully suggests a pop-up. SOUL.md makes such tacit principles visible, and thus machine-readable.

A second reason concerns people. Projects go through staff changes, and open-source projects constantly receive contributions from strangers. A file that describes the purpose and boundaries in clear words saves lengthy discussions. It is therefore less an invention of AI than an old wish that AI has made urgent.

What such a file contains

There is no fixed format; SOUL.md is not an official standard. However, some recurring sections are common. At the beginning there is usually the purpose in two or three sentences. Then follow principles, often as a list of statements like “Speed matters more than feature richness.”

The section on boundaries is especially useful. It states what the project deliberately does not do. Such negative rules are more valuable to an AI than nice statements of intent, because they are clearly verifiable. Often there is also a section on tone, for example for error messages or texts in the user interface.

Technically, nothing magical happens here. The file is handed to the AI assistant as text along with the code. It treats its content like an instruction from the user. That is precisely why the rule applies: the more concrete the sentences, the better the effect. A sentence like “We love good quality” changes practically nothing; a sentence like “Do not integrate external advertising libraries” does.

SOUL.md, AGENTS.md, and the rest of the file family

Anyone browsing projects on platforms like GitHub will now come across a whole range of such files. AGENTS.md and CLAUDE.md contain technical instructions for AI assistants, such as which commands need to run for testing. CONTRIBUTING.md is aimed at human contributors. SOUL.md sits alongside these and covers the substantive level.

You can think of the difference like that with an intern. AGENTS.md is the list of workflows within the company. SOUL.md is the conversation about what the company cares about and where it won’t compromise. Both are needed, but they are different things.

In tech news, the term usually appears in connection with so-called vibe coding, meaning programming in which an AI writes the bulk of the code. A common misconception here is that the file is a safety measure. It is not: an AI can misunderstand or ignore instructions, and nobody technically enforces compliance. SOUL.md is a guide for orientation, not a lock on the door.