Я вже два місяці не написав жодної функції руками. Кодова база ніколи не була здоровішою. Два роки тому ця фраза звучала б як маркетинг. У 2026 це просто нова база, і інженери, які цього не бачать, ось-ось втратять сходинку, на якій стояли, не помічаючи.
Це design-time-двійник посту про контекст-інжиніринг. Контекст-інжиніринг — це те, що рантайм збирає у момент виконання. Spec-driven development — це те, що пише команда і з чого рантайм потім збирає. Це дві сторони одного зсуву, і не можна всерйоз займатися однією, не зайнявшись іншою.
Теза тут жорсткіша, ніж людям зручно. Ваша кодова база більше не ваша кодова база. Ваші специфікації — так. Код — це просто кеш.
Зсув: код як кеш, специфікація як істина
Тридцять років вихідний код був довговічним артефактом, а все інше — тікети, вимоги, архітектурні документи — прикрасами навколо нього. Код був єдиним місцем, де жила істина. Все інше дрейфувало.
У 2026 ці стосунки перевертаються у багатьох командах, включно з моєю. Довговічний артефакт — це специфікація: файл, який читає агент, eval-набір, проти якого її перевіряють, обмеження, яким зобов’язана коритися система. Код — це те, що регенерується зі специфікації на вимогу. Якщо видалити код і залишити специфікацію, код можна виробити заново. Якщо видалити специфікацію і залишити код — ви втратили істину, і успіхів у реверс-інжинірингу з папки .ts-файлів, до якої останніми торкалися три різні агенти.
Це не гіпотеза. Це практична реальність кодової бази, де більша частина написання коду делегована. Код перестає бути джерелом істини, бо більше немає одного автора, який тримає його в голові. Цю роль зобов’язана взяти специфікація, інакше — ніхто.
Це змінює все, що йде вниз за течією: ревʼю, тестування, онбординг, найм. Дійдемо до кожного.
Що таке «специфікація» у 2026
Специфікація — це не документ вимог. Не user story. Не сторінка у wiki, яку хтось написав шість місяців тому і відтоді ніхто не торкався.
Специфікація у 2026 — це виконуваний артефакт, який агент читає напряму, проти якого його оцінюють і з якого він виробляє код. У неї є три конкретні форми, які зустрічаються у зрілих команд.
| Старий артефакт | Еквівалент-специфікація 2026 | Що змінилося |
|---|---|---|
| Тікет у Jira | Feature-специфікація | Виконувана агентом, а не бажана; лежить у репо, а не в трекері |
| README | CLAUDE.md / AGENTS.md / правила репо | Читається машинами, а не лише людьми; примусово, а не декоративно |
| Архітектурний документ | System-специфікація + eval-набір | Перевіряється, а не вшановується; ревʼюїться при зміні |
| Коментар у коді | Inline-специфікація | Керує поведінкою, а не просто описує |
Формат Anthropic Skills, GitHub Spec Kit, поява файлів AGENTS.md у корені репозиторіїв — це не розрізнені тренди. Це один і той самий тренд під різними шапками. Індустрія колективно усвідомлює, що довговічний вхід для агентських систем має жити у файлі, а не у промпті, і цей файл має ревʼюїтися та версіонуватися так само, як код.
Ієрархія специфікацій
У зрілій spec-driven кодовій базі ви знаходите чотири рівні, вкладених один в одного.
Системна специфікація. Інваріанти. Архітектурні правила. Межі безпеки. Обмеження роботи з даними. «Усі відповіді API — JSON; PII не покидає БД; авторизація на edge, а не в хендлерах». Ці рідко змінюються і рідко належать одній фічі. Вони живуть у корені репо — у AGENTS.md або еквіваленті.
Feature-специфікація. Що робить можливість. Приклади та контр-приклади. Критерії приймання. Eval-набір, за яким фіча утримується. Ці переписуються, коли фічі еволюціонують. Вони живуть поруч із кодом, який описують, часто як feature.md-сусід директорії реалізації.
Task-специфікація. Одиниця, яку агент виконує за один прогін. Вужче за фічу: «Додай middleware-обмежувач частоти, який використовує наявний Redis-клієнт і випромінює ту саму телеметрію, що й auth middleware». Часто ефемерна, але версіонується у описі PR чи task-файлах.
Inline-специфікація. Правила, вбудовані у файли репо — CLAUDE.md, AGENTS.md, коментарі до схем, директорійні README.md, які агент читає як контекст всього, що робить у цій директорії.
Що працює: маленькі специфікації, скомпоновані разом. Великі специфікації протікають. Двотисячослівна feature-специфікація, що покриває п’ять задач, агентом (або людиною) виконується гірше, ніж п’ять трисотслівних, що покривають по одній задачі.
Що змінюється, коли специфікації стають first-class
Щойно специфікація — довговічний артефакт, робочий процес нижче за течією змінює форму:
- Code review стає spec review. Ревʼю PR з двома сотнями рядків згенерованого агентом коду — невдячна робота: код зазвичай нормальний механічно. Ревʼю специфікації, що його виробила, — високоважлива робота: там реально приймаються рішення. Команди, які не перенесли увагу ревʼю на специфікацію, досі витрачають час сеньорів на код, який агент згенерує заново з виправленої специфікації за двадцять секунд.
- PR description стає spec diff. «Я змінив специфікацію політики rate-limit з X на Y; код регенерований під неї» — значно кращий опис PR, ніж стіна змінених файлів. Diff, що цікавий людям, — це spec diff. Code diff — його наслідок.
- Тестування стає eval. Юніт-тести досі існують. Але високоцінне тестування — чи виконує фіча специфікацію на різних входах, крайових випадках і ворожих умовах — виглядає більше як eval-набір, ніж як файл юніт-тестів. Evals прив’язані до специфікації; змінюється специфікація — змінюються evals у тому ж коміті.
- Дебаг стає spec-gap-аналізом. «Чому агент згенерував неправильний код?» перетворюється на «Де в специфікації цей випадок недоспецифікований?». Баг майже завжди у специфікації, а не в коді, який вона виробила. Ставитися до специфікації як до джерела багів — це найвищоважливіша зміна workflow, яку я зробив за два роки.
- Онбординг стає читанням специфікацій, а не читанням вихідників. Нові інженери не розганяються, читаючи кодову базу. Вони розганяються, читаючи системну специфікацію, потім feature-специфікації тих областей, де працюватимуть. Код іде вниз за течією — і вони самі швидко його зроблять, коли зрозуміють обмеження.
Кредитне плече сеньорного інженера у 2026 — у написанні специфікацій, які агенти інших людей виконають правильно.
Це та частина зсуву, яка б’є по сеньорах найсильніше — і в обидва боки. Кредитне плече величезне. Діяльність незвична. М’язова пам’ять «писати код руками» починає атрофуватися, якщо активно не вирішувати, які задачі ще цього варті.
П’ять правил написання специфікацій, яким агенти справді коряться
Пронумеровані, бо вироблені у продакшені, а не виведені з блог-постів.
1. Виконувана, а не бажана. Кожній специфікації потрібна перевірка приймання. «Ця фіча має бути user-friendly» — це не специфікація, це побажання. «Коли користувач надсилає форму без email, поверни 400 з тілом {error: 'email_required'} і залогуй подію validation_failed з ID форми» — це специфікація. Правило: якщо з однієї специфікації не можна написати тест — специфікація не готова.
2. Показуйте приклади і контр-приклади. Агенти швидше вчаться на контрасті, ніж на правилах. Специфікація «імена мають бути у sentence case» слабша за специфікацію, що додає «Приклад: ‘Annual revenue’. Контр-приклад: ‘annual_revenue’ або ‘AnnualRevenue’». Завжди показуйте, як вихід не має виглядати. Ось де живе справжня керованість.
3. Називайте режими відмови. Позитивні специфікації («Завжди роби X») слабші за негативні («Ніколи не роби Y»). Агент надійніше кориться «не ходи в БД з хендлера», ніж «використовуй шар репозиторію». Обидва місця у специфікації, але якщо можна написати лише одне — пишіть заперечення.
4. Версіонуйте специфікації як код. Специфікації лежать у репо. У них є історія. Їх ревʼюять у PR. Їх звинувачують, коли щось ламається. «Зміна специфікації без зміни коду» — це реальна форма PR у 2026: іноді головна зміна — специфікація, а регенерація коду — наступний крок. Ставитися до специфікацій як до коду — не обговорюється; решта розвалюється, якщо специфікації дрейфують.
5. Одна специфікація — одна можливість. Великі специфікації протікають. Специфікація, що покриває аутентифікацію і rate-limit і логування, виробить код, де одна з цих трьох задач стабільно злегка не так. Розділяйте. Композиціюйте можливості. Той самий інстинкт «маленькі функції, єдина відповідальність» застосовний до специфікацій із подвійною силою.
Де це розвалюється
Я продавав би вам щось, якби зупинився тут. Є реальні випадки, де spec-driven development — невірний фрейм, і вдавати протилежне означає обпектися.
- Розвідка і дослідницька робота. Ви ще не знаєте, що специфікувати. Ви вивчаєте форму проблеми. Писати специфікацію до розуміння проблеми — це карго-культ інженерії. У цих фазах пишіть код руками, читайте вихід, потім виймайте специфікацію з того, що спрацювало. Специфікація після, а не спочатку.
- Перфоманс-критичний код. Гарячі цикли, чутливий до memory layout код, щільні внутрішні ядра — агент виробить щось, що відповідає специфікації, але удвічі повільніше, ніж потрібно, способами, які специфікація передбачити не могла. Пишіть такі шматки руками. Специфікуйте поверхню; ядро — руками.
- Археологія легасі-коду. «Зміни цю чотирнадцятирічну функцію» — рідко spec-driven задача. Читайте код, розумійте, що він робить, потім вирішуйте. Специфікації — для руху вперед; археологія — окрема дисципліна.
- Випадки, коли специфікація довша за код. Якщо ваша специфікація сто рядків, а код двадцять — ви переспецифікували. Співвідношення spec-to-code має sweet spot, і його перехід означає, що ви використовуєте специфікації як заміну тому, що не знаєте, що будувати. Зробіть крок назад, напишіть тридцятирядкову специфікацію, погодьтесь ітерувати.
Чесна рамка: spec-driven development — це дефолт для дев’яноста відсотків роботи у зрілій кодовій базі 2026. Решта десяти відсотків важлива, і сеньорний інженер — це той, хто розрізняє.
Кар’єрний кут: автор специфікацій як ремесло
Що змінюється особисто для вас, залежно від сходинки на драбині, грубо ділиться на три групи.
Джуни. Пастка очевидна і небезпечна: писати код, який міг би написати агент, замість того, щоб навчитися писати специфікацію, в якій агент потребував. Найшвидший спосіб так і не стати сеньором — пишатися обсягом коду, який ви виробляєте. Найшвидший спосіб почати ним ставати — пишатися точністю специфікацій, які ви пишете, включно з негативними випадками. Кожна написана вами специфікація — мисленнєвий артефакт. Кожен рядок агентського коду — ні.
Мідли. Зсув найсильніший тут. Ваше старе кредитне плече — писати код добре; ваше нове — писати специфікації добре. Кар’єрний ризик: якщо ви не зробите переходу, розрив до сеньора стане складніше закрити, бо те, за що зараз наймають сеньорів, лежить вище за течією, ніж код. Кар’єрна можливість: spec authoring — недорозвинений навичок по всій галузі; швидко в ньому прокачатися — одна з найдоходніших інвестицій, доступних просто зараз.
Сеньори і стаффи. Опис вашої роботи зсунувся, наздогнало це ваше звання чи ні. Ви — автор специфікацій, який іноді пише код, а не автор коду, який іноді пише специфікації. Найсеньорніші інженери, з якими я працюю, тепер проводять день, формуючи специфікації, що керують п’ятьма-десятьма агентськими сесіями паралельно. Кредитне плече складається, бо добре сформовані специфікації композиціюються за кількома агентами і фічами. Погано сформовані — протікають у всі одночасно.
Глибша думка
Специфікації — це те, що ви пишете; контекст — це те, що рантайм збирає з них. Обидва мають бути правильними. Зламайте одне — і система відмовляє способами, що виглядають як AI-баги, але насправді — інженерні. Зробіть обидва правильно — і кодова база більшу частину пише сама. Звучить хльосткувато, доки не побачите це у роботі, після чого звучить як найважливіший зсув в інженерній практиці з часів системи контролю версій.
Якщо хочете глибше, у курсах нижче — ті частини дисципліни, які я викладаю найчастіше: Claude Code Mastery: Agentic Coding for Engineers — щоденний workflow spec-driven development з реальним агентом, Building Agents with the Claude Agent SDK — побудова агентів, що споживають специфікації як first-class вхід, Prompt Engineering & AI Workflow Automation — фундамент prompt-рівня, з якого еволюціонують специфікації, і Building MCP Servers & AI Tool Integrations — як зробити специфікації переносимими між агентами та інструментами.
