Decision log: what it is and a template to start with

A decision log is a running record of the important choices a team has made, with the reasons and the alternatives. It answers the question every new engineer eventually asks: why is it like this?

Key takeaways

• A decision without its reasoning gets re-argued later.
• Short entries are enough: context, options, decision, consequences.
• Store them where people will find them and link them to the work.
• Never edit history; supersede an old entry with a new one.

Why keep one

Systems hold the results of decisions but not the thinking behind them. Six months on, a strange design looks like an accident, and someone proposes changing it, only to rediscover the constraint that caused it. A log saves that round trip.

It also speeds up onboarding. A new teammate can read ten entries and understand more about the system than from a week of code reading.

What belongs in the log

Write an entry when a decision is:

• hard or expensive to reverse,
• shared across teams or services,
• a departure from the obvious approach, or
• likely to prompt a future "why?".

Skip small, easily reversed choices.

A simple template

# 0007: Use Postgres row-level security for tenant isolation

Date: 2026-03-14
Status: Accepted
Owner: Platform team

## Context
What problem are we solving, and what constraints apply?

## Options considered
1. Separate database per tenant: strong isolation, high operating cost.
2. Shared tables with a tenant column and app-level checks: simple, easy to get wrong.
3. Shared tables with row-level security: isolation enforced by the database.

## Decision
We use option 3.

## Consequences
- Every query must run with the tenant set.
- Migrations need to include policies.
- We revisit this if tenant count passes the level we planned for.

## Supersedes / superseded by
None yet.

Habits that keep it useful

1. Number and date entries so order is clear.
2. Record the rejected options. That is often the most useful part.
3. Supersede, do not rewrite. Add a new entry that links to the old one.
4. Link from the work. Attach the entry to the tasks and docs it affects.

In Osco, a decision log can be a folder of docs in a project, with entries linked to related tasks, endpoints and features. Coding agents can then read the reasoning over MCP before proposing a change that contradicts it.

Conclusion

A decision log costs a few minutes per entry and pays back every time someone asks why. Start with the template above, keep entries short and link them to the work.