10. When are specifications not enough?

AI coding tools are fast for one developer working on small, contained tasks. A small application that its team can hold in mind works well with a written specification for each change, which the coding agent builds from and the reviewer checks against. Specifications start to fall short as the application grows complex: a large existing system, a legacy code base, or work that crosses team boundaries. Each specification describes one change, and knows little about the rest of the application. Specifications drift from the code under deadline pressure. A specification carries the product owner's functional knowledge, and little of the design, architecture and code knowledge the change depends on. Writing specifications becomes the slowest step in the process. The knowledge graph sits alongside the specifications and supplies the design, architecture and code knowledge they lack. Each specification still describes the change, and the knowledge graph describes the application the change lands in.

On the site: The Four Zones · When This Zone Stops Working · From SDD to SE