The post has been translated automatically. Original language: Russian
In the early 2000s, I read a lot about Joel on Software. Joel Spolsky already had the experience of Microsoft and his own company Fog Creek Software, and his articles gradually became for us something like a practical textbook on real development.
He wrote not only about the code, but also about things that seem secondary before the first serious project. One of these topics is the specification. On October 2, 2000, Joel published the article Painless Functional Specifications, Part 1: Why Both?. Her main idea was simple: if you don't agree in advance exactly what the program should do, the risk of expensive misunderstandings increases dramatically.
I was convinced of this in a rather painful way at the time.
Everything started out fine
The customer described the task to me. I listened carefully, assessed the amount of work, named the price and deadlines. Everything was fine with everyone, we signed a contract, and I started developing it.
I completed the program on time and came to take it. It would seem that the usual acceptance should have started further, but then it turned out that the result was accepted by a completely different person — not the one who set the task and with whom I discussed the requirements.
The new receptionist had his own idea of how everything should work. I show the finished system, and in response I hear: it needs to be different here, this should not be, but this, on the contrary, needs to be added.
From his point of view, everything was logical. He accepted the system and expected to see what he thought was right. It was also logical on my part: I did exactly what was explained to me at the beginning of the project.
The problem wasn't that someone was necessarily wrong. The problem was the lack of a sufficiently accurate document that would unequivocally answer the question.: What exactly did we agree to do?
And I had to redo it
The deadline has already arrived, the contract has been concluded, and the price has been fixed. Explaining to the receptionist that "another person told me something completely different" is almost useless: he needs to adopt a system that will be used later.
Therefore, the program had to be redone literally on the go, and for the same money and in about the same time frame.
It's at moments like this that you quickly begin to understand the value of a specification. Not as a beautiful document for the archive, but as a way to preserve the original agreement between the parties.
The specification is needed not only by the programmer
Before such an experience, it is easy to think that the technical task is necessary for the developer only so that he does not forget anything. In practice, it is necessary for all project participants.
A customer can consist of dozens of people. One sets the task, the other coordinates the budget, the third accepts the result, and the fourth then works with the system. Each of them may have their own idea of what the phrase "the system should do X" means.
As long as everything exists only in conversations, it seems that everyone understands each other. Discrepancies are usually discovered too late, after a significant part of the system has been written.
That's where Joel was right: not having a specification doesn't save time. It simply moves the discussion of requirements to a later stage, when changes are already much more expensive.
The specification is the project's memory
Over time, I began to look at the specification even more simply: it is a memory of what the parties decided at a particular moment.
People forget details, employees change, someone gets fired, someone gets transferred, a new manager comes in. And the project continues. If everything important is left only in the head of the person who set the task, after his departure, a new version of the requirements actually appears.
The document allows us to separate two completely different questions: "what do we want to change now?" and "what did we initially agree on?".
The first is the normal development of the project. The second is a potential conflict.
And now there's AI.
In 2026, this problem has become even more interesting. AI dramatically speeds up implementation: today you can describe a task and get a working prototype in a few minutes, and a significant part of the application in a day.
Because of this, it is easy to decide that the specification has become less necessary. In my opinion, the opposite has happened.
If previously a poorly set task slowly turned into the wrong program, today AI is able to make the wrong program very quickly. The speed of implementation has increased, but the price of ambiguity has not disappeared.
You can tell the AI, "Make an application accounting system," and it will actually write the code. But what is an application? Who can create it? Is it possible to change it after registration? Who's closing it? Do I need a history of changes? What happens when a failure occurs?
The AI doesn't know what exactly the customer meant. He just fills in the blanks faster with his own assumptions.
The specification is now also becoming an input for AI.
Previously, a specification was basically an agreement between people and a guideline for the programmer. Now it is also becoming an instruction for AI.
The more precisely the behavior, constraints, and outcome criteria are defined, the less the model has to figure out for itself. Therefore, I would formulate Joel's old thought today as follows:: the faster we can write code, the more important it is to agree in advance which code to write at all.
It is in this sense that the specification becomes not a bureaucracy, but a way to keep the meaning of the project.
What did I learn from that acceptance
After the incident with the new receptionist, I became much more careful about verbal demands. Even if it seems that the task is simple and everyone understands everything, it is useful to fix at least the main scenarios and the expected result.
It's not necessary to turn every small project into hundreds of pages of documentation. But there must be a place where you can look and say, "That's what we agreed on."
If the customer wants otherwise after that, no problem. Requirements may vary. But then it's a change in requirements, not a dispute about what someone once supposedly had in mind.
After a quarter of a century
Joel wrote about specifications back when programming took much longer and AI couldn't generate code. Today, his thought looks even more practical.
You can speed up compilation, testing, and writing of code. But if two people understand the end result differently, no amount of development speed will solve this problem.
Once I understood it very simply: one person set me a task, and another came to take the job. And the finished program had to be redone for the same money.
After that, you start to respect a well-written specification very much.
В начале 2000-х я много читал Joel on Software. Джоэл Спольски уже имел опыт Microsoft и собственной компании Fog Creek Software, а его статьи постепенно становились для нас чем-то вроде практического учебника по реальной разработке.
Он писал не только о коде, но и о вещах, которые кажутся второстепенными до первого серьёзного проекта. Одна из таких тем — спецификация. 2 октября 2000 года Джоэл опубликовал статью Painless Functional Specifications, Part 1: Why Bother?. Её основная мысль была проста: если заранее не договориться, что именно должна делать программа, риск дорогих недоразумений резко возрастает.
Я в своё время убедился в этом довольно болезненным способом.
Всё начиналось нормально
Заказчик описал мне задачу. Я внимательно выслушал, оценил объём работы, назвал цену и сроки. Всех всё устроило, мы заключили договор, и я начал разработку.
Программу я сделал в установленный срок и пришёл её сдавать. Казалось бы, дальше должна была начаться обычная приёмка, но тут выяснилось, что результат принимает совсем другой человек — не тот, кто ставил задачу и с кем я обсуждал требования.
У нового приёмщика было своё представление о том, как всё должно работать. Я показываю готовую систему, а в ответ слышу: здесь нужно иначе, вот этого не должно быть, а вот это, наоборот, необходимо добавить.
С его точки зрения всё было логично. Он принимал систему и ожидал увидеть то, что считал правильным. С моей стороны всё тоже было логично: я сделал именно то, что мне объяснили в начале проекта.
Проблема была не в том, что кто-то обязательно ошибался. Проблема была в отсутствии достаточно точного документа, который однозначно отвечал бы на вопрос: что именно мы договорились сделать?
И пришлось переделывать
Срок уже наступил, договор заключён, цена зафиксирована. Объяснять приёмщику, что «мне другой человек говорил совсем другое», практически бесполезно: ему нужно принять систему, с которой потом будут работать.
Поэтому программу пришлось переделывать буквально на ходу, причём за те же деньги и примерно в те же сроки.
Вот в такие моменты очень быстро начинаешь понимать ценность спецификации. Не как красивого документа для архива, а как способа сохранить исходную договорённость между сторонами.
Спецификация нужна не только программисту
До такого опыта легко думать, что техническое задание нужно разработчику только затем, чтобы он ничего не забыл. На практике оно нужно всем участникам проекта.
Заказчик может состоять из десятков людей. Один ставит задачу, другой согласовывает бюджет, третий принимает результат, четвёртый потом работает с системой. У каждого из них может быть своё представление о том, что означает фраза «система должна делать X».
Пока всё существует только в разговорах, кажется, что все друг друга поняли. Расхождения обычно обнаруживаются слишком поздно — уже после того, как значительная часть системы написана.
Именно здесь Джоэл был прав: отсутствие спецификации не экономит время. Оно просто переносит обсуждение требований на более поздний этап, когда изменения уже стоят гораздо дороже.
Спецификация — это память проекта
Со временем я стал смотреть на спецификацию ещё проще: это память о том, что стороны решили в конкретный момент.
Люди забывают детали, меняются сотрудники, кто-то увольняется, кого-то переводят, приходит новый руководитель. А проект продолжается. Если всё важное осталось только в голове человека, который ставил задачу, после его ухода фактически появляется новая версия требований.
Документ позволяет отделить два совершенно разных вопроса: «что мы хотим изменить сейчас?» и «о чём мы договаривались изначально?».
Первое — нормальное развитие проекта. Второе — потенциальный конфликт.
А теперь есть ИИ
В 2026 году эта проблема стала ещё интереснее. ИИ резко ускоряет реализацию: сегодня можно описать задачу и через несколько минут получить работающий прототип, а за день — значительную часть приложения.
Из-за этого легко решить, что спецификация стала менее нужна. На мой взгляд, произошло обратное.
Если раньше плохо поставленная задача медленно превращалась в неправильную программу, то сегодня ИИ способен сделать неправильную программу очень быстро. Скорость реализации выросла, а цена неоднозначности никуда не исчезла.
Можно сказать ИИ: «Сделай систему учёта заявок», и он действительно напишет код. Но что такое заявка? Кто может её создавать? Можно ли менять её после регистрации? Кто закрывает её? Нужна ли история изменений? Что происходит при отказе?
ИИ не знает, что именно заказчик имел в виду. Он просто быстрее заполняет пробелы собственными предположениями.
Спецификация теперь становится ещё и входом для ИИ
Раньше спецификация была в основном договорённостью между людьми и ориентиром для программиста. Теперь она становится ещё и инструкцией для ИИ.
Чем точнее определены поведение, ограничения и критерии результата, тем меньше модели приходится додумывать самой. Поэтому старую мысль Джоэла сегодня я бы сформулировал так: чем быстрее мы умеем писать код, тем важнее заранее договориться, какой код вообще нужно писать.
Именно в этом смысле спецификация становится не бюрократией, а способом удерживать смысл проекта.
Что я вынес из той приёмки
После истории с новым приёмщиком я стал гораздо осторожнее относиться к устным требованиям. Даже если кажется, что задача простая и все всё поняли, полезно зафиксировать хотя бы основные сценарии и ожидаемый результат.
Не обязательно превращать каждый небольшой проект в сотни страниц документации. Но должно существовать место, куда можно посмотреть и сказать: «Вот об этом мы договорились».
Если после этого заказчик хочет иначе — никаких проблем. Требования могут меняться. Но тогда это уже изменение требований, а не спор о том, что кто-то когда-то якобы имел в виду.
Через четверть века
Джоэл писал о спецификациях ещё тогда, когда программирование занимало намного больше времени, а ИИ не умел генерировать код. Сегодня его мысль выглядит ещё практичнее.
Можно ускорить компиляцию, тестирование и написание кода. Но если два человека по-разному понимают конечный результат, никакая скорость разработки эту проблему не решит.
Когда-то я понял это очень просто: один человек поставил мне задачу, а принимать работу пришёл другой. И готовую программу пришлось переделывать за те же деньги.
После такого начинаешь очень уважать хорошо написанную спецификацию.
Share
