spec-first
Skill0 starsChanged 7 days agoMITView on GitHub
Use when a request is vague, large, or will span more than one sitting, to turn it into docs/spec.md before any code is written. Also use when picking up work started earlier, to check the spec still matches reality.
We split this skill into the rules it gives an agent
4 rules. 0 are common, 2 are distinctive, and 2 are very specific to this project.
0
Common
Most of the 8 edited versions we read keep these.
2
Distinctive
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 20
When skipping, say so in one line rather than silently skipping.
- Very specific: line 28
Write docs/spec.md from templates/spec.template.md.
- Very specific: line 51
When a choice would be expensive to reverse and is not obvious from the code, add a short ADR in docs/decisions/, numbered, using …
- Distinctive: line 57
Never delete an ADR. Supersede it with a new one that links back.
“Common” is measured: kept by at least 6 in 10 of the 8 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Spec first
A spec exists to make disagreement cheap. Changing a paragraph costs nothing, changing a built system costs the build.
When to write one
| Write a spec | Skip it |
| More than about three moving parts | A notebook exploring a dataset |
| Anything deployed or multi-user | A single-page landing site |
| Anything storing personal data | A throwaway script |
| The request has an unstated success criterion | The request is one sentence and unambiguous |
When skipping, say so in one line rather than silently skipping.
Workflow
- Ask the questions that change the build, at most three, in one message. Good ones: who uses it, how they run it (script, web, scheduled), where the data comes from, whether anything is private, what "done" looks like. Bad ones: anything you could decide yourself and note as an assumption.
- Write
docs/spec.mdfromtemplates/spec.template.md. - Show the open questions and assumptions before building, not after. Assumptions are decisions the reader did not get asked about, so surface them.
- Build against the spec. When reality contradicts it, update the spec in the same commit as the code. A spec that lies is worse than no spec.
- Anything discovered and deferred goes in
TASKS.mdwith the reason, not just the task.
What a good spec has
- A problem statement that does not mention a solution. "Users cannot tell which followers matter" is a problem. "Build a ranking dashboard" is a solution wearing a problem's clothes.
- Success criteria that can be checked. "Ranks 10k followers in under 5 minutes" can be. "Fast and reliable" cannot.
- Explicit non-goals. This is the section that prevents scope creep, and the one most often left out.
- Constraints: budget, rate limits, privacy, deadlines, what must not change.
- The chosen approach, and the rejected ones with the reason. Six months later the rejected options get re-proposed unless the reason is written down.
- Open questions with an owner, so it is clear what is blocked on whom.
Decision records
When a choice would be expensive to reverse and is not obvious from the code, add a short
ADR in docs/decisions/, numbered, using docs/decisions/0001-record-decisions.md as the
shape. Five sentences is a normal length. Examples worth recording: the database, the
hosting model, the auth model, a dependency with a licence implication, anything chosen
against the obvious default.
Never delete an ADR. Supersede it with a new one that links back.
Other versions10 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 10
- rohunvora/my-claude-skills★ 6same name
- genfeedai/genfeed.ai★ 4same name
- MissingPackage/nightshift★ 3same name
- 223mle/skills★ 1same name
- soilSpoon/skills★ 1same name
- Jinbae10/skills★ 0same name
- Kylianmgt/spec-first-skills★ 0same name
- marcin-urbanski/claude-skills★ 0same name
- paulowsousa/spec-first★ 0same name
- vindreshsingh/engineering-skills★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository8 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- .github/copilot-instructions.mdCopilot instructions
- design-taste-frontendSkill
- iac-templatingSkill
- project-bootstrapSkill
- readme-writerSkill
- swiftui-expert-skillSkill
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.