Structured-Prompt-Driven Development (SPDD)

Як зробити зміни за допомогою LLM керованими, придатними до рев'ю та повторно використовуваними

Асистенти програмування на базі LLM уже продемонстрували значну цінність, але переважно для окремих розробників. Внутрішня IT-організація Thoughtworks використовує їх у командній роботі та розробила метод і workflow під назвою Structured Prompt-Driven Development (SPDD). У цій статті описано простий приклад такого workflow з деталями на GitHub. Цей workflow ставиться до prompt-ів як до першокласних артефактів: вони зберігаються разом із кодом у version control і використовуються для узгодження розробки з бізнес-потребами. Ми виявили, що для ефективної роботи розробникам потрібні три ключові навички: alignment, abstraction-first та iterative review.

28 квітня 2026

Автори: Wei Zhang та Jessie Jie Xia

Примітка щодо перекладу, ліцензування та політики

Це український переклад статті "Structured-Prompt-Driven Development (SPDD)" з martinfowler.com. Переклад підготовлено відповідно до політики перекладів Martin Fowler FAQ: переклади можна публікувати за умови посилання на оригінальну статтю. Діаграми та зображення взято з оригінальної статті; змін до зображень не вносилося. Деталі перевірки політики наведено в POLICY.md.

Зміст

• Що таке SPDD?
  • REASONS Canvas
  • Workflow SPDD
• Покращення billing engine за допомогою SPDD
  • Поточна система
  • Покращення
  • Крок 1: створити початкові вимоги
  • Крок 2: уточнити аналіз
  • Крок 3: згенерувати контекст аналізу
  • Крок 4: згенерувати структурований prompt
  • Крок 5: згенерувати код
  • Крок 6: згенерувати unit-тести
  • Що дав цей приклад
• Три ключові навички
• Де доречний SPDD
• Завершення
• Подяки
• Відповіді на деякі питання

Коли команда починає використовувати AI coding assistants, перші виграші проявляються на рівні окремого розробника: одна людина може створювати, змінювати й рефакторити код значно швидше, ніж раніше. Але швидкість delivery рідко обмежується набором тексту. Якщо подивитися на повний delivery lifecycle, від вимог до release, з'являються нові тертя:

• Неоднозначні вимоги швидко перетворюються на код, і разом із ними масштабуються непорозуміння.
• Review мають обробляти більше змін, і неузгодженість стає легше внести.
• Виникає більше проблем інтеграції та тестування, бо "generated" не означає "aligned".
• Production-ризики важче осмислювати, коли обсяг змін зростає.

Отже, локальна швидкість справді зростає. Але це не автоматично перетворюється на system-level throughput. Це схоже на купівлю Ferrari й поїздку розмитою дорогою: двигун потужний, але час прибуття визначають стан дороги й трафік. З нашого досвіду справжнє питання не в тому, "як генерувати більше коду?". Питання в тому, як зробити AI-generated changes керованими, придатними до рев'ю та повторно використовуваними, щоб команди ставали швидшими й безпечнішими.

Це привело наші внутрішні IT-команди Thoughtworks (Global IT Services) до методу й workflow, який ми тепер називаємо Structured Prompt-Driven Development (SPDD). SPDD має перетворити AI assistance з особистої ефективності на організаційну capability, що масштабується без втрати якості.

Prompts as First-Class Delivery Artifacts

Що таке SPDD?

Structured Prompt-Driven Development (SPDD) - це інженерний метод, який ставиться до prompt-ів як до першокласних delivery artifacts.

Замість покладатися на ad hoc chats, SPDD перетворює prompt-и на assets, які можна version control-ити, рев'юїти, повторно використовувати й покращувати з часом. Команди використовують structured prompts, щоб зафіксувати вимоги, доменну мову, design intent, constraints і task breakdown. Потім LLM генерує код у визначених межах, тому результат стає передбачуванішим і легшим для валідації.

Метод має два основні компоненти.

REASONS Canvas

REASONS Canvas - це структура для генерації prompt-ів. Вона змушує чітко сформулювати requirements, domain model, solution approach, system structure, task decomposition, reusable norms і safeguards. Завдяки цьому LLM керується наміром, а не здогадками.

REASONS Canvas - це структура із семи частин, яка веде prompt від intent -> design -> execution -> governance.

Абстрактні частини (intent & design)

• R - Requirements: яку проблему ми розв'язуємо і що таке DoD?
• E - Entities: доменні сутності та зв'язки.
• A - Approach: стратегія, за якою ми виконаємо вимоги.
• S - Structure: де зміна вписується в систему; components and dependencies.

Конкретні частини (execution)

• O - Operations: розбити абстрактну стратегію на конкретні, тестовані implementation steps.

Частини спільних стандартів (governance)

• N - Norms: наскрізні engineering norms (naming, observability, defensive coding тощо).
• S - Safeguards: межі, які не можна порушувати (invariants, performance limits, security rules тощо).

Canvas узгоджує intent і boundaries до генерації коду, зміщуючи невизначеність ліворуч. Оскільки structured prompt містить повну specification, reviewers міркують про один артефакт замість розрізнених chat logs і часткових diffs. Завдяки однаковій структурі кожен prompt стає керованим в однаковий спосіб. А коли domain knowledge і design decisions накопичуються в кожному prompt-і, вони посилюють індивідуальну експертизу між ітераціями та зменшують варіативність у команді.

Workflow SPDD

Workflow переносить prompt-и в ту саму дисципліну, що й код: commit history, review і quality gates. Він також впроваджує просте, але потужне правило:

Коли реальність розходиться з очікуванням, спочатку виправ prompt, а потім онови код.

З часом це змінює спосіб роботи команд. Review відходять від "знайди баг" до "перевір intent". Rework стає контрольованішим. А успішні patterns природно накопичуються в reusable prompt library, яка підтримує AI-First Software Delivery (AIFSD).

Якщо ви знаєте про Spec-Driven Development, то впізнаєте ту саму вихідну точку: спочатку чітко напиши spec, потім дозволь model реалізувати її. SPDD дивиться під іншим кутом. Він трактує structured prompts як governed, reusable, versioned team assets (REASONS + workflow), які еволюціонують разом із кодом - підхід, який Birgitta Böckeler класифікує як spec-anchored.

Що SPDD додає до spec-driven development

SDD і SPDD мають одну вихідну точку: згенерувати spec перед генерацією коду. SPDD додає метод того, як ця spec створюється, рев'юїться та синхронізується з кодом.

• Prompt є підтримуваним артефактом. Його не генерують один раз і не викидають. Він проходить визначений workflow і залишається записом того, що було задумано.
• Від requirements до engineering spec. REASONS Canvas виходить за межі опису того, що система має робити. Він фіксує обраний approach, system structure, engineering norms і safeguards, даючи LLM implementation boundary, а не лише goal.
• Sync, not handoff. Prompt і code залишаються синхронізованими. Зміни з будь-якого боку відображаються назад, тому intent і implementation не розходяться.
• Repeatable team control. Мета не в "детальніших specs", а в послідовному способі, яким команди керують AI output і переносять ухвалені рішення через ітерації. Аналіз trade-offs за цими рішеннями живе в analysis phase; Canvas фіксує результат.

Мета workflow SPDD - перетворити business input -> abstraction -> execution -> validation -> release на "closed loop" [1] і переконатися, що prompt assets і code еволюціонують разом, а не окремо.

