The New Code
Structured communication:
I felt it is very important to have clear communication before coding, much like the pre-AI era when we discussed requirements, achieved team alignment, and built shared understanding before starting. In the past week, I used qwen-code/zed to update ankihelper’s UI to modern Material Design. Each time, I had a clear vision of what I wanted to achieve, discussed requirements with the model to ensure clarity, and then began coding. Unlike before, when requirements were vague, I still didn’t save them in a spec file.
Moving forward, I will consistently create a spec for each feature.
notes from The New Code — Sean Grove, OpenAI
Structured communication is the bottleneck
- You talk with users to understand their challenges
- You distill these discussion and ideate concrete goals to alleviate those challenges
- You plan ways to to build those goals
- You share those plans with colleagues
- You translate those plans into code
- You test and verify that the result matches your plans and achieves your original goals
specification is more important than generated code
A written specification aligns humans.
Capture your intents and values in a specification
A written specification is what enables you to align humans - it’s the artifact that you discuss, debate, refer to, and sync on.
LOSSY VS LOSSLESS ARTIFACTS
Code is a lossy projection.
In the same way that decompiling a C binary doesn’t return you the original C source with comments and variable names…
…you can’t know all of the intentions and values from looking at the code produced from models. Instead, you try to infer.
LOSS-LESS FAN-OUT
Communication - the work we all already do - embodied in a specification is better than code.
Source code => compiler = target multiple architectures with no changes
Specification => models = TypeScript, Rust, iOS apps, servers, clients, documentation, tutorials, blog posts, even podcasts!
MENTAL MODEL: SIMILAR PROPERTIES
- Specs compose
- Specs are executable
- Specs are testable
- Specs have interfaces
- Specs can be shipped as modules
MENTAL MODEL: FAMILIAR SHAPE
- Type checker intent conflict finder
- Unit tests policy examples
- Linters ambiguity highlighters
Specs give us the familiar toolchain, just pointed at intentions instead of syntax.
EVERYTHING IS A SPEC
Group | Aligns | Via |
---|---|---|
Programmers | silicon | code specs |
Product managers | teams | product specs |
Lawmakers | humans | legal specs |
AI engineers | models | model specs (us!) |
Whether you realise it or not, you’re already spec authors.
PUT IT IN ACTION
- Start a spec for every AI feature
- Debate clauses, attach examples
- Make the spec executable
- Feed spec to the model
- Test against your spec