The New Code

Published on
Last updated on
AI Programming

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 =^\hat{=} intent conflict finder
  • Unit tests =^\hat{=} policy examples
  • Linters =^\hat{=} ambiguity highlighters

Specs give us the familiar toolchain, just pointed at intentions instead of syntax.

EVERYTHING IS A SPEC

GroupAlignsVia
Programmerssiliconcode specs
Product managersteamsproduct specs
Lawmakershumanslegal specs
AI engineersmodelsmodel 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
© 2025 Jennings Liu. All rights reserved.