[1] В односторонньому pipeline вимоги породжують код, і процес завершується; будь-яке пізніше коригування відбувається лише в коді, а первинний intent застаріває. В SPDD loop закривається у двох масштабах. Усередині ітерації feedback повертається назад: logic corrections оновлюють prompt перед кодом; refactoring синхронізується з коду назад у prompt, щоб жодна сторона не розходилася мовчки. Між ітераціями накопичені prompt assets - domain models, design decisions, norms тощо - стають стартовим контекстом для наступного enhancement, тому кожен цикл будується на governed baseline, а не починається з нуля.

SPDD workflow

Мета цього workflow - прив'язати collaboration до prompt-ів, щоб developers і product owners могли уникати повторних циклів alignment. Prompt задає явну boundary для code generation, зменшуючи випадковість LLM non-determinism і полегшуючи governance. Ставлячись до structured prompts як до першокласних артефактів у version control, ми перетворюємо успішні practices на reusable assets, підвищуючи consistency і зменшуючи reinventing.

На практиці ці кроки виконуються командами, які надає openspdd, command-line tool, що реалізує SPDD workflow. Таблиця нижче підсумовує кожну команду.

Command	Type	Purpose
/spdd-story	Optional	Розбиває велику requirement на незалежні deliverable user stories за принципом INVEST.
/spdd-analysis	Core	Витягує domain keywords з requirements, сканує релевантний code і створює strategic analysis, що охоплює domain concepts, risks і design direction.
/spdd-reasons-canvas	Core	Генерує повний REASONS Canvas - executable blueprint від high-level rationale до method-level operations.
/spdd-generate	Core	Читає Canvas і генерує code task by task, суворо дотримуючись operations, norms і safeguards, визначених у prompt-і.
/spdd-api-test	Optional	Генерує cURL-based API test script зі structured test cases для normal, boundary та error scenarios.
/spdd-prompt-update	Core	Інкрементально оновлює Canvas, коли змінюються requirements (requirements -> prompt -> code).
/spdd-sync	Core	Синхронізує code-side changes (refactoring, fixes) назад у Canvas, щоб prompt залишався точним записом поточного коду (code -> prompt).

Покращення billing engine за допомогою SPDD

Складний workflow важко зрозуміти абстрактно, тому ми підготували приклад workflow для покращення наявної software system. Ця система та її enhancement вимушено невеликі, щоб лишатися зрозумілими в межах tutorial article. Водночас enhancement example є повним end-to-end прикладом: від створення початкових requirements і аналізу business requirements до генерації та review structured prompt, створення й перевірки коду, фінального cleanup і testing.

Ви можете пройти цей приклад у власному середовищі, встановивши openspdd.

Поточна система

Поточна система - це простий billing engine, який рахує bills за використання large-language model. Він приймає record, що фіксує кількість tokens, використаних у session, і обчислює bill.

Повний codebase початкової версії доступний на GitHub. Repository містить initial requirements story і всі SPDD artifacts, використані для її генерації. Заради стислості ми не описуємо цю початкову генерацію, але вона виконує по суті ті самі кроки, що й enhancement. Ми зосереджуємося на enhancement, бо більшість роботи над системою - це саме enhancements.

Покращення

Під впливом нових бізнес-вимог і прямого user feedback ми покращуємо billing engine, переводячи його зі static pricing model на складнішу, гнучкішу інфраструктуру. Це оновлення має підтримати різні subscription strategies і variable, model-specific pricing через такі ключові зміни:

• API enhancement: оновити наявний endpoint POST /api/usage, щоб він приймав новий обов'язковий параметр modelId (наприклад, "fast-model", "reasoning-model").
• Model-aware pricing: перейти від єдиного global rate до dynamic pricing, де costs залежать від конкретної AI model, яку викликали.
• Multi-plan billing logic: запровадити різну billing behavior залежно від subscription tier клієнта:
  • Standard plan (optimized): зберігає global monthly quota, але overage usage тепер обчислюється за model-specific rates.
  • Premium plan (new): працює без quota limit. Він вводить split billing, де prompt tokens і completion tokens оплачуються окремо за різними rates залежно від model.
• Architectural scalability: реалізувати extensible design pattern (наприклад, Strategy або Factory), щоб чисто ізолювати calculation formulas для різних plans і забезпечити легке додавання майбутніх pricing models.

Оскільки ця нова секція охоплює і business requirements, і technical details, її зазвичай заповнюють спільно під час pairing session між PO (або BA) та developer.

Крок 1: створити початкові вимоги

Щоб швидко запустити процес, ми можемо використати команду /spdd-story [2], яка генерує user story безпосередньо з enhancement. Загалом user stories надає PO або BA. Однак у нашому workflow ми можемо перетворювати stories будь-якої форми на consistent format і dimension. Якщо є shared alignment щодо final acceptance criteria, цей крок може виконати PO, BA або developer - залежно від гнучкого розподілу роботи в команді.

[2] Оскільки це optional command, якщо її немає у вашому local environment, її можна згенерувати командою openspdd generate spdd-story.

Instruction:

Як працює spdd-story

Ця команда розбиває велику requirement на незалежні, deliverable user stories за принципом INVEST (1-5 днів роботи кожна). Кожна story містить acceptance criteria, написані business language і готові бути input для /spdd-analysis.

Її мета - зробити великі requirements керованими й забезпечити standardized, predictable format для наступних кроків.

/spdd-story @idea-of-the-enhancement.md

AI проаналізував enhancement description і розділив його на дві user stories:

• Story 1-1 (Standard Plan & model-aware pricing)
• Story 1-2 (Premium Plan split-rate billing)

Auto-generated stories достатньо детальні, щоб бути baseline для формального project. Для цього walkthrough ми об'єднуємо їх в одну simplified story, щоб приклад залишався self-contained.

Instruction:

Consolidate the following two user stories into a single, simplified story:
@[User-story-1-1-initial]Multi-Plan-Billing-Foundation-&-Standard-Plan-Model-Aware-Pricing.md
@[User-story-1-2-initial]Premium-Plan-Split-Rate-Billing.md

Requirements:
1. Merge both plans (Standard and Premium) into one coherent story.
2. Keep only the sections: Background, Business Value, Scope In, Scope Out, and Acceptance Criteria.
3. Strip implementation-level detail — focus on what the system should do, not how.
4. Acceptance Criteria must use Given/When/Then format with concrete numeric examples.
5. Keep the result concise — no more than one page.
6. Only keep three high-level ACs.

Інструкції такого типу рідко дають ідентичний текст у кожному запуску: models і sampling вносять невеликі відмінності. Тому ми все одно очікуємо review і tweaking output перед тим, як вважати його final. Нижче наведено combined story, яку ми доопрацювали для цього walkthrough: навмисно simplified consolidation двох початкових stories.

Combined user story (simplified)

Background

У міру масштабування нашої LLM API platform єдиної pricing model уже недостатньо. Нам потрібно refactor наявний billing engine, щоб підтримати різні subscription strategies і variable pricing на основі AI model, яку викликали, закладаючи foundation для майбутніх complex billing plans.

Business Value

1. Flexible Monetization: підтримати різні billing strategies (Standard, Premium), щоб охопити різні market segments.
2. Model-Aware Pricing: стягувати різні rates залежно від конкретної AI model.
3. Architecture Scalability: реалізувати extensible design (наприклад, Strategy Pattern), щоб ізолювати calculation logic і легко додавати future pricing models.

