Skip to main content
Spec Led is a simple way to keep intent clear as code changes. It puts a small spec in the repo, next to the code. Humans can read it. AI can use it. The team can check it as the code changes.

​
The main point

Specs are useful because they are part of a loop. The loop is:
  1. write intent
  2. build from it
  3. verify it
Without that loop, a spec is just another document.

​
The basic idea

You write short spec files for the important parts of a codebase. Those specs say:
  • what the code should do
  • what should stay true
  • what tests or checks should prove it
  • any approved exceptions

​
What makes it useful

Because the spec is in the repo:
  • humans can get up to speed faster
  • AI has a clearer target
  • tests and docs have a contract to line up with
  • drift is easier to catch in CI
  • the team has one place to point to when behavior changes

​
Who this is for

  • TypeScript apps and libraries
  • APIs
  • services
  • tools
  • workflows
It can work in other languages too.

​
What it is not

  • not a code generator
  • not a replacement for tests
  • not a replacement for design work
  • not a magic way to remove ambiguity
It is a small contract layer that helps teams keep meaning attached to the code.