FINANCE.md: An Open Standard for Financial Modeling Conventions
Open a financial model you did not build. Not a bad one, a good one, from a competent team. Within about four minutes you will hit a question the file cannot answer.
Are these amounts in thousands or units? Costs shown positive or negative? When this company says gross margin, does it include logistics or not? Does the year close in December or in June? Which of these three revenue lines is the one management actually steers on?
None of that is in the model. It is in someone's head, or in an email thread, or in a habit the team acquired four years ago and never wrote down. Every discipline that got serious about its craft eventually encoded its conventions in a file. Code has linters, formatters, and CLAUDE.md. Design has tokens and design system docs. Infrastructure has Terraform. Finance, which handles the numbers everything else is judged on, still runs on institutional memory.
FINANCE.md is the attempt to fix that. One file. Versioned. Readable by a person and by a machine. It travels with the model and says how to read it.
The Problem Is Not the Numbers, It Is Everything Around Them
Financial models fail on context far more often than they fail on arithmetic. The formula is right and the interpretation is wrong.
Three recurring examples, all of which cost real money:
A group reports in thousands. A subsidiary reports in units. Someone consolidates them without noticing, and a line comes out a thousand times too large. This is not a hypothetical, it is the single most common consolidation error there is, and no amount of formula auditing catches it because every formula is correct.
Two teams both report "adjusted EBITDA". One excludes stock compensation, the other does not. Both are defensible, both are labelled identically, and the comparison between them is meaningless.
A model shows costs as positive numbers, so net income is revenue minus costs. Another shows costs as negatives, so net income is a sum. Hand either to someone who assumed the other and they will produce a plausible, confidently wrong answer.
These are convention failures. They are invisible to review, they survive every check that looks at the math, and they compound quietly across every model built on top of the first one.
What Goes in the File
A FINANCE.md has two halves, which is the whole design idea: machine-readable front matter, human-readable body.
The front matter carries what an agent must know before touching anything.
organization: Distrib SAS
units: thousands
sign_convention: costs_positive
context:
activity: 'Food distribution, B2B, 12 warehouses'
purpose: annual_budget
closing_frequency: monthly
closing_lag_days: 10
reporting_standard: 'French GAAP (PCG)'
glossary:
- term: Marge brute commerciale
definition: 'Revenue minus purchase cost only. Excludes logistics.'
The body carries what a person needs: the closing calendar and its exceptions, why the net debt perimeter is drawn where it is, which restatements apply to which year and on whose instruction, the sector KPI your industry defines differently from everyone else.
Both halves travel with the model. Neither is a comment buried in a cell.
The categories worth covering, in rough order of how often their absence causes damage: units and sign convention, the closing calendar, the reporting standard, a glossary of company-specific terms, the definition of any adjusted metric, FX conventions and rate sources, the net debt perimeter, and the normalizations applied per period with their rationale.
Why This Became Urgent
Conventions have always mattered. Institutional memory carried them adequately for decades, because the number of people touching a model was small and they sat near each other.
AI broke that arrangement in a specific way. An agent building or modifying your model has no institutional memory at all, and unlike a junior analyst it will not hesitate before a convention it does not know. It will make a reasonable assumption, apply it consistently, and hand you a confident, internally coherent, wrong answer. Then next session it will make a different reasonable assumption.
This is the drift problem underneath most complaints about AI in finance. People describe it as the model being unreliable. Usually the model is fine and the context is missing. You explained your conventions in session one, the session ended, and the context went with it. Session two starts from zero and reinvents.
You can solve that by writing a very long prompt every time. Most people try this first. It works and it does not scale, because the prompt is now a file you maintain by hand, in a chat window, with no version history and no way to share it with the person who takes over your model.
Or you put the conventions in a file that lives with the model, gets versioned with the model, and gets read automatically before any agent touches anything. That is all FINANCE.md is. The idea is not clever. It is overdue.
It Works at Every Level
Conventions are not flat. A group has rules, a team has overrides, a specific deal has restatements that apply to nothing else. FINANCE.md nests the same way your organization does.
Sector template FINANCE.md PE LBO, SaaS FP&A, infrastructure
└── Organization group currency, reporting standard
└── Team M&A vs FP&A conventions
└── Model deal-specific restatements
An agent reading a model traverses the hierarchy and knows which convention applies at which scope, and why. The deal-level restatement overrides the team default, which overrides the group standard, and every level is inspectable. This is exactly how configuration works in every mature engineering stack, and there is no reason finance should be the exception.
What It Is Not
Worth being precise, because the format invites a few wrong assumptions.
It is not a data format. FINANCE.md does not hold your numbers. It holds the rules for reading them. The model is elsewhere.
It is not a replacement for documentation. A model still benefits from an explanation of its logic. FINANCE.md covers conventions, the things that are true across the whole file, not the reasoning behind a specific calculation.
It is not proprietary. It is published under MIT license. Anyone can adopt it, extend it, or fork it. We wrote it because we needed it, and a convention format that only one vendor can read would defeat the point entirely.
Adopting It
Start smaller than you think. A FINANCE.md with three lines in it, units, sign convention, and fiscal year end, already prevents the most expensive class of error on this page. Add the glossary the first time someone misreads one of your terms. Add the adjusted metric definitions the first time two teams disagree.
Put the file next to your other convention files, where anyone looking for it will look:
CLAUDE.md / AGENTS.md AI and coding conventions
DESIGN.md visual and product standards
FINANCE.md financial modeling conventions
The spec, the schema, and templates for LBO, SaaS FP&A, infrastructure and SME budget models are on GitHub. The full standard, with examples, is on the FINANCE.md page.
Layerz generates one automatically from your model structure and versions it alongside your model history, which is the part we sell. The standard itself is free and always will be, and it is more useful to us adopted widely than owned narrowly.
The Takeaway
Every mature discipline eventually writes its conventions down. Not because anyone enjoys writing documentation, but because the cost of not doing it shows up as errors that are invisible until they are expensive.
Finance held out longer than most, because institutional memory worked well enough while the people holding it stayed in the room. AI agents changed that calculation permanently. They have no memory between sessions, no hesitation about conventions they do not know, and an unfortunate talent for producing confident answers on wrong assumptions.
One versioned file, read before anything else, closes most of that gap. It is not a sophisticated idea. It is just one that finance has not adopted yet.