Scope In

• Enhance existing POST /api/usage endpoint.
• New Request Field: додати modelId (required, string, наприклад, "fast-model", "reasoning-model").
• Реалізувати routing mechanism (Strategy/Factory Pattern) для обробки різних calculation formulas.
• Реалізувати два initial Plan Types:
  1. Standard Plan (Legacy Refactor): має monthly global quota. Overage rates тепер залежать від modelId.
  2. Premium Plan (New): без quota. Prompt і Completion tokens оплачуються окремо, а rates залежать від modelId.

Scope Out

• Complex tiered/volume-based discount logic (відкладено до Phase 2).
• Subscription plan creation and assignment CRUD.
• Invoice generation.

Acceptance Criteria (ACs)

1. Base Validations (Regression & New)
   Given invalid request (наприклад, missing modelId, negative tokens)
   When backend validates request
   Then return HTTP 400 with appropriate error messages.

2. Standard Plan with Model-Aware Overage
   Given a "Standard" customer with a 100,000 monthly quota, 90,000 used so far. Overage for "fast-model" is $0.01/1K.
   When submitting 30,000 tokens for "fast-model"
   Then bill shows: 10,000 from quota, 20,000 overage, $0.20 charge.

3. Premium Plan with Split Rates
   Given a "Premium" customer. For "reasoning-model", Prompt is $0.03/1K, Completion is $0.06/1K.
   When submitting 10,000 prompt and 20,000 completion tokens for "reasoning-model"
   Then bill shows: 0 from quota, $0.30 prompt charge, $1.20 completion charge, total $1.50.

Крок 2: уточнити аналіз

Перед тим як переходити до implementation, developer переглядає user story, щоб сформувати shared understanding того, що вона означає на практиці. Якщо є очевидні business-level issues, саме тут треба узгодитися з BA або PO. У цьому випадку story достатньо зрозуміла, тому ми одразу розкладаємо її за трьома dimensions: core logic, scope boundaries і definition of done.

Core logic

Одне нове required field в API: modelId. Customer тепер повідомляє, яку AI model використав; це ключ, що відкриває правильну price.

• Standard Plan: Customer має monthly token quota. Usage within quota є free. Overage оплачується за model-specific rate (наприклад, fast-model $0.01/1K проти reasoning-model $0.03/1K). Existing quota logic зберігається; змінюється лише rate lookup.
• Premium Plan: Без quota. Кожен token bill-иться з першого. Prompt tokens і completion tokens оплачуються окремо, кожен за model-specific rate. Bill = prompt charge + completion charge. Це повністю новий plan.
• Routing: System визначає customer's plan і dispatches до відповідної billing formula. Design має бути easy to extend: Enterprise plans (Story 2) наступні.

Scope boundaries

Ми лише обчислюємо current bill. Ми НЕ будуємо customer CRUD, НЕ запитуємо historical bills, НЕ керуємо subscriptions і НЕ додаємо/видаляємо models.

Definition of done

Наступні scenarios повторюють acceptance criteria story з implementation detail, який команда має перевірити. Четвертий пункт (Response format) не є новим business AC; він фіксує non-functional contract, який developer додає, щоб criteria можна було testable end-to-end.

• Validation: Missing modelId -> HTTP 400. Unknown customer -> HTTP 404. Negative tokens -> HTTP 400. Усі existing validations залишаються intact.
• Standard Plan billing: Customer із quota 100K і вже використаними 90K відправляє 30K tokens для fast-model ($0.01/1K). Expected result: 10K covered by quota, 20K overage, charge $0.20. Той самий request з reasoning-model ($0.03/1K) дає $0.60 - та сама quota logic, інший rate.
• Premium Plan billing: Customer відправляє 10K prompt tokens + 20K completion tokens для reasoning-model (prompt $0.03/1K, completion $0.06/1K). Expected result: $0.30 + $1.20 = $1.50. No quota, no overage - prompt і completion bill-яться окремо.
• Response format: HTTP 201 повертає bill ID, customer ID, token counts, timestamp, modelId і plan-appropriate charge breakdown.

Якщо всі ці scenarios проходять, ми подолали цю story.

Крок 3: згенерувати контекст аналізу

Коли requirements і scope уточнено, ми використовуємо команду /spdd-analysis. Передаючи їй business requirements, ми доручаємо AI згенерувати comprehensive analysis context.

Як працює spdd-analysis

Ця команда витягує domain keywords із business requirements (наприклад, "billing", "quota", "plan") і використовує їх, щоб сканувати лише релевантні частини codebase, а не весь codebase. Вона визначає existing concepts, new concepts, key business rules і technical risks.

Output - context-rich document, що охоплює domain concept recognition, strategic direction і risk analysis. Він слугує input для наступного кроку: generation of the REASONS Canvas.

Instruction:

/spdd-analysis
@[User-story-1]Multi-Plan-Billing-Foundation-&-Model-Aware-Pricing.md

Generated artifact: initial analysis context document.

Ця команда створює strategic-level analysis, grounded in actual codebase exploration. Output повністю фокусується на "what" і "why", свідомо уникаючи granular implementation details на цьому етапі. Зазвичай він охоплює:

• Domain concepts: existing vs. new, relationships, business rules
• Strategic approach: solution direction, design decisions, trade-offs
• Risks & gaps: ambiguities, edge cases, technical risks, acceptance-criteria coverage

Review and refine the analysis context

З нашим власним розумінням business requirements ми переглядаємо generated analysis document, зосереджуючись на areas, підсвічених у навичці alignment. Це review має дві цілі: підтвердити, що наше розуміння узгоджується з AI interpretation, і знайти edge cases або boundary scenarios, які AI міг виявити, а ми не врахували.

У цьому конкретному випадку review зосередився на кількох critical areas:

• Чи Strategy Pattern було розглянуто належним чином.
• Дотримання OOP principles, установлених у наявній system, зокрема ISP і SRP.
• Валідність запропонованої strategy для додавання нових fields.
• Виявлення edge cases, яких раніше не передбачили.
• Виявлення potential technical risks.

Після завершення review AI analysis загалом узгоджувався з нашим architectural intent; у деяких areas його considerations були навіть повнішими за наші.

Edge cases and risks from the analysis document

Щоб бути прозорими: на цьому етапі ми маємо лише high-level conceptual alignment. Хоча ми можемо швидко уявити implementation для areas, де вже маємо досвід, ми не можемо повністю розкласти всі granular technical details для незнайомих parts прямо зараз.

Але це нормально. Загальний direction узгоджено. Ми можемо перейти до наступного кроку: подивитися, як AI "simulates" concrete implementation details у межах нашого framework і context. Коли матимемо ці tangible details, зможемо виявити глибші hidden issues і прийняти informed trade-offs based on actual scenario: залишити approaches, де benefits outweigh drawbacks, і відкинути решту.

Decision: accept the analysis as-is and proceed.

Крок 4: згенерувати структурований prompt

Як працює spdd-reasons-canvas

Ця команда читає business context (output /spdd-analysis або direct requirements description) і поєднує його з current state of the codebase. Потім вона генерує design specification за всіма сімома REASONS dimensions - від "why are we doing this" до "what must we not do".

