Spec-First Development is a software development practice consistently followed by Jan_Wilmake for over two years (as of April 2026): before writing code, write a SPEC.md file — a plain-text specification of what the software should do. In the era of LLM agents, this practice has become doubly valuable: the SPEC file serves both as a design discipline for the human and as the primary context document for the coding agent.
Jan's approach, described in response to Karpathy's viral thread on LLM knowledge bases in April 2026: "I've done this for over 2 years. Just search in my github for SPEC.md."
A SPEC.md file typically contains:
The file lives in the repository root alongside code, serving as both documentation and agent instruction.
Before LLM coding assistants, SPEC files were principally a human design discipline — forcing the developer to think through the problem before implementing. In the agentic era, the SPEC file takes on a second function: it is the primary context document fed to the coding agent. An agent that reads a SPEC before writing code produces dramatically better output than one that is prompted with vague instructions.
This is why Jan connected his SPEC.md practice to Karpathy's thread about LLM knowledge bases: both involve the insight that pre-written structured text is the substrate that makes LLMs useful. Jan had already been treating his own repositories as structured knowledge sources — the SPEC.md pattern being the most direct expression of this.
The SPEC-first practice connects to several threads in Jan's broader thinking:
A notable consequence of this practice: Jan's GitHub repositories contain SPEC.md files as a matter of routine, making them more agent-accessible than typical repositories. When uithub is pointed at a Jan Wilmake repository, the SPEC.md provides meaningful context that a coding agent can use immediately.