spec-md
give your agents
the briefing they need.
a single markdown file that tells every developer and AI agent exactly how your codebase is built, what's decided, and what to work on next.
the problem
AI agents are powerful but blind. drop one into an unfamiliar codebase and it'll guess at architecture, re-litigate settled decisions, and pick up tasks it can't handle — because nothing told it not to.
no architecture context → wrong abstractions
no decision log → past choices relitigated
no roadmap tags → wrong tasks picked up
no complexity score → agent treads too lightly or too heavily
the solution
SPEC.md is the briefing file. four required sections, one markdown file,
zero tooling. lives in the repo root, versioned with the code, never drifts.
think of it like agents.md for agent behavior — but for architecture.
any agent or developer can read it and be productive in minutes.
| section | heading | gives agents |
|---|---|---|
| architecture | ## architecture | system design, components, boundaries |
| roadmap | ## roadmap | open tasks scoped by component and difficulty |
| decisions | ## decisions | what was chosen and why — stops re-litigation |
| complexity score | ## complexity score | how carefully to tread, per layer |
built for agents
component tags `[api]` `[cli]` `[ui]` tell an agent exactly which subsystem a task belongs to — no guessing, no sprawl.
difficulty tags [easy] [medium] [hard] let agents self-select appropriate tasks without human triage.
the decisions section is a settled record. agents read it and move on — they don't propose alternatives to choices already made.
the complexity score tells an agent how much care a change requires before it touches anything. a 4/5 storage layer gets different treatment than a 1/5 config file.
example
# SPEC — my-project
## architecture
rest api (go) → postgres → s3 for assets.
auth via jwt; no session state on the server.
## roadmap
### near term
- [x] `[api]` basic crud endpoints [easy]
- [ ] `[api]` rate limiting [hard]
- [ ] `[cli]` export command [medium]
### ideas
- [ ] `[ui]` dark mode toggle [easy]
## decisions
- **jwt over sessions**: stateless; scales horizontally without shared cache.
- **postgres over nosql**: relational model fits the data; team knows sql.
## complexity score
| dimension | score | notes |
| :-------- | :----- | :--------------------------- |
| overall | 3 / 5 | moderate; async job queue |
| api | 2 / 5 | thin rest layer |
| storage | 4 / 5 | custom migrations, no orm |get started in 30 seconds
curl -O https://raw.githubusercontent.com/mirageglobe/spec-md/main/template/SPEC.md
drop SPEC.md in your repo root and fill in each section. —
or browse the blank template
and worked example on GitHub.