Output - executable blueprint. Section Operations є точною аж до method signatures, parameter types і execution steps.

Instruction:

/spdd-reasons-canvas
@GGQPA-001-202603191100-[Analysis]-multi-plan-billing-model-aware-pricing.md

Generated artifact: initial structured prompt.

На цьому етапі ми вже пройшли high-level strategy в analysis phase, тому під час review structured prompt не стартуємо з нуля. Натомість перевіряємо, як AI переклав наше shared understanding у REASONS Canvas structure: від strategy до abstraction і concrete details.

Думайте про це як про progression: analysis phase дав strategic clarity; тепер ми перевіряємо, чи ця clarity faithfully carried through в architectural abstractions і implementation specifics. Це intent alignment на глибшому рівні: перед генерацією будь-якого коду ми переконуємося, що AI effectively "simulated" entire solution у нашому defined framework. Ми можемо review з global perspective, а не губитися в details із самого початку.

Що робити, якщо structured prompt потребує змін?

Ми ніколи не редагуємо structured prompt file вручну. Натомість підтримуємо SPDD iterative dialogue:

1. Identify the gap: помітити missing elements (наприклад, missing OO principles або misunderstood business rule).
2. Input new prompt: надати missing intent напряму AI через conversational interface.
3. AI updates the file: AI обробляє new intent і уточнює лише ті sections structured prompt, які потребують змін.

Далі ми побачимо конкретний step-by-step example саме такого "prompt-first update" workflow, коли змінюємо prompt, щоб виправити business logic mismatch до змін у коді.

Сфокусуйте review на areas, підсвічених у навичці abstraction-first. У цьому випадку foundational context уже embedded у codebase і previous structured prompt. Тому під час генерації structured prompt для цієї ітерації AI природно враховує ці architectural guidelines і OO principles. Як наслідок, хоч generated content дуже складний, major issues надзвичайно мало. Ми можемо спершу перейти до code generation із цим structured prompt, а вже потім провести deeper review, щоб виявити potential code-level anomalies.

Наразі ми досягли strong consensus на intent level, уточнивши і core problem, і resolution path. Невеликі omissions у details можливі, але це не проблема: коли overall scope узгоджено з AI, local optimizations залишаються highly controllable. Тепер ми переходимо до code generation phase.

Крок 5: згенерувати код

Цей крок складніший, бо ми генеруємо product code, tests, а наші reviews можуть мати два alternative outcomes.

Generate product code

Коли structured prompt зафіксовано, використайте його для генерації product code.

Як працює spdd-generate

Ця команда читає REASONS Canvas і генерує code task by task у порядку, визначеному в Operations. Вона суворо дотримується coding standards у Norms і constraints у Safeguards: no improvisation, no features beyond what the spec defines.

Core principle: prompt captures the intent, and code is the implementation of that intent. Generated code must correspond one-to-one with this specification.

Instruction:

/spdd-generate
@GGQPA-001-202603191105-[Feat]-multi-plan-billing-model-aware-pricing.md

Generated artifact: code generated based on the structured prompt.

Завдяки multiple rounds of logical deduction, які ми виконали раніше за допомогою structured prompts, ми підходимо до code review із clear focus і set of priorities:

1. Architecture: чи code строго дотримується expected 3-tier architecture?
2. Business logic: чи Service layer implementation ідеально узгоджується з initial intent?
3. Scope of change: чи modifications строго confined to boundaries, визначених structured prompt, без unrelated changes або scope creep?

У цьому конкретному випадку завдяки highly precise context generated code загалом відповідав очікуванням, за винятком кількох potential "magic numbers". Ми optimize їх після завершення functional verification.

Головний takeaway: не переживайте через помилки й не напружуйтеся, що не вловили кожну detail ідеально з першої спроби. Поки ми iterating і рухаємося через SPDD workflow, є достатньо opportunities to course-correct. Minor code smells зараз прийнятні: спершу verify core functionality, потім повертаємося до optimization.

Feature verification

Під час feature validation SPDD workflow надає команду /spdd-api-test для генерації functional testing scripts. [3]

[3] Оскільки це optional command, якщо її немає у вашому local environment, її можна згенерувати командою openspdd generate spdd-api-test.

Як працює spdd-api-test

Ця команда витягує API endpoint information з code implementation або acceptance criteria і генерує cURL-based test script. Script містить structured test-case table, що охоплює normal scenarios, boundary conditions і error scenarios. Під час виконання він виводить expected-vs-actual comparison results.

Instruction:

/spdd-api-test

Generated artifact: API test script.

Керуючись rules, визначеними в command, AI генерує script, який формує required test scenarios через curl commands. Ми можемо review ці AI-generated scenarios в section "TEST CASE OVERVIEW" script.

Generated API Test Script

Execution: після генерації script запустіть його:

sh scripts/test-api.sh

Result: усі functional tests успішно passed.

API Test Results

Code review & final adjustments

Завдяки rigorous intent alignment у перших кількох steps основну важку роботу вже зроблено. На цьому етапі remaining issues зазвичай є minor logic discrepancies або surface-level code smells.

Щоб зберегти precision в engineering practices, ми поділяємо ці final adjustments на два distinct types залежно від того, чи змінюють вони observable behavior system, і обробляємо їх різними strategies у SPDD workflow:

Two responses to code review changes

Logic corrections (behavior changes)

Strategy: update the prompt first, then generate code. Для issues, пов'язаних із business rules або logic mismatches, які inherently change observable behavior of the software, завжди оновлюйте structured prompt, щоб зафіксувати correct intent перед змінами в code. Це update або bug fix, а не refactoring.

Наприклад, коли ми persist modelId у bill, наразі дозволяємо цьому field бути nullable. Причина - need to maintain backward compatibility with historical data, що робить такий workaround reasonable architectural decision.

Prompt needs update

Однак є alternative. Якщо business stakeholders можуть підтвердити, яким має бути значення modelId до цієї зміни, ми можемо unify system behavior і усунути potential technical debt. Припустімо, що після підтвердження з business modelId для всіх historical bills має бути fast-model.

З таким clear intent ми взаємодіємо з AI:

Як працює spdd-prompt-update

Ця команда інкрементально оновлює existing Canvas. Вона змінює лише sections, яких торкається change, і зберігає все інше. На основі type of change - new requirement, architectural adjustment або constraint change - вона автоматично визначає, які REASONS dimensions потребують update.

Це відрізняється від /spdd-sync: sync flows from code to spec, коли code змінився; prompt-update flows from requirements to spec, коли requirements змінилися.

Instruction:

/spdd-prompt-update @GGQPA-001-202603191105-[Feat]-multi-plan-billing-model-aware-pricing.md

model_id is a required field, and its default value is fast-model.
Based on this decision, update the corresponding parts of the structured prompt.

AI оновлює structured prompt на основі цієї instruction.

Updated artifact: updated structured prompt.

Після підтвердження використайте команду /spdd-generate, щоб оновити відповідний code на основі щойно updated structured prompt:

/spdd-generate
@GGQPA-001-202603191105-[Feat]-multi-plan-billing-model-aware-pricing.md

AI, керований rules у /spdd-generate, comprehends required changes і виконує targeted updates виключно в affected codebase.

Updated artifact: updated code.

Важливо зазначити, що ми не regenerate entire codebase. Ми продовжуємо використовувати existing structured prompt, а AI handles targeted diffs:

