.decisions/

Code has git.
Decisions have .decisions/

A lightweight convention for preserving the reasoning behind how a project evolves.

Codebases record what changed. But the reasoning behind decisions often disappears.

.decisions adds a simple folder to your repository where short notes capture why choices were made.

Humans and AI tools can both read and write them.

View the convention on

GitHub

Example:

.decisions/

project.md

                                        Purpose: open convention for preserving project reasoning

                                        Constraints: must stay simple no required structure

                                        Core stack: markdown, git

                                        Philosophy: short reasoning notes, not documentation

log.md

                                        2026-03-07 Removed structured templates. Too much friction, kills
                                        adoption.

                                        2026-03-07 Dropped AUTHORS.md from v1. Already covered in README, one less
                                        file to maintain.