Structured-Prompt-Driven Development (SPDD)

The REASONS Canvas

The REASONS Canvas is a structure for generating prompts. It forces
clarity around requirements, domain model, solution approach, system
structure, task decomposition, reusable norms, and safeguards. So the
LLM is guided by intent, not guesswork.

The REASONS Canvas is a seven-part structure that guides a prompt from
intent → design → execution → governance.

Abstract parts (intent & design)

• R — Requirements: What problem are we solving, and what is DoD?
• E — Entities: Domain entities and relationships.
• A — Approach: The strategy of how we’ll meet the requirements.
• S — Structure: Where the change fits in the system; components and dependencies.

Specific parts (execution)

• O — Operations: Break the abstract strategy into concrete, testable implementation steps.

Common standards parts (governance)

• N — Norms: Cross-cutting engineering norms (naming, observability, defensive coding, etc.).
• S — Safeguards: Non-negotiable boundaries (invariants, performance limits, security rules, etc.).

The canvas aligns intent and boundaries before code is generated, moving uncertainty to the left.
Because the structured prompt captures the full specification, reviewers reason about a single artifact instead of scattered chat logs and partial diffs.
By following the same structure, every prompt becomes governable in the same way.
And as domain knowledge and design decisions accumulate in each prompt, they compound individual expertise across iterations and reduce variability across the team.

The SPDD workflow

The workflow brings prompts into the same discipline as code: commit
history, review, and quality gates. It also enforces a simple but powerful rule:

When reality diverges, fix the prompt first — then update the code.

Over time, this changes how teams work. Reviews move away from “spot
the bug” toward “check the intent.” Rework becomes more controlled. And
successful patterns naturally accumulate into a reusable prompt library
that supports AI-First Software Delivery (AIFSD).

If you’ve known about Spec-Driven
Development,
you’ll recognize the same starting point: write the spec clearly first,
then let the model implement. SPDD takes a different angle. It treats
structured prompts as governed, reusable, versioned team assets (REASONS
+ workflow) that evolve alongside the code – an approach that Birgitta
Böckeler categorizes as a spec-anchored approach.

The goal of the SPDD workflow is to turn business input → abstraction →
execution → validation → release into a “closed loop”—and to make sure
prompt assets and code evolve together, not separately.

SPDD workflow

The aim of this workflow is to anchor collaboration on the prompts, so
that developers and product owners can avoid repeated cycles of alignment.
The prompt sets an explicit boundary for code generation, reducing the
randomness of the LLM’s non-determinism, making it easier to govern. By
treating the structured prompts as first-class artifacts in version
control, we turn successful practices into reusable assets, improving
consistency and reducing reinvention.

In practice these steps are carried out through commands provided
by openspdd, a command-line tool that
implements the SPDD workflow. The table below summarizes each
command.

The current system

The current system is a simple billing engine that calculates bills
for using a large-language model. It accepts a record that captures how
many tokens are used in a session and calculates a bill.

The complete codebase for this initial version is
available on GitHub.
The repository includes the initial requirements story
and all the SPDD artifacts used to generate it.
For brevity, we don’t describe that initial generation here, but it follows essentially the same steps as that for the enhancement.
We focus on describing the enhancement because most work on a system are enhancements.

The enhancement

Driven by evolving business requirements and direct user feedback, we are enhancing the billing engine to transition from a static pricing model to a more sophisticated,
flexible infrastructure. This update aims to support diverse subscription strategies and variable, model-specific pricing through the following key changes:

• API enhancement: update the existing POST /api/usage
  endpoint to accept a new, required modelId parameter
  (e.g., “fast-model”, “reasoning-model”).
• Model-aware pricing: shift from a single global rate to dynamic
  pricing, where costs vary depending on the specific AI model
  invoked.
• Multi-plan billing logic: introduce distinct billing behaviors
  based on the customer’s subscription tier:
• Standard plan (optimized): retains the global monthly quota,
  but any overage usage is now calculated using model-specific
  rates.
• Premium plan (new): operates without a quota limit. It
  introduces split billing, where prompt tokens and completion
  tokens are charged separately at different rates depending
  on the model used.
• Architectural scalability: implement an extensible design pattern
  (such as Strategy or Factory) to cleanly isolate the calculation
  formulas for different plans, ensuring the system can easily
  accommodate future pricing models.

Since this new section encompasses both business requirements and technical details,
it is typically completed collaboratively through a pairing session between a PO (or BA) and a developer.

Step 1: Create initial requirements

To kick off the process quickly, we can use the /spdd-story
command to generate a user story directly based on the enhancement. Generally, user stories are provided by the PO or BA.
However, in our workflow, we can transform stories of any form into a consistent format and dimension.
As long as there is shared alignment on the final acceptance criteria, this step can be performed by a PO, BA, or developer, depending on the team’s flexible division of labor.

Instruction:

The AI analyzed the enhancement description and split it into two
user stories:

The auto-generated stories are detailed enough to serve as a baseline
for a formal project. For this walkthrough we consolidate them into a
single simplified story so the example stays self-contained.

Instruction:

Instructions of this kind rarely produce identical text on every run —
models and sampling introduce small differences — so we still expect to
review and tweak the output before treating it as final. The combined
story below is the version we refined for this walkthrough: a deliberately
simplified consolidation of the two initial stories.

Step 2: Clarify analysis

Before jumping into implementation, the developer reviews the user
story to build a shared understanding of what it means in practice. If
there are obvious business-level issues, this is the point to align with
the BA or PO. In this case the story is clear enough, so we move
straight to breaking it down along three dimensions: core logic, scope
boundaries, and definition of done.

Core logic

One new required field on the API: modelId. The customer
now tells us which AI model they used — this is the key that unlocks the
right price.

• Standard Plan: Customer has a monthly token quota. Usage
  within quota is free. Overage is charged at a model-specific rate
  (e.g., fast-model $0.01/1K vs. reasoning-model $0.03/1K). Existing
  quota logic stays; only the rate lookup changes.
• Premium Plan: No quota. Every token is billed from the
  first one. Prompt tokens and completion tokens are charged separately,
  each at a model-specific rate. Bill = prompt charge + completion
  charge. This plan is entirely new.
• Routing: The system determines the customer’s plan and
  dispatches to the matching billing formula. The design must be easy to
  extend — Enterprise plans (Story 2) are next.

Scope boundaries

We are only calculating the current bill. We are NOT building customer
CRUD, NOT querying historical bills, NOT managing subscriptions, and NOT
adding/removing models.

Definition of done

The following scenarios restate the story’s acceptance criteria
with the implementation detail the team needs to verify. The fourth
item (Response format) is not a new business AC — it captures the
non-functional contract the developer adds to make the criteria
testable end-to-end.

• Validation: Missing modelId → HTTP 400.
  Unknown customer → HTTP 404. Negative tokens → HTTP 400. All
  existing validations remain intact.
• Standard Plan billing: A customer with a 100K quota and
  90K already used submits 30K tokens for fast-model ($0.01/1K).
  Expected result: 10K covered by quota, 20K overage, charge $0.20.
  The same request with reasoning-model ($0.03/1K) yields $0.60 —
  same quota logic, different rate.
• Premium Plan billing: A customer submits 10K prompt
  tokens + 20K completion tokens for reasoning-model (prompt $0.03/1K,
  completion $0.06/1K). Expected result: $0.30 + $1.20 = $1.50. No
  quota, no overage — prompt and completion are billed separately.
• Response format: HTTP 201 returning bill ID, customer ID,
  token counts, timestamp, modelId, and a plan-appropriate
  charge breakdown.

If all these scenarios pass, we’ve conquered this story.

Step 3: Generate analysis context

With the requirements and scope clarified, we use the
/spdd-analysis command. By feeding it the business
requirements, we instruct the AI to generate a comprehensive analysis
context.

Instruction:

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

Generated artifact: the initial analysis context document.

This command produces a strategic-level analysis grounded in actual
codebase exploration. The output focuses entirely on the “what” and
“why,” deliberately avoiding granular implementation details at this
stage. It typically covers:

• 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

With our own understanding of the business requirements in mind, we
review the generated analysis document—focusing on the areas
highlighted in the alignment skill. This review serves
two purposes: confirming that our understanding aligns with the AI’s
interpretation, and discovering edge cases or boundary scenarios the AI
might surface that we hadn’t considered.

In this specific instance, the review focused on several critical
areas:

• Whether the Strategy Pattern was appropriately considered.
• Adherence to the OOP principles established in the existing system,
  specifically ISP and SRP.
• The validity of the proposed strategy for adding new fields.
• Identifying edge cases not previously anticipated.
• Uncovering potential technical risks.

Upon completing the review, the AI’s analysis largely aligned with
our architectural intent; in fact, its considerations were even more
comprehensive than ours in certain areas.

Edge cases and risks from the
analysis document

To be transparent, at this stage we only possess a high-level
conceptual alignment. While we can quickly envision the implementation
for areas where we have prior experience, we cannot completely map out
all the granular technical details for the unfamiliar parts right
now.

However, that is perfectly fine. The overarching direction is aligned.
We can proceed to the next step: observing how the AI “simulates” the
concrete implementation details within our established framework and
context. Once we have these tangible details, we can uncover deeper,
hidden issues and make informed trade-offs based on the actual
scenario—adopting the approaches where the benefits outweigh the
drawbacks, and discarding the rest.

Decision: accept the analysis as-is and proceed.

Step 4: Generate structured prompt

Instruction:

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

Generated artifact: the initial structured prompt.

By this point, we’ve already gone through high-level strategy during
the analysis phase—so when reviewing the structured prompt, we’re not
starting from scratch. Instead, we’re examining how the AI has
translated our shared understanding into the REASONS Canvas structure:
from strategy to abstraction to concrete details.

Think of it as a progression: the analysis phase gave us strategic
clarity; now we’re checking whether that clarity has been faithfully
carried through into the architectural abstractions and implementation
specifics. This is intent alignment at a deeper level—ensuring that
before any code is generated, the AI has effectively “simulated” the
entire solution within our defined framework. We get to review from a
global perspective rather than getting lost in details from the
start.

Focus the review on the areas highlighted in the abstraction-first skill. In this case,
this foundational context is already embedded in the codebase and the previous
structured prompt. Consequently, when generating the structured
prompt for this iteration, the AI naturally factors in these
architectural guidelines and OO principles. As a result, even though the
generated content is highly complex, there are remarkably few major
issues. We can opt to proceed with generating the code using this
structured prompt first, and then conduct a deeper review to identify
any potential code-level anomalies later.

So far, we have reached a strong consensus at the intent level,
clarifying both the core problem and the resolution path. While there
may be slight omissions in the details, this is not a concern; having
aligned on the overall scope with the AI makes local optimizations
highly controllable. Now, we transition into the code generation
phase.

Step 5: Generate code

This step is more involved as we are generating the product code,
tests, and our reviews have two alternative outcomes.

Feature verification

During feature validation, the SPDD workflow provides the
/spdd-api-test command to generate functional testing
scripts.

How spdd-api-test works

This command extracts API endpoint information from the code
implementation or acceptance criteria and generates a cURL-based
test script. The script includes a structured test-case table
covering normal scenarios, boundary conditions, and error
scenarios. When executed, it outputs expected-vs-actual comparison
results.

Instruction:

/spdd-api-test

Generated artifact: the API test script.

Guided by the defined rules in the command, the AI generates a
script that formulates the required test scenarios using curl commands.
We can review these AI-generated scenarios in the “TEST CASE OVERVIEW”
section of the script.

Generated API Test Script

Execution: once the script is generated, run it:

sh scripts/test-api.sh

Result: all functional tests passed successfully.

API Test Results

Code review & final adjustments

Thanks to the rigorous intent alignment in the first several steps, the
heavy lifting is already done. At this stage, the remaining issues are
usually minor logic discrepancies or surface-level code smells.

To maintain precision in our engineering practices, we categorize
these final adjustments into two distinct types—based on whether they
change the system’s observable behavior—and handle them using
different strategies within the SPDD workflow:

Two responses to code review changes

Logic corrections (behavior changes)

Strategy: update the prompt first, then generate code. For issues
related to business rules or logic mismatches (which inherently change
the observable behavior of the software), always update the structured
prompt to lock in the correct intent before touching the code. This is
an update or bug fix, not a refactoring.

For instance, when persisting modelId in the bill, we
currently allow this field to be nullable. The underlying reason is the
need to maintain backward compatibility with historical data, making
this workaround a reasonable architectural decision.

Prompt needs update

However, there is an alternative. If the business stakeholders can
confirm what the modelId value should be prior to this
change, we can unify the system’s behavior and eliminate this potential
technical debt. Let’s assume that, after confirming with the business,
the modelId for all historical bills should be set to
fast-model.

With this clear intent, we interact with the AI:

How spdd-prompt-update works

This command incrementally updates the existing Canvas. It
modifies only the sections affected by the change and preserves
everything else. Based on the type of change — new requirement,
architectural adjustment, or constraint change — it automatically
determines which REASONS dimensions need updating.

This differs from /spdd-sync: sync flows from
code to spec when code has changed; prompt-update flows from
requirements to spec when requirements have changed.

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.

The AI updates the structured prompt based on this instruction.

Updated artifact: the updated structured prompt.

Once confirmed, use the /spdd-generate command to
update the corresponding code based on the newly updated structured
prompt:

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

The AI, guided by the rules defined within the
/spdd-generate command, comprehends the required changes
and performs targeted updates exclusively on the affected
codebase.

Updated artifact: the updated code.

It is important to note that we do not regenerate the entire
codebase. We continue using the existing structured prompt and the AI
handles targeted diffs:

1. Identify the mismatch: notice that the behavior of
   modelId during persistence is inconsistent with the new
   business requirement (it must be mandatory with a default).
2. Target the prompt snippet: copy the specific section from the
   structured prompt that defines the outdated logic.
3. Update the prompt: paste the extracted snippet into the chat
   alongside the revised business rule, instructing the AI to update
   the structured prompt first.
4. Generate targeted code updates: once the prompt reflects the new
   truth, run /spdd-generate pointing to the updated file.
   The AI automatically performs targeted diffs exclusively on the
   affected codebase, rather than regenerating everything from
   scratch.

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;
    }

Regression test

Once all optimizing is complete, restart the service and run the
API test script one more time to ensure no core functionality was
broken during the cleanup.

Result: all passed.

Regression Test Results

Step 6: generate unit tests

Functional testing alone is insufficient for robust validation; it
acts primarily as an auxiliary check and is not factored into code
coverage metrics. The final sign-off on core logic requires
comprehensive unit tests. Currently, the SPDD workflow does not have
dedicated testing commands finalized (these will be introduced in
future iterations). As an interim solution, we utilize a
template-driven approach to generate structured prompts for unit
testing.

What this example delivered

This marks the conclusion of a complete SPDD workflow. Through this
standardized process, we successfully delivered the following key
outcomes:

1. A business logic implementation with exceptionally high intent
   alignment (~99%).
2. Complete engineering transparency, including a clear
   understanding of the implementation path, technical decisions, and
   accepted trade-offs.
3. A structured prompt asset tightly synchronized with the current
   codebase, laying a solid foundation for future iterations.
4. Compounding human expertise, fostering a continuous accumulation
   of developer experience and mental models as we iterate
   collaboratively with the AI.

View the complete code diff for this enhancement on GitHub.

We’ve also prepared a bonus enhancement feature—Enterprise
Plan Volume-Based Tiered Billing. If you’re interested in getting
some hands-on practice, we highly encourage you to tackle it using the
SPDD workflow outlined above.

Fitness assessment

SPDD is an engineering investment. The table below rates how well it pays off by scenario, from highly recommended (5 stars) to not suitable (1 star).

Trade-offs to consider

Return on investment

Upfront investment