1. Identify the mismatch: помітити, що behavior modelId під час persistence не узгоджується з new business requirement (він має бути mandatory with a default).
2. Target the prompt snippet: скопіювати specific section зі structured prompt, яка визначає outdated logic.
3. Update the prompt: вставити extracted snippet у chat разом із revised business rule, instructing AI to update the structured prompt first.
4. Generate targeted code updates: коли prompt reflects the new truth, запустити /spdd-generate на updated file. AI автоматично виконає targeted diffs лише в affected codebase, а не regenerate everything from scratch.

Refactoring (clean code & style)

"A change made to the internal structure of software to make it easier to understand and cheaper to modify without changing its observable behavior."

-- Martin Fowler

Strategy: refactor the code first, then sync back to the prompt. Для structural або stylistic issues, які не змінюють observable behavior, instruct AI to refactor the code directly, а потім використайте sync command, щоб оновити prompt documentation.

Наприклад, AI-generated class BillingServiceImpl містить кілька hardcoded magic numbers, які потрібно винести в meaningful constants.

private int calculateRemainingQuota(String customerId, PricingPlan plan) {
        if (plan.getMonthlyQuota() == null || plan.getMonthlyQuota() == 0) {
            return 0;
        }

        LocalDate currentDate = LocalDate.now(ZoneOffset.UTC);
        LocalDateTime monthStart = currentDate.withDayOfMonth(1).atStartOfDay();
        LocalDateTime monthEnd = currentDate.plusMonths(1).withDayOfMonth(1).atStartOfDay();

        Integer currentMonthUsage = billRepository.sumIncludedTokensUsedForMonth(customerId, monthStart, monthEnd);
        return plan.getMonthlyQuota() - currentMonthUsage;
    }

Instruction 1:

@BillingServiceImpl.java In the calculateRemainingQuota method,
there are some magic numbers that need to be processed as constants

AI виконує code refactoring на основі цієї instruction (пам'ятайте golden rule: always refactor in small, incremental steps). Якщо output відповідає очікуванням, ми використовуємо команду /spdd-sync, щоб synchronize ці newly updated code details назад у відповідні locations structured prompt.

Instruction 2:

Як працює spdd-sync

Ця команда порівнює current code із Canvas specification, а потім synchronizes code-side changes (refactoring, bug fixes, new components) назад у Canvas.

Мета - тримати Canvas accurate design document для current code, а не outdated historical record.

/spdd-sync

AI summarizes changes на основі rules, defined in /spdd-sync. Потім, дотримуючись structural requirements REASONS Canvas, він записує detailed code description updates назад у corresponding sections structured prompt.

Після виконання обох commands ми можемо побачити всі prompt і code changes тут.

Для будь-яких deeper або hidden code smells просто повторіть ці steps. Golden rule - always keep the structured prompt synchronized with your latest codebase.

Regression test

Коли всі optimizations завершено, restart service і run API test script ще раз, щоб переконатися, що core functionality не зламалася під час cleanup.

Result: all passed.

Regression Test Results

Крок 6: згенерувати unit-тести

Functional testing alone недостатній для robust validation; він переважно є auxiliary check і не враховується в code coverage metrics. Final sign-off на core logic потребує comprehensive unit tests. Наразі SPDD workflow не має finalized dedicated testing commands (вони з'являться в future iterations). Як interim solution, ми використовуємо template-driven approach для генерації structured prompts for unit testing.

Generate the initial test prompt

Ми починаємо з поєднання implementation details із standardized testing template, щоб згенерувати baseline test prompt.

Instruction:

Based on the implementation details prompt
@GGQPA-001-202603191105-[Feat]-multi-plan-billing-model-aware-pricing.md,
combined with the template @TEST-SCENARIOS-TEMPLATE.md, please
generate a test prompt file.

Deduplicate and refine scenarios

Після генерації initial structured test prompt частина proposed test scenarios дублювала те, що вже було. Щоб виправити це, ми продовжили dialogue, instructing AI to cross-reference generated prompt with existing test suite, identify genuinely new scenarios і remove redundancies.

Instruction:

@GGQPA-001-202603191105-[Test]-multi-plan-billing-model-aware-pricing.md
There are tests that are duplicated with existing ones, compare the
relevant tests that exist, and then only add tests for new scenarios

Updated artifact: test structured prompt.

Generate the unit test code

Коли refined test scenarios reviewed and confirmed, використайте finalized test prompt, щоб drive actual code generation.

Instruction:

Based on the generated test prompt
@GGQPA-001-202603191105-[Test]-multi-plan-billing-model-aware-pricing.md,
please generate the corresponding unit test code.

Result: all tests passed. Commit for tests.

Що дав цей приклад

Це завершення complete SPDD workflow. Через цей standardized process ми успішно отримали такі key outcomes:

1. Business logic implementation з exceptionally high intent alignment (~99%).
2. Complete engineering transparency, включно з clear understanding implementation path, technical decisions і accepted trade-offs.
3. Structured prompt asset, tightly synchronized with the current codebase, що закладає solid foundation for future iterations.
4. Compounding human expertise, що підтримує continuous accumulation developer experience і mental models під час collaborative iteration with AI.

View the complete code diff for this enhancement on GitHub.

Ми також підготували bonus enhancement feature - Enterprise Plan Volume-Based Tiered Billing. Якщо вам цікава hands-on practice, ми дуже радимо пройти її за SPDD workflow, описаним вище.

Три ключові навички

SPDD суттєво змінює те, як developers будують software. У нашій роботі ми визначили три core skills, потрібні для effective work. Ці skills відображають, куди зміщується цінність developers в AI-assisted world.

Abstraction first

design before you generate

Перед генерацією будь-якого code потрібно чітко розуміти, які objects існують, як вони collaborate і де boundaries. Без цього AI часто стрімко біжить по implementation details, поки structure розвалюється. Нечіткі responsibilities, duplicated logic, inconsistent interfaces - і cost з'являється пізніше в review та rework.

Alignment

lock intent before you write code

Перед implementation потрібно зробити "what we will do / what we won't do" explicit і upfront узгодити standards та hard constraints. Інакше ви отримуєте fast output і slow rework.

Iterative Review

turn output into a controlled loop

Вам потрібно, щоб AI assistance поводився як engineering process, а не one-shot draft. Без disciplined review-and-iterate loop команди або змушують model латати речі, доки solution дрейфує, або repeatedly restart і втрачають control of cost and time.

Де доречний SPDD

Fitness assessment

SPDD - це engineering investment. Таблиця нижче оцінює, наскільки він окупається в різних scenarios: від highly recommended (5 stars) до not suitable (1 star).

Rating	Scenario	Notes
★★★★★	Scaled, standardized delivery	High-repeat business logic, яка потребує long-term maintainability (наприклад, побудова багатьох similar APIs, automating core business workflows).
★★★★★	High compliance and hard constraints	Environments, де потрібно дотримуватися regulations, security standards або strict architectural rules (наприклад, financial core systems, multi-channel / multi-client deployments).
★★★★☆	Team collaboration and auditability	Multi-person delivery, де changes мають бути fully traceable і reviewable end-to-end.
★★★★☆	Cross-cutting consistency work	Complex refactors, де logic має залишатися tightly synchronized across multiple microservices або different languages.
★★☆☆☆	Firefighting hotfixes	"Stop the bleeding" production fixes, де speed важливіша за architectural discipline.
★★☆☆☆	Exploratory spikes	Коли goal - швидко validate idea, а не ship production-quality software, SPDD governance overhead не окупиться.
★★☆☆☆	One-off scripts	Disposable data cleanup або temporary scripts, де upfront cost SPDD завеликий щодо value.
★☆☆☆☆	Context black holes	Коли domain poorly defined і business rules unclear, ви не можете задати meaningful boundaries для model.
★☆☆☆☆	Pure creative / visual work	Tasks, driven by taste and aesthetics rather than logic (наприклад, UI visual exploration, marketing copy).

Trade-offs to consider

Далі: подолати "expert-only" barrier

З today's trade-offs SPDD може виглядати як method, reserved for senior architects, бо ставить високу планку abstraction and modelling. Це не наша кінцева мета.

Ми працюємо над lowering that barrier. Щоб address scaling bottleneck, ми досліджуємо способи reuse existing SPDD assets і зробити complex business rules та design constraints more machine-readable and "intelligent", щоб вони застосовувалися consistently без покладання на individual intuition.

Наш direction clear: SPDD має менше залежати від personal craftsmanship і більше - від mature, organization-level asset system. Незалежно від того, seasoned expert ви чи тільки починаєте, ви маєте бути здатні deliver high-quality, standardized outcomes із набагато меншою потребою в "expert time" upfront.

More approaches to make SPDD easier to adopt are on the way.

Return on investment

Benefit	Impact	Speed	What you get
Determinism	High	Immediate	Encode logic in a precise spec, що суттєво зменшує hallucination і "creative" interpretation.
Traceability	High	Immediate	Кожну meaningful change можна trace back до structured prompt, closing the audit loop.
Faster reviews	High	Short-term	Code "arrives" closer to team standards, тому reviews фокусуються на logic and design, а не formatting and cleanup.
Explainability	Medium-High	Gradual	Intent і behavior visible at natural-language level, що зменшує cognitive load для understanding and maintenance.
Safer evolution	High	Long-term	Well-defined boundaries і stepwise implementation роблять targeted changes lower-risk і easier to iterate.

Upfront investment

Area	Barrier	Nature	What it takes
Mindset shift	High	Ongoing training	Teams мають перейти до "design first", а не "code first".
Senior expertise up front	Medium-High	Per-feature	Engineers, здатні translate business rules into clean abstractions and design constraints.
Automation tooling	Medium	Infrastructure setup	Without automation SPDD reaches a throughput ceiling and struggles to keep prompts consistent. openspdd запускає workflow цієї статті - від analysis і structured REASONS prompts до code й optional test support - як repeatable CLI steps, щоб artifacts залишалися versioned and reviewable, а не trapped in chat. Larger organizations may still layer a knowledge platform on top to manage and reuse assets at scale.

Завершення

Використовуючи REASONS Canvas, clarifying intent, establishing the right abstractions, breaking work into concrete tasks і locking in boundaries, ми даємо AI well-defined space to operate. У цьому space SPDD може не бути shortest path to "generate code quickly", але це один із найнадійніших способів ship the right change with confidence.

Також чесно сказати, що SPDD найкраще проявляється в logic-heavy domains. В areas, driven by aesthetic judgment, наприклад frontend styling, ми ще шукаємо engineering patterns, які можуть бути такими ж stable, як purely logical construction.

Framework у цій статті - це лише "moves". Справжня advantage приходить від sharpening meta-skills behind it: abstraction and modelling, systematic analysis і deep understanding of the business as a whole. Саме ці human strengths зрештою визначають, скільки value ми можемо отримати від AI.

В AI era software development не є contest of model IQ. Це contest of engineer cognitive bandwidth: наскільки ясно ми можемо think, frame problems і make decisions.

Завершимо цитатою, яка передає дух SPDD:

"In science, if you know what you are doing, you shouldn't be doing it. In engineering, if you don't know what you are doing, you shouldn't be doing it."

-- Richard W. Hamming

Подяки

Ми хочемо щиро подякувати Martin Fowler. Попри насичений графік, він глибоко інвестувався в цю статтю: від sharpen narrative structure і clarification of key concepts до elevating visual storytelling за допомогою improved and new diagrams. Його keen eye for detail і commitment to precision profoundly shaped the final result.

Ми також глибоко вдячні Eric (Ke) Zhou, Wei Sun, Sara Michelazzo, Rebecca Parsons, Matteo Vaccari, May (Ping) Xu, Zhi Wang, Feng Chen and Da Cheng за thoughtful critique and insights. Ваш input допоміг нам clarify several key concepts, що лежать в основі methodology.

Також хочемо відзначити early practitioners: Jie Wang, Jian Gao, Yixuan Feng, Siyuan Li, Yixuan Li, Biao Tian, Wei Cheng, Qi Huang, and Yulong Li. Дякуємо за validating SPDD in real projects і за patience, поки approach matured. Ваш frontline feedback був foundational для того, щоб зробити SPDD practical and robust.

Нарешті, у дусі practicing what we preach, сама ця стаття була shaped with the assistance of large language models - Claude 4.5 Sonnet, Claude 4.6 Opus, Gemini 3.1 Pro, and ChatGPT 5.4. Ми використовували їх для prose refinement, structural review, synthesizing suggestions і як thought partners for continuous learning throughout the writing process. Їхній внесок є доречним свідченням того самого approach, який описує ця стаття.

Відповіді на деякі питання

Після публікації цієї статті ми отримали багато питань. Ось кілька відповідей.

With rules, workflow definitions, and execution hooks already governing AI output, what gap does SPDD actually fill - tighter coupling between prompt and code, versioning that prevents drift over time, or both?

І те, й інше; вони підсилюють одне одного. Global rules і hooks є valuable high-level safety net, але в day-to-day engineering вони перебувають на рівні abstraction, який залишає actual generation step opaque. Ось як SPDD закриває gaps, які high-level guardrails alone не закривають:

• Finer-grained control over intent. High-level rules описують broad strategy and boundaries, але залишають generated code black box. SPDD робить problem-solving steps explicit через REASONS Canvas - intent, design, execution, governance - щоб reviewers могли reason about the plan before the code, а humans stayed in the loop where it matters.
• Reusable intent assets. Ad hoc prompts є single-use. SPDD перетворює structured prompts на version-controlled artifacts, що travel with the code, capturing business intent, design decisions and constraints. Саме це closes the loop between prompt and code over time і prevents slow drift, який виникає, коли підтримується лише code.
• A framework for human learning. Якщо ми дозволяємо model produce code unsupervised, наші modelling and abstraction skills з часом слабшають. SPDD змушує developers reason about the problem alongside the tool, тож domain knowledge і design judgement compound across iterations, а не губляться після кожного chat.

How does this differ from traditional instruction sets placed within projects/solutions using progressive disclosure?

Core difference у тому, що SPDD treats the structured prompt as a maintained, version-controlled file:

• Fixed structure instead of free-text rules. Замість open-ended instructions ми використовуємо REASONS Canvas - fixed seven-part template for intent, design, execution and governance. AI має plan inside that shape, що робить план readable and reviewable consistently across the team.
• Intent before code. Commands clarify requirements, domain and approach before generating anything, moving uncertainty to the left. Disagreements resolve at the prompt level, де їх cheap to fix, а не later in code.
• Task breakdown via Operations. Canvas dimension O - Operations decomposes abstract strategy into concrete, testable implementation steps, аж до method signatures and execution order. Reviewers check these steps before code is written, тож generation becomes a faithful translation of an agreed plan.
• Two-way sync, not handoff. Traditional in-project instructions and design docs stale the moment code moves on. In SPDD prompt and code are tied together: коли business rules change, /spdd-prompt-update flows requirements -> prompt -> code; коли code refactored, /spdd-sync flows code -> prompt. Spec stays accurate record of the current system, not historical snapshot.

Humans build the "why" behind decisions through discussions and accumulated context, not just the final code. Does SPDD close that loop with automated learning, or is the "why" still carried by humans?

Це залежить від того, що ми маємо на увазі під "closing the loop". Якщо питання в тому, чи має SPDD closed AI learning loop, де кожен chat silently teaches the model and the system gets smarter on its own, то чесно: ще ні, і це свідомо. openspdd працює як semi-automated, human-led framework, а humans залишаються gatekeepers for all core decisions.

Але сам "why" не залишається locked inside human heads або scattered chat logs. Він captured in the structured prompt as a first-class artifact:

• The Canvas encodes the rationale. R (Requirements with DoD), A (Approach) і Step 3 analysis context явно record what we are solving, why, and which trade-offs we accepted, not just what to build.
• Version control makes it durable. Оскільки prompts committed alongside code, "why" travels with the system across people and time, замість зникати, коли chat window closes або developer leaves the team.
• Two-way sync keeps it current. /spdd-prompt-update flows requirements -> prompt -> code when intent changes; /spdd-sync flows code -> prompt when implementation changes. Artifact stays accurate record of the current system.
• Each iteration starts from accumulated assets. Next enhancement begins with existing Canvas as context, тож domain knowledge and design decisions compound instead of being rediscovered each cycle.

Отже, loop closes by the workflow and the artifact, not by an autonomous learning mechanism. Reviewers shift from "spot the bug" to "check the intent", бо intent тепер є там, де його можна inspect. Це human-led design by choice, і наразі ми вважаємо його правильним, доки automated verification at the asset layer не дозріє достатньо, щоб брати на себе більше навантаження.

If two developers writing the same Canvas can produce different specs - and there is no formal definition of "good" - doesn't SPDD just push the variance problem up a layer rather than solve it?

Чесно кажучи, це справедлива characterization того, де ми є сьогодні. Canvas звужує band of variance порівняно з free-form prompting, але не усуває її. Два developers, що працюють із same requirement, можуть produce different Canvases, і той самий developer може produce a thinner one on a different day. Ми ще не маємо crystallized, objective standard for what a "good" Canvas looks like.

Framework наразі спирається на baseline criteria - structure, granularity, level of abstraction і task breakdown - codified into openspdd commands. Кожна command encodes a thinking strategy, що pulls output toward a consistent shape, raising the floor для less experienced practitioners і даючи reviewers fixed thing to react to. Це meaningful reduction in variance, але не external, automated check.

Closing that remaining gap - наступний напрям governance: automated verification at the asset layer (analysis, Canvas, prompt artifacts), щоб framework сам catches cases, де Canvas structurally complete but substantively under-specified. Until that exists, honest answer is that human judgement is still load-bearing.

How does SPDD hold up as you scale it across multi-project, multi-discipline, multi-domain work - and where does the real ceiling sit: in the AI's capability, or in how cleanly the problem itself can be bounded?

Limit здебільшого на problem side, not the model side. Навіть із stronger model або better learning loop ми не рекомендували б handing a massive, multi-project, cross-domain scope to the AI in one shot. Важливіше, наскільки clearly bounded the problem і скільки prior context the team accumulated; raw model capability rarely the bottleneck. Три причини:

• Decomposition is required. Large or cross-domain scope краще розбивати на smaller, self-contained units, які можна accurately model one at a time. Без цієї discipline навіть strong model loses coherence as scope widens.
• Unclear boundaries cap the success rate. In "context black holes" - domains, де business rules unclear and boundaries weak - SPDD success rate drops, бо model has nothing meaningful to constrain it. More powerful AI does not fix this; it just fails more confidently.
• Decision assets help over time. End-to-end portfolio-scale work не те, що ми сьогодні handed off autonomously. Це зміниться, коли достатньо "decision assets" - historical context, architectural choices, normative patterns - accumulated to raise success rate to acceptable level. До того human-led, unit-by-unit approach is default.

Is SPDD model-agnostic? Does accumulated prompting behave equivalently across Claude, GPT, and Gemini, or could a model change between iterations introduce prompt drift or code divergence? Is the real artifact prompt-as-spec, or prompt + model configuration?

SPDD задуманий як model-agnostic, і ми застосовували його across model generations since Claude 3.5 Sonnet era. Workflow не залежить від single model. Водночас raw capability still matters: stronger reasoning models produce better canvases.

З hands-on experience для heavy-lifting analysis і REASONS Canvas generation steps Claude (особливо Opus) зазвичай лідирує, далі GPT Codex і Gemini 3.x Pro. Однак коли intent locked into structured prompt, наступна phase largely instruction-following, тому switching to a slightly less capable model carries manageable risk of intent drift. Viewed this way, artifact is the spec; model is executor of that spec.

Щодо local-offline vs remote-online: today we do not recommend local-offline LLMs for SPDD. Small models that fit on local hardware lack the capability needed for analysis and canvas-generation steps, а deploying capable large models locally rarely cost-effective.

Отже, SPDD не гарантує absolute determinism, і ми цього не стверджуємо. Він keeps randomness of LLM non-determinism within controllable bounds. Чи трактувати artifact як prompt-as-spec або prompt + model configuration - strategic call, tied to cost, compute and compliance constraints, і teams should make it consciously.

As LLM capabilities have advanced, has the SPDD method itself changed - or only how practical it is to apply?

Method fundamentally hasn't changed. Core loop той самий: anchor everything on the structured prompt and use it to progressively clarify intent.

Змінилося те, скільки manual effort ми можемо hand off to repeatable tooling on top of the LLM. Коли models стали краще following structured prompts and reasoning over richer context, ми distilled each step of the workflow into a reusable thinking strategy - commands like /spdd-analysis, /spdd-reasons-canvas, /spdd-generate, and /spdd-sync. З цього вийшли три речі:

• From template-driven to strategy-driven. Раніше SPDD heavily relied on solution templates: without a well-summarized template up front, output quality dropped, що ускладнювало starting on a new domain. Тепер кожна command encodes the thinking strategy itself, тому навіть без template LLM can follow the strategy to produce a reasonable first cut. We refine from there, and once enough cases have gone through the same strategy, a template emerges as a byproduct.
• Higher automation. Steps, які раніше driven manually with ad hoc prompts, тепер invoked as commands, so workflow runs with far less hand-holding.
• More stable outputs. Оскільки кожна command encodes the same thinking strategy every time, artifacts it produces - analysis, REASONS Canvas, generated code - far more consistent run to run, and therefore easier to govern and review.

As the human "lead", how do you judge when additional prompt engineering is needed over the same portfolio scope?

Я спираюся на three concrete triggers, і вони прямо map to review steps у SPDD workflow:

• Behavioral mismatches. Під час functional testing (typically with /spdd-api-test) я фокусуюся на system behavior rather than implementation detail. Якщо output deviates from defined acceptance criteria, це signal, що prompt didn't capture intent precisely enough - classic logic-correction case, де we update the prompt first, then update the code.
• Overcomplicated logic. Коли reviewing critical code, якщо AI engineered a solution more elaborate than the problem warrants, prompt's Approach або Operations section usually under-specified. Tightening those constraints typically simplifies next generation.
• Instruction failures. Коли AI fails to follow explicit instructions або violates a Norm or Safeguard from the canvas, я трактую це як signal, що constraint needs to be made more prominent or unambiguous in the prompt itself, instead of fighting the same battle again in chat.

Why does SPDD's workflow have six steps instead of the simpler plan-then-code pattern? Couldn't intent just be confirmed once, in a single review after the plan is generated?

Short answer - cognitive load. Intent confirmation має бути distributed across the workflow, бо compressing it into a single review after plan generation puts too much in front of the reviewer at once. На практиці люди не можуть sustain that level of attention: they skim, defer, or approve by default, and intent drift becomes inevitable even when everything looks correct on paper.

Six steps exist so each checkpoint stays small enough to actually engage with:

• Step 1 shapes raw idea into a user story (optionally with AI assistance), а Step 2 - where human reviews and clarifies what that story actually means in business terms, anchoring on the right problem before design work begins.
• Step 3 confirms domain understanding, risks and strategic direction - the "why" and "what".
• Step 4 confirms structured prompt - design and operations - only after analysis is agreed.
• Step 5 confirms behavior and code only after intent is locked.
• Step 6 generates unit tests last, once implementation is stable.

Коли reviewers дивляться на code, requirements, domain model and design already signed off, тому attention може йти до decisions that matter at that stage. Point isn't more steps for their own sake; it's narrower decisions per step, so humans can stay in the loop.

SPDD runs API tests before code review but unit tests after - almost the inverse of TDD. Why is that sequence?

This sequencing was deliberate. Classic TDD uses tests to clarify behavior, protect against regressions and shape design through fast feedback. SPDD still wants all three outcomes - it just distributes them differently across the workflow:

• API tests come first because generated code is cheap. Немає великої цінності deeply reviewing code, який може навіть не satisfy intended business behavior. /spdd-api-test швидко validates the "what" at the system boundary, тож ми знаємо, що reviewing something that actually works before investing human review effort.
• Code review then focuses on what only humans can judge. Once API tests pass, review concentrates on logic, architecture, trade-offs and non-functional concerns, not whether basic behavior is right.
• Unit tests come last as a regression safety net. До цього моменту intent already explicit through structured prompt, а implementation stabilized through API validation and review. Generating unit tests at this point avoids rewriting them after major review-driven changes.

Tests are not less important in SPDD. The change is that intent is made explicit earlier - through structured prompt - and tests can be applied where they create the most leverage.

If hotfixes are rated a poor fit for SPDD, doesn't the highest-signal feedback from production permanently bypass the spec and never make it back into the methodology?

Так було б, якби workflow stopped at the fix. 1-star rating у fitness table стосується upfront fit during the incident itself: під час live production incident system recovery comes first, і зупинятися, щоб write a Canvas, - wrong call. Але governance is not skipped; it is deferred by one step. На практиці ми split hotfixes into two scenarios:

• Scenario A - context exists. Якщо bug falls inside an area already covered by structured prompt, ми використовуємо AI to analyze failure, identify root cause, and then apply standard SPDD loop in compressed form: update the prompt first, then update the code. Це keeps spec and implementation in lockstep, and fix becomes permanent part of governed asset.
• Scenario B - legacy or no prior context. Для urgent fixes in code never brought under SPDD, pragmatic move is to let AI analyze logs and fix the issue directly. Closing step is deliberate post-mortem: synthesize the fix, failure mode and relevant context into newly documented assets. Саме там governance loop closes for legacy code, і так SPDD coverage organically grows over a codebase.

Key point: production signal does feed back, але it requires explicit, human-led documentation step rather than happening automatically. Skipping that step creates spec/code delta; treating it as part of workflow prevents it.

Have you considered having an agent do the prompt/spec review itself - not a human reviewing the Canvas, but an agent that reads the REASONS Canvas alongside the code diff and verifies alignment?

Так, це фактично те, що вже робить команда /spdd-code-review. Вона читає REASONS Canvas і code diff разом і flags where code drifts from stated intent, тож ви можете hand alignment check off to the command whenever you want.

Trade-off у тому, від чого ви відмовляєтесь. Command can check alignment, але humans bring two things to review that an agent cannot replace:

• Catching intent drift. Agent може перевірити, чи code matches Canvas, але тільки human може сказати, чи Canvas itself still matches real business intent. Без цього check fully agent-driven review can look correct on its own terms but still miss the real goal.
• Letting humans learn. Review також місце, де humans learn from AI's choices: patterns, trade-offs, options they had not thought of. Cutting humans out speeds things up, але blocks long-term skill growth that SPDD is designed to protect.

Command is there when you want to use it, але it is built to handle the mechanical part of review, not to take it over. For now, humans stay in the loop by design. Once enough decision rules build up to give real confidence, we may shift more review to the agent step by step, but the part where humans learn from AI is something we plan to keep.

What's next for SPDD - and how will the roadmap reduce its dependence on individual expertise?

Four directions are shaping how the practice will evolve, і всі вони тягнуть в один бік: менше reliance on personal craftsmanship, більше repeatable organization-level capability.

• More recurring workflows captured as commands. Pattern, який почався з /spdd-analysis, /spdd-reasons-canvas і /spdd-generate, далеко не завершений. Коли ми бачимо recurring patterns in real projects, ми keep extracting them into new commands, so each successful workflow becomes reusable rather than knowledge held by individuals.
• Automated verification at the asset layer. Ми досліджуємо automated verification not at the code level but on SPDD assets themselves: analysis, REASONS Canvas and prompt artifacts. Aim - layer automated checks and, over time, some automated decision-making on top of intent-layer assets, so framework can catch gaps, inconsistencies and routine calls that today depend entirely on human review.
• Progressively raising the automation ratio. SPDD already a harness - semi-automated one, with humans in the loop on decisions that matter. Direction is to raise automation ratio inside that harness step by step, paced by what AI can reliably handle in practice.
• A memory mechanism for "decision memory". Goal - let historical decisions, past canvases, trade-offs and accepted patterns act as persistent context, so agent can retrieve right prior reasoning in a given situation instead of rediscovering it each time. Specifics will be shaped by practical feedback.

Together, these directions move SPDD from a method that rewards skilled practitioners to a system where framework itself carries more of the weight.

All of this reflects our current understanding and experience, and is likely to be adjusted as we keep learning and practising.

Footnotes

1. In a one-way pipeline, requirements produce code and the process ends; any later adjustment happens in code alone and the original intent drifts out of date. In SPDD the loop closes on two scales. Within an iteration, feedback flows back: logic corrections update the prompt before the code; refactoring syncs from code back to the prompt, so neither side silently diverges. Across iterations, the accumulated prompt assets become the starting context for the next enhancement.
2. Since this is an optional command, if it is not available in your local environment, you can generate it by running openspdd generate spdd-story.
3. Since this is an optional command, if it is not available in your local environment, you can generate it by running openspdd generate spdd-api-test.

Significant Revisions

• 04 May 2026: Added Q & A
• 28 April 2026: initial publication