From Spec to Ship: Building a Video SaaS with AI Long-Horizon Tasks
This article examines why long-horizon tasks mark the real dividing line in AI-assisted programming and how to tame them with spec-driven development. Using the concrete goal of building a commercial, UGC-driven short-video generation SaaS from scratch, it walks through a strict research → architecture → implement workflow, the requirements and constraint prompt template, context and progress management, and a minimal complete architecture covering layering, the multi-tenant data model with row-level security, asynchronous task orchestration, authentication, billing with a freeze-settle-refund model, and security and compliance. It also catalogs typical pitfalls and tuning strategies, provides an acceptance checklist for judging whether a system is truly production-ready, and concludes with a candid account of what AI handles well versus what still requires human judgment.
1. Why “Long-Horizon Tasks” Are the Dividing Line in AI Programming
Over the past two years, “Can AI write code?” has long stopped being the real question. The true dividing line is how long AI can work continuously and how reliably it does so. Code completion solves “writing the next function,” conversational generation solves “writing a script,” but software delivery is about “building an entire system.” The jump from one to the other does not grow in difficulty linearly.
A commercial SaaS platform must handle at least six categories of problems at the same time:
- API design: how endpoints are layered, how they are versioned, and how error codes are standardized;
- Data modeling: table structures, indexes, constraints, and foreign-key relationships;
- Asynchronous task orchestration: video generation is time-consuming, so requests cannot block synchronously;
- Authentication and billing: identity verification, token validation, quota deduction, and ledger consistency;
- Multi-tenant isolation: different users’ data, files, and resources must never cross boundaries;
- Security and compliance: key management, uploaded-content moderation, and data retention and deletion policies.
These problems are deeply coupled: one decision ripples across the other five. Human teams usually rely on architecture documents, review meetings, task breakdown, and long-term memory to maintain consistency. Large language models, however, face two inherent constraints:
- A limited context window: once a project grows beyond a certain size, history is forced to be compressed;
- Autoregressive generation lacks a global view: it tends toward local optima and easily falls into “treating the head when the head hurts.”
The three concepts the industry often discusses—Agentic capability, Long-Horizon Task, and System Engineering—correspond precisely to three progressive questions:
| Capability Dimension | Core Question | Key Mechanisms | Primary Risks |
|---|---|---|---|
| Agentic | Can AI plan, call tools, and verify results on its own? | Tool calling, task decomposition, self-checking | Runaway loops, ineffective retries |
| Long-Horizon | Can AI work continuously for hours without drifting? | Context management, staged deliverables, persistent state | Context drift, internal contradictions |
| System Engineering | Can AI assemble multiple modules into a consistent, runnable system? | Architectural constraints, interface contracts, automated testing | Locally correct, globally inconsistent |
Therefore, evaluating a coding agent should not stop at “does the generated page look good,” but should examine whether it can maintain architectural consistency across long tasks, correct its own mistakes, and deliver verified results.
To test this capability, you can design a sufficiently “hardcore” ultimate exam: build a commercial short-video UGC video generation SaaS platform from scratch, without relying on ready-made templates. This article uses that goal as its main thread and breaks down the methodology and engineering implementation in full.
2. Topic Selection: From “Teaching to Fish” to “Giving the Fish”
2.1 What Cross-Border E-Commerce Sellers Actually Want
In recent years, video generation models have improved rapidly, and short-video product promotion has become an important customer-acquisition channel for cross-border merchants. Many tech bloggers love to share various automation workflows, teaching people “how to piece videos together.” But after working closely with merchants, you discover a counterintuitive fact: most merchants do not want to learn workflows.
Their concerns are refreshingly simple:
- Does a video cost a few cents or a few dollars?
- Can we reliably produce thousands a day?
- Can we just open a web page, upload materials, click generate, and get a publishable finished video?
The dividing line here is this: workflows target “hands-on technical users,” while SaaS targets “business users who pay only for results.” The former sells a method; the latter sells certainty.
2.2 The Value of the Topic as a Stress Test
A demo page needs only a frontend and static data, whereas a commercial SaaS must productize all the demands above: users upload images, the system automatically handles storyboarding, voiceover, subtitles, and compositing, and outputs product-promotion short videos ready for distribution. The value of this topic lies in its coverage:
- A complete user loop: sign up and log in → upload materials → submit a task → asynchronous generation → download the finished video → credit settlement;
- A complete technology stack: frontend UI, API service, relational database, object storage, task queue, and video rendering service;
- Real engineering constraints: multi-tenant isolation, long-running tasks, billing consistency, content compliance, and cost control.
Only when a system like this runs end to end can we say the coding agent has reached delivery-grade capability.
3. Methodology: Taming Long-Horizon Tasks with Spec-Driven Development
3.1 Why Spec-Driven Development Is Needed
In long tasks, models are most prone to three problems: forgetting early agreements, reinventing the wheel across different modules, and producing inconsistent interfaces front to back. The core idea of Spec-Driven Development (SDD) is to solidify “what to build” and “how to build it” into searchable, verifiable documents before writing code. This effectively gives AI the equivalent of a human team’s “requirements document + architecture document + acceptance checklist.”
The whole process is divided into three stages, executed in strict order; a stage may not proceed to the next until it passes review:
Research → Design → Implement↓ ↓ ↓docs/research.md docs/architecture.md layered, sliced implementation(needs &选型) (interfaces & data model) (test-driven + per-slice acceptance)
3.2 Requirements and Constraints Prompt Template
The following is an illustrative prompt that can be reused directly:
You are a senior full-stack architect. Help me build a "short-video UGC video generation SaaS."Strictly adopt Spec-Driven Development (SDD), progressing through three stages:"Research → Design → Implement." At the end of each stage, produce the correspondingdocument, and wait for my confirmation before entering the next stage.【Product Goal】Merchants upload product images and selling-point copy; the system automatically generatesproduct-promotion short videos. Users consume credits per video and log in via phone numberand verification code.【Overall Constraints】1. Choose only general-purpose technologies; do not bind to any specific vendor's proprietary APIs;2. Every external service call must have timeout, retry, idempotency, and fallback strategies;3. All data access must go through a unified data access layer that forcibly carries a tenant ID;4. Any change involving money or credits must complete in a single transaction and record a ledger entry;5. Never hardcode secrets in code or config; read all secrets from environment variables.【Stage 1: Research】- Map the target users' complete journey and core feature list;- Tag priorities as MVP / Phase 2 / Deferred;- Define non-functional requirements: performance targets, availability, security, and compliance;- Output docs/research.md.【Stage 2: Design】- Provide system layering and module responsibilities;- Define database table structures, indexes, and constraints;- Define RESTful API specifications (including error codes);- Design the task state machine and the credit transaction flow;- Output docs/architecture.md and the interface contract document.【Stage 3: Implement】- Implement in slices, in the order "infrastructure → data layer → business services → API layer → frontend pages";- Every slice must include unit tests and pass self-testing;- After completing each slice, update the progress file and to-do list;- When you hit an uncertain dependency, record the assumption and continue, then reconcile everything at the end.【Self-Check List】After completing each module, confirm item by item:□ Are there any unhandled exception paths?□ Is there any risk of privilege escalation?□ In concurrent scenarios, could duplicate charges occur?□ Do failed tasks have retry and compensation mechanisms?
3.3 Context and Progress Management
Long tasks also need lightweight context management mechanisms in place:
- Layered spec documents: the master document keeps only architectural decisions and interface agreements, while detailed content is split into sub-documents per module and loaded on demand;
- Progress checklist: use a to-do list to record the status of each slice (not started, in progress, verified, blocked) to prevent omissions or duplication;
- Prioritize stage deliverables: produce “structured intermediate artifacts” such as documents, interface definitions, and test cases first, which are more resilient to compression and easier to verify than pure natural-language descriptions;
- Decision records: write architectural choices together with their rationale and alternatives into decision records, so later adjustments remain traceable.
In practice, the quality of the spec directly determines the quality of the long task. The more the spec reads like “executable acceptance criteria,” the lower the chance that AI drifts off course.
4. Architecture Highlights: A Minimal Complete Skeleton for a Video SaaS
4.1 Overall Layering
The recommended architecture is the classic “separated frontend and backend + asynchronous tasks”:
[Browser / Mini-Program]│ HTTPS▼[API Gateway / Load Balancer] ──► [Business API Service (stateless, horizontally scalable)]│┌────────────────────────┼────────────────────┐▼ ▼ ▼[Relational DB] [Object Storage] [Task Queue](users/credits/tasks) (materials & outputs) (producer-consumer model)│▼[Render Worker Cluster]├─ material download & transcoding├─ script/voiceover/subtitle generation (calls model inference)└─ video compositing & watermarking
Responsibilities of each layer:
- Business API service: authentication, parameter validation, quota checks, task creation and querying;
- Relational database: stores users, credit ledger, and task metadata; it is the anchor for transactional consistency;
- Object storage: stores uploaded materials and output videos, distributed via time-limited temporary links;
- Task queue + workers: offload video generation, which takes minutes, from the request path, achieving peak shaving and failure retries.
4.2 Data Model and Multi-Tenant Isolation
A minimal viable data model includes:
| Table | Key Fields | Purpose |
|---|---|---|
| users | id, phone, nickname, status, created_at | User master data |
| user_quota | user_id, balance, updated_at | Credit balance (separate table for easy row locking and auditing) |
| credit_ledger | id, user_id, amount, biz_type, biz_id, created_at | Credit ledger, ensuring traceability |
| materials | id, user_id, storage_key, type, status | Uploaded materials |
| video_tasks | id, user_id, status, progress, params, result_key, cost, idempotency_key | Video generation tasks |
| audit_logs | id, user_id, action, ip, created_at | Audit of key operations |
Design highlights:
- Separate balance from ledger: the balance table supports atomic deduction, the ledger table records every change, and the two must reconcile;
- Unique constraint as an idempotency backstop: put a unique index on idempotency_key in the task table so duplicate submissions hit the existing task directly;
- Row-Level Security (RLS): inject the current user ID into every connection at the data access layer, and let the database intercept unauthorized access uniformly:
-- Example: enable row-level security and define an access policyALTER TABLE video_tasks ENABLE ROW LEVEL SECURITY;CREATE POLICY video_tasks_owner ON video_tasksUSING (user_id = current_setting('app.current_user_id')::bigint);-- The ledger table is append-only; clients may not modify history directlyCREATE POLICY credit_ledger_insert ON credit_ledgerFOR INSERT WITH CHECK (user_id = current_setting('app.current_user_id')::bigint);
RLS is the “last gate” of defense in depth. Even if the application layer has an oversight, unauthorized data cannot be queried.
4.3 Asynchronous Task Orchestration
Video generation usually takes minutes and depends on external inference services, so it must be made asynchronous. The core elements include:
- Task state machine:
pending → queued → running → succeeded / failed / canceled, with all state changes performed through a unified state machine function and no scattered assignments; - Idempotent submission: the frontend carries an idempotency key, and the server checks before creating, preventing duplicate charges from network retries;
- Fair scheduling: set per-tenant concurrency limits and priorities so a single user cannot monopolize rendering resources;
- Failure handling: distinguish retryable errors (network timeouts, downstream rate limiting) from non-retryable errors (non-compliant materials, invalid parameters); retry the former with exponential backoff up to a maximum count, and terminate the latter immediately with a reason;
- Graceful cancellation: users can cancel a task while it is queued or running, and workers check the cancellation flag at key points;
- Observable progress: workers periodically write back progress for the frontend to poll or receive via long-lived connections.
Server-side task creation pseudocode:
def create_video_task(user, request, idempotency_key):# 1. Idempotency check: return the existing task if one is foundexisting = task_repo.find_by_idem(user.id, idempotency_key)if existing:return existing# 2. Validate parameters and material ownership to prevent unauthorized# references to another user's materialsmaterials = material_repo.get_for_user(user.id, request.material_ids)# 3. Atomic charge: balance check + deduction + ledger entry in one transactioncost = pricing.quote(request.duration, request.resolution)ledger = billing.charge_atomic(user.id, cost,biz_type="video_generate",biz_id=idempotency_key)# 4. Create the task and enqueue it; roll back the charge if enqueueing failstask = task_repo.create(user.id, request, cost, idempotency_key)try:queue.publish(task.id, priority=task.priority)except Exception:billing.refund_atomic(ledger.id)task_repo.mark_failed(task.id, reason="enqueue_failed")raisereturn task
On the worker side, the order is “claim first, execute, then write back”: after pulling a message from the queue, atomically claim the task first (transition the status from queued to running, and verify the lease and retry count), then perform rendering, and finally write back the result. This way, even if a message is redelivered, the same task will not be executed concurrently twice.
4.4 Authentication and Billing
Authentication: use phone-number verification-code login, issuing a short-lived access token and a long-lived refresh token. All protected endpoints validate the token uniformly and inject the user ID into the data access context, working together with RLS.
Billing: use a “freeze → settle → refund on failure” model.
Submit task → validate and freeze estimated credits → execute task├─ Success → settle by actual consumption, refund the difference└─ Failure → refund all frozen credits
Key constraints:
- Every credit change must carry a unique business ledger number, with idempotency guaranteed by a database unique index;
- Credit operations must not be completed across service calls, to avoid the complexity of distributed transactions;
- When the balance is insufficient, reject at the submission stage, so workers do not run empty and waste compute.
Anti-abuse and risk control: set limits on the number of tasks per user per unit time and the number of registrations per device. Verification-code sending frequency and login failure counts need rate limiting to guard against SMS costs and credential-stuffing risk.
4.5 Security and Compliance
- Key management: inject all third-party credentials via environment variables or a secrets-management service, never committing them to the code repository;
- Transport and access control: encrypt end to end; materials and output videos in object storage are private by default and accessible only via short-lived links;
- Content safety: run uploaded materials and output videos through machine moderation plus spot checks, keeping moderation records for traceability;
- Data retention and deletion: define retention periods for materials and outputs, and support deleting personal data as required after a user closes their account;
- Audit logs: log key operations such as login, charging, and task cancellation, writing desensitized logs to a logging service.
5. Long-Horizon Tasks in Practice: Typical Pitfalls and Tuning
| Problem | Typical Symptom | Tuning Strategy |
|---|---|---|
| Context drift | Naming and fields inconsistent across modules | Treat the spec document as the single source of truth; for interface changes, update the doc before the code |
| Reinventing the wheel | Each module writes its own pagination, error handling | Define shared infrastructure in the architecture stage; later modules reference it uniformly |
| Rework loops | Tests fail repeatedly with small patches, stuck in a futile loop | Set a maximum retry count per point; on exceeding it, go back to the spec to find the root cause |
| Pseudo-implementation | External calls use “fake returns” as placeholders | Require real call paths + timeout fallback + injectable mocks for testing |
| Interface mismatch | Frontend fields don’t match backend responses | Generate type definitions and mock data from the interface contract document |
| Duplicate queue consumption | The same task runs multiple times, duplicate charges | Triple safeguard: state-machine claiming on the consumer side + idempotency key + unique index |
| Irreversible migration | Database changes lack rollback scripts | Provide both upgrade and rollback scripts for every change |
| Progress distortion | A long task can’t resume after interruption | Persist the progress checklist and architecture document; read them before resuming execution |
The most worth emphasizing is “rework loops.” Once AI hits a failure in a long task, it tends to patch immediately, but the root cause often lies at the architecture level. The sensible approach is to agree that after a problem fails several times in a row, you must pause editing, go back to the spec document to recheck assumptions, and adjust the architectural decision if necessary while recording the reason.
6. Acceptance Checklist: How to Judge “Truly Production-Ready”
- Functional: sign up and log in, upload materials, submit tasks, poll progress, download output, credit deduction and refund—the entire chain works;
- Consistency: under high concurrency, duplicate submissions produce no duplicate charges, and a failed task always refunds credits;
- Isolation: User A cannot read or reference User B’s materials and tasks, and unauthorized requests are intercepted at the database layer;
- Reliability: if a worker crashes, the task can be rescheduled without being executed twice;
- Observability: task duration, failure rate, and rendering cost can be measured, and critical alerts can be delivered;
- Compliance: secrets are not stored in the database, materials are private, moderation is logged, and deletion on account closure is supported.
This checklist can serve directly as acceptance input for SDD, letting AI self-check against acceptance criteria during the development stage instead of discovering problems only during manual testing.
7. Lessons Learned: The Capability Boundary of Long-Horizon Tasks
After completing a practice like this, you can form a few relatively level-headed judgments.
What AI is truly good at is “structural work”: scaffolding, boilerplate code, data model drafts, test-case generation, document organization, and parallel implementation of multiple modules around clear contracts. This work has clear rules, is verifiable, and is highly repetitive.
What must still be borne by humans is “judgment work”:
- Requirement prioritization: which features go into the MVP and which are deferred depends on business, not technology;
- Architectural trade-offs: choices among consistency, cost, and latency require judgment based on business scale;
- Security auditing and compliance judgment: AI can write an RLS policy, but it cannot bear responsibility for a data leak on your behalf;
- Cost control: generation can be infinitely long and external calls infinitely expensive, so the budget boundary must be drawn by a human.
A more accurate statement, then, is that AI programming has indeed entered a new phase—moving from “assisting with writing code” to “delivering continuously under clear specs.” But it has not replaced engineering judgment; rather, it shifts the engineer’s role from “the person who writes code” to “the person who defines the problem, sets constraints, and reviews results.”
At the methodology level, this can be distilled into three principles:
- Spec first, code second: make AI work under structured constraints;
- Contract first, implementation second: put interfaces and data models in place early to reduce late rework;
- Acceptance first, expansion second: make every slice verifiable before moving to the next.
Once you master this method, even individual developers can advance system-level projects at a pace close to that of a small team. Tools are evolving, but what remains truly scarce is the ability to turn vague requirements into clear specs.
