6.7 KiB
6.7 KiB
Feature Specification: [FEATURE NAME]
Feature Branch: [###-feature-name]
Created: [DATE]
Status: Draft
Input: User description: "$ARGUMENTS"
User Scenarios & Testing (mandatory)
User Story 1 - [Brief Title] (Priority: P1)
[Describe this user journey in plain language]
Why this priority: [Explain the value and why it has this priority level]
Independent Test: [Describe how this can be tested independently - e.g., "Can be fully tested by [specific action] and delivers [specific value]"]
Acceptance Scenarios:
- Given [initial state], When [action], Then [expected outcome]
- Given [initial state], When [action], Then [expected outcome]
User Story 2 - [Brief Title] (Priority: P2)
[Describe this user journey in plain language]
Why this priority: [Explain the value and why it has this priority level]
Independent Test: [Describe how this can be tested independently]
Acceptance Scenarios:
- Given [initial state], When [action], Then [expected outcome]
User Story 3 - [Brief Title] (Priority: P3)
[Describe this user journey in plain language]
Why this priority: [Explain the value and why it has this priority level]
Independent Test: [Describe how this can be tested independently]
Acceptance Scenarios:
- Given [initial state], When [action], Then [expected outcome]
[Add more user stories as needed, each with an assigned priority]
Edge Cases
- What happens when [boundary condition]?
- How does system handle [error scenario]?
Requirements (mandatory)
Functional Requirements
- FR-001: System MUST [specific capability, e.g., "allow users to create accounts"]
- FR-002: System MUST [specific capability, e.g., "validate email addresses"]
- FR-003: Users MUST be able to [key interaction, e.g., "reset their password"]
- FR-004: System MUST [data requirement, e.g., "persist user preferences"]
- FR-005: System MUST [behavior, e.g., "log all security events"]
Example of marking unclear requirements:
- FR-006: System MUST authenticate users via [NEEDS CLARIFICATION: auth method not specified - email/password, SSO, OAuth?]
- FR-007: System MUST retain user data for [NEEDS CLARIFICATION: retention period not specified]
Technical Requirements (Constitution-Driven)
Tech Stack Compliance:
- All HTTP operations use Fiber framework (no
net/httpshortcuts) - All database operations use GORM (no
database/sqldirect calls) - All JSON operations use sonic (no
encoding/jsonusage) - All async tasks use Asynq
- All logging uses Zap + Lumberjack.v2
- All configuration uses Viper
- Uses Go official toolchain:
go fmt,go vet,golangci-lint
Architecture Requirements:
- Implementation follows Handler → Service → Store → Model layers
- Dependencies injected via struct fields (not constructor patterns)
- Unified error codes defined in
pkg/errors/ - Unified API responses via
pkg/response/ - All constants defined in
pkg/constants/(no magic numbers/strings) - No hardcoded values: 3+ identical literals must become constants
- Defined constants must be used (no duplicate hardcoding)
- Code comments prefer Chinese (implementation comments in Chinese)
- Log messages use Chinese (logger.Info/Warn/Error/Debug in Chinese)
- Error messages support Chinese (user-facing errors have Chinese text)
- All Redis keys managed via
pkg/constants/key generation functions - Package structure is flat, organized by feature (not by layer)
Go Idiomatic Design Requirements:
- No Java-style patterns: no getter/setter methods, no I-prefix interfaces, no Impl-suffix
- Interfaces are small (1-3 methods), defined where used
- Error handling is explicit (return errors, not panic)
- Uses composition (struct embedding) not inheritance
- Uses goroutines and channels for concurrency
- Naming follows Go conventions:
UserIDnotuserId,HTTPServernotHttpServer - No Hungarian notation or type prefixes
- Simple and direct code structure
API Design Requirements:
- All APIs follow RESTful principles
- All responses use unified JSON format with code/message/data/timestamp
- All error messages include error codes and bilingual descriptions
- All pagination uses standard parameters (page, page_size, total)
- All time fields use ISO 8601 format (RFC3339)
- All currency amounts use integers (cents)
Performance Requirements:
- API response time (P95) < 200ms
- Database queries < 50ms
- Batch operations use bulk queries
- List queries implement pagination (default 20, max 100)
- Non-realtime operations delegated to async tasks
- Uses
context.Contextfor timeouts and cancellation
Testing Requirements:
- Unit tests for all Service layer business logic
- Integration tests for all API endpoints
- Tests use Go standard testing framework with
*_test.gofiles - Table-driven tests for multiple test cases
- Tests are independent and use mocks/testcontainers
- Target coverage: 70%+ overall, 90%+ for core business logic
Key Entities (include if feature involves data)
- [Entity 1]: [What it represents, key attributes without implementation]
- [Entity 2]: [What it represents, relationships to other entities]
Success Criteria (mandatory)
Measurable Outcomes
- SC-001: [Measurable metric, e.g., "Users can complete account creation in under 2 minutes"]
- SC-002: [Measurable metric, e.g., "System handles 1000 concurrent users without degradation"]
- SC-003: [User satisfaction metric, e.g., "90% of users successfully complete primary task on first attempt"]
- SC-004: [Business metric, e.g., "Reduce support tickets related to [X] by 50%"]