Tencent CloudBase Spec Workflow

The Specific Problem It Solves

When developing new features or architectural changes, teams often struggle with vague requirements and lack of structured planning. This leads to direct coding that mismatches expectations, frequent rework, and poor cross-module coordination. Common scenarios include new page or system design, multi-step product changes, and database or UI-intensive work, all of which require clear acceptance criteria and staged confirmations to avoid drifting from user goals.

How the Skill Works: The Spec Workflow

This skill provides a structured workflow through four core phases to ensure orderly development:

• Requirements Phase: Create specs//requirements.md, using EARS (Easy Approach to Requirements Syntax) for user stories and acceptance criteria. Key steps involve:
• Restating the problem and scope, clarifying business rules, constraints, and non-goals.
• For example, acceptance criteria follow the pattern THE <system> SHALL <functional requirement> WHEN <trigger> IF <condition>, ensuring they are specific and testable.
• Design Phase: Create specs//design.md, describing architecture, module boundaries, and technical choices. This covers:
• Explaining technical trade-offs, defining data models, APIs, security strategies, and testing approaches.
• Using Mermaid diagrams only when they materially improve clarity, avoiding overcomplication.
• Tasks Phase: Create specs//tasks.md, breaking the design into executable tasks. Requirements include:
• Keeping tasks specific, reviewable, and linked back to relevant requirements, with formats like - [ ] Task description.
• Updating task status as work progresses to maintain traceability.
• Execution Phase: Start implementation only after user confirms the task plan. During execution:
• Complete one meaningful unit at a time, keeping task status current.
• Preserve traceability from changes to tasks to requirements, ensuring consistency.

The skill also emphasizes working rules: ask follow-up questions when requests are underspecified instead of guessing core behavior; require confirmation between requirements, design, and task breakdowns; involve ../ui-design/SKILL.md early for page or visual decisions; and keep documents concise but testable, prioritizing user-visible outcomes.

Usage Boundaries and Considerations

• When to Use: Suitable for medium to large tasks, cross-module changes, and scenarios with fuzzy acceptance criteria, such as defining new features, designing architecture, or handling database/UI-intensive work.
• When to Skip: For small bug fixes, single-file documentation updates, straightforward config changes, or tiny refactors where the user provides precise implementation instructions, direct execution without forced spec artifacts is allowed.
• Common Pitfalls:
• Jumping into coding before explicit acceptance criteria, leading to requirement drift.
• Skipping user confirmation between phases, like moving from requirements to design without feedback.
• Writing vague tasks that don't map back to user-visible outcomes, focusing only on technical details.
• Treating UI work as purely technical implementation without clarifying design intent, which can disconnect from user experience.

Following this workflow helps teams reduce rework and improve development quality, but it should be applied flexibly based on task scale.