Initial commit

2025-11-30 09:05:29 +08:00
commit 91fde12a8b
51 changed files with 11738 additions and 0 deletions
--- a/commands/spec.md
+++ b/commands/spec.md
@@ -0,0 +1,560 @@
+## Spec
+
+**"Give structure before writing code"** - Fully compliant with Kiro's spec-driven development
+
+Unlike traditional code generation tools, it realizes Kiro's specification-driven development focused on bringing structure to development chaos. From minimal requirement input, it progressively develops from detailed product manager-level specifications to implementable designs, ensuring consistent quality from **prototype to production**.
+
+### Usage
+
+```bash
+# Request Spec Mode from Claude (minimal requirement input)
+"Create a spec for [feature description]"
+
+# Kiro's step-by-step development:
+# 1. Simple requirements → Automatic generation of detailed user stories
+# 2. Structured requirement descriptions using EARS notation
+# 3. Refinement of specifications through step-by-step dialogue
+# 4. Generation of 3 independent files:
+#    - requirements.md: Requirement definitions using EARS notation
+#    - design.md: Design including Mermaid diagrams and TypeScript interfaces
+#    - tasks.md: Implementation plan with automatic application of best practices
+```
+
+### Proven Results (Kiro Track Record)
+
+**Secure File Sharing App in 2 Days**
+
+```bash
+"Create a spec for a file sharing system (with encryption)"
+→ Production-level encrypted file sharing application completed in 2 days
+→ Automatic application of security best practices
+→ No additional prompts needed
+```
+
+**Game Development in One Night (For Beginners)**
+
+```bash
+"Create a spec for a 2D puzzle game"
+→ Open source developer with no game development experience
+→ Game completed in one night
+→ Kiro handles implementation logic, allowing developers to focus on creativity
+```
+
+**Weekend Prototype→Production**
+
+```bash
+"Create a spec for an EC site product management system"
+→ Concept to working prototype in one weekend
+→ Consistent quality from prototype to production
+→ Structured approach through spec-driven development
+```
+
+### Basic Examples
+
+```bash
+# Create spec for new feature (minimal input)
+"Product review system
+- Star rating functionality
+- Comment posting
+- Image upload"
+
+# Create spec for system feature
+"User authentication
+- OAuth support
+- Multi-factor authentication"
+
+# Create spec for API feature
+"Payment system API
+- Stripe integration
+- Security-focused"
+```
+
+### Collaboration with Claude
+
+```bash
+# Complex feature spec
+"Create a spec for chat functionality including WebSocket, real-time notifications, and history management"
+
+# Database integration feature spec
+"Create a spec for EC site inventory management functionality including product addition, inventory updates, and alert functionality"
+
+# Frontend feature spec
+"Create a spec for a React dashboard including graph display, filtering, and export functionality"
+
+# Backend feature spec
+"Create a spec for a RESTful API including authentication, validation, and logging"
+```
+
+### Features of Spec Mode
+
+**Step-by-Step Dialogue Workflow**
+
+- Fully reproduces Kiro's original value of step-by-step discussion
+- Refines specifications collaboratively with users at each phase
+- Generates files through question resolution, option discussion, and approval processes
+
+**Three Phases of Interactive Development**
+
+- **Phase 1**: Requirements Discovery → Discussion → Approval → `requirements.md` generation
+- **Phase 2**: Design Exploration → Discussion → Approval → `design.md` generation
+- **Phase 3**: Implementation Planning → Discussion → Approval → `tasks.md` generation
+
+**Dynamic Specification Development**
+
+- Resolves requirement ambiguities through dialogue
+- Presents and discusses technical options
+- Explains trade-offs and confirms decisions
+
+### Detailed Examples
+
+```bash
+# Complex system feature
+"Create a spec for an online payment system including Stripe integration, security, and error handling"
+
+# Frontend feature
+"Create a spec for a React component including state management, property design, and testing"
+
+# Backend feature
+"Create a spec for a GraphQL API including schema design, resolvers, and authentication"
+
+# DevOps feature
+"Create a spec for a CI/CD pipeline including test automation, deployment, and monitoring"
+```
+
+### Phase-by-Phase Dialogue Workflow
+
+#### Phase 1: Requirements Discovery & Discussion
+
+**1. Automatic Expansion from Minimal Input (Kiro Style)**
+
+```text
+User: "User management system
+- Login functionality
+- Profile editing
+- Administrator permissions"
+
+Claude: "I'll generate detailed user stories from your requirements.
+Is this understanding correct?
+
+Automatically generated user stories:
+- User registration and authentication (OAuth compatible)
+- Profile management (avatar, settings)
+- Permission management (RBAC)
+- Password reset functionality
+- Security audit logs
+
+I've added some details you didn't mention. Anything else we need?"
+```
+
+**2. Structured Requirements Description Using EARS Notation**
+
+```text
+Claude: "Let me structure this using EARS notation:
+
+Here are the requirements in EARS format:
+
+WHEN a user attempts to log in
+GIVEN they enter the correct email address and password
+THEN the system shall confirm authentication
+AND redirect to the dashboard on success
+
+WHILE a user is on the profile editing screen
+THE SYSTEM SHALL perform real-time validation
+AND display a preview of changes
+
+WHERE access is attempted to a feature requiring administrator privileges
+IS when the system shall check permission levels
+AND deny access if insufficient"
+```
+
+**3. Automatic Completion of Edge Cases and Security Requirements**
+
+```text
+Claude: "Following best practices, I've also thought of these:
+
+Security requirements (auto-added):
+- Brute force protection
+- Session management and timeouts
+- CSRF and XSS protection
+- Password strength rules
+
+Edge cases (auto-detected):
+- Multiple login handling
+- Account lockout
+- Data consistency during migration
+- High traffic handling
+
+Do these look good?"
+```
+
+**5. Phase 1 Completion and Approval**
+
+```text
+Claude: "Requirements phase done.
+Should I create requirements.md?"
+→ "Yes" → generates requirements.md
+```
+
+#### Phase 2: Design Exploration & Discussion
+
+**1. Codebase Analysis + Automatic Design Proposal (Kiro Style)**
+
+```text
+Claude: "After analyzing your codebase, here's my recommended architecture:
+
+Codebase analysis results:
+- Authentication: JWT + Express.js (v4.18.x)
+- Database: PostgreSQL (v14+)
+- Frontend: React + TypeScript (v18+)
+- Existing patterns: Repository pattern, service layer separation
+
+Kiro recommended architecture:
+- Clean Architecture compliant
+- Domain-Driven Design elements
+- Partial application of CQRS pattern
+- Automated security best practices
+
+Shall we proceed with this design?"
+```
+
+**2. Visual Design with Mermaid Diagrams**
+
+```text
+Claude: "I've automatically generated a system design using Mermaid diagrams:
+
+Automatically generated architecture diagram:
+
+graph TB
+    Client[React Client] --> API[Express API Gateway]
+    API --> Auth[Auth Service]
+    API --> User[User Service]
+    API --> Profile[Profile Service]
+
+    Auth --> AuthDB[(Auth Database)]
+    User --> UserDB[(User Database)]
+    Profile --> ProfileDB[(Profile Database)]
+
+    Auth --> JWT[JWT Service]
+    Auth --> OAuth[OAuth Provider]
+
+Shall I also generate a data flow diagram?"
+
+```
+
+**3. Automatic Generation of TypeScript Interfaces**
+
+```text
+Claude: "I'll automatically generate TypeScript interfaces based on the design:
+
+Automatically generated TypeScript interfaces:
+
+// Domain entities
+interface User {
+  readonly id: UserId;
+  readonly email: Email;
+  readonly profile: UserProfile;
+  readonly auth: AuthSettings;
+  readonly permissions: Permission[];
+  readonly createdAt: Date;
+  readonly updatedAt: Date;
+}
+
+interface UserProfile {
+  readonly displayName: string;
+  readonly avatar: AvatarUrl;
+  readonly preferences: UserPreferences;
+}
+
+interface AuthSettings {
+  readonly passwordHash: PasswordHash;
+  readonly mfaEnabled: boolean;
+  readonly lastLoginAt: Date;
+  readonly failedAttempts: number;
+}
+
+// Use cases
+interface UserRepository {
+  findById(id: UserId): Promise<User | null>;
+  findByEmail(email: Email): Promise<User | null>;
+  save(user: User): Promise<void>;
+}
+
+interface AuthenticationService {
+  authenticate(credentials: LoginCredentials): Promise<AuthResult>;
+  refreshToken(token: RefreshToken): Promise<AccessToken>;
+}
+
+Shall we proceed with this interface design?"
+
+```
+
+**4. Phase 2 Completion and Approval**
+
+```text
+
+Claude: "The Design Phase is complete.
+May I generate design.md?"
+→ "Proceed" → design.md generation
+
+```
+
+#### Phase 3: Implementation Planning & Discussion
+
+**1. Automatic Application of Best Practices (Kiro Style)**
+
+```text
+
+Claude: "I've generated an implementation plan with automatic application of Kiro's best practices:
+
+Automatically generated implementation strategy:
+
+1. Security-first development
+   - Automatic incorporation of OWASP Top 10 countermeasures
+   - Automatic implementation of encryption and hashing
+   - Automatic generation of security tests
+
+2. Enforcement of clean architecture
+   - Automatic implementation of layer separation
+   - Automatic application of dependency inversion
+   - Enforcement of testable design
+
+3. Performance optimization
+   - Automatic implementation of caching strategy
+   - Database optimization
+   - Utilization of asynchronous processing
+
+Shall we proceed with this approach?"
+
+```
+
+**2. Automatic Setting of Quality Checkpoints**
+
+```text
+
+Claude: "I've automatically set quality checkpoints for each implementation phase:
+
+Automatic quality assurance process:
+
+Phase 3a: Backend implementation
+
+- [ ] Security scan (SAST/DAST)
+- [ ] API specification test (OpenAPI compliant)
+- [ ] Performance test (load/response)
+- [ ] Vulnerability scan (dependencies/CVE)
+
+Phase 3b: Frontend implementation
+
+- [ ] Accessibility test (WCAG 2.1 AA)
+- [ ] Browser compatibility test
+- [ ] Responsive design verification
+- [ ] Security header confirmation
+
+Phase 3c: Integration/Deployment
+
+- [ ] E2E test suite
+- [ ] CI/CD pipeline setup
+- [ ] Monitoring/logging setup
+- [ ] Production environment security audit
+
+All will be executed automatically. Are there any additional quality standards?"
+
+```
+
+**3. Automatic Analysis of Dependencies and Risk Mitigation**
+
+```text
+
+Claude: "I've automatically analyzed the implementation order and risk mitigation measures:
+
+Optimized implementation order:
+
+Week 1: Infrastructure and security foundation
+
+- Database design and schema creation
+- Authentication foundation (JWT + session management)
+- Security middleware implementation
+- Basic API endpoints
+
+Week 2: Core functionality implementation
+
+- User management functionality
+- Profile management functionality
+- Permission management system
+- Validation and error handling
+
+Week 3: Advanced features and optimization
+
+- Multi-factor authentication implementation
+- Audit log functionality
+- Performance optimization
+- Frontend integration
+
+Automatically detected risk mitigation measures:
+
+- Multi-factor authentication: Gradual rollout (SMS→app authentication)
+- Session management: Redis cluster configuration
+- High traffic: Rate limiting + CDN utilization
+- Data consistency: Enhanced transaction management
+
+Is this plan acceptable?"
+
+```
+
+**4. Phase 3 Completion and Approval**
+
+```text
+
+Claude: "The Implementation Planning Phase is complete.
+May I generate tasks.md?"
+→ "Proceed" → tasks.md generation
+
+```
+
+### Kiro-Specific Features
+
+**EARS Notation (Easy Approach to Requirements Syntax)**
+
+```text
+# Kiro Standard EARS Notation Patterns
+
+WHEN [situation/trigger]
+GIVEN [precondition]
+THEN [system behavior]
+AND [additional behavior]
+
+WHILE [state/process]
+THE SYSTEM SHALL [mandatory behavior]
+AND [related behavior]
+
+WHERE [function/component]
+IS [condition/state]
+THE SYSTEM SHALL [corresponding behavior]
+```
+
+**Automatic Generation Features**
+
+- **Mermaid diagrams**: Automatic generation of architecture and data flow diagrams
+- **TypeScript interfaces**: Automatic creation of type definitions based on design
+- **Best practices**: Automatic incorporation of security and performance measures
+- **Quality checkpoints**: Automatic setting of phase-specific quality standards
+
+**Hooks Integration**
+
+- Automatic quality checks on file save
+- Automatic application of code standards
+- Automatic execution of security scans
+- Automatic verification of OWASP Top 10 countermeasures
+
+**Prototype→Production Quality Assurance**
+
+- Consistent design through structured approach
+- Enforcement of security-first development
+- Automatic application of scalable architecture
+- Integration of continuous quality management
+
+### Notes
+
+**Scope of Application**
+
+- Spec Mode is optimized for feature implementation
+- Use normal implementation format for simple fixes or small changes
+- Recommended for new feature development or complex feature modifications
+
+**Quality Assurance**
+
+- Clarification of completion criteria at each stage
+- Design review before implementation
+- Comprehensive quality standards including testing and accessibility
+
+**Operational Notes**
+
+- Resolve requirement ambiguities before design phase
+- Generate implementation tasks after design completion
+- Emphasize approval process at each stage
+
+### Trigger Phrases and Controls
+
+#### Step-by-Step Workflow Control
+
+**Start Triggers**
+
+- "Create a spec for [feature name]"
+- "I want to develop [feature name] using spec-driven development"
+- "Design [feature name] from specifications"
+
+**Phase Progress Control**
+
+- **"Proceed"**: Complete current phase, generate file, move to next phase
+- **"Revise"**: Adjust or improve content within current phase
+- **"Restart"**: Restart current phase from beginning
+- **"Explain in detail"**: Provide more detailed explanations or options
+- **"Skip"**: Skip current phase and move to next (not recommended)
+
+**File Generation Timing**
+
+```text
+Phase 1 completion → "Proceed" → requirements.md generation
+Phase 2 completion → "Proceed" → design.md generation
+Phase 3 completion → "Proceed" → tasks.md generation
+```
+
+### Execution Example (Step-by-Step Flow)
+
+```bash
+# Usage example
+User: "Create a spec for a user management system"
+
+# Phase 1: Requirements Discovery
+Claude: [Begins requirement confirmation and discussion]
+User: [Responds, discusses, makes revisions]
+Claude: "The Requirements Phase is complete. May I proceed?"
+User: "Proceed"
+→ requirements.md generation
+
+# Phase 2: Design Exploration
+Claude: [Begins design proposal and discussion]
+User: [Discusses technology selection and architecture]
+Claude: "The Design Phase is complete. May I proceed?"
+User: "Proceed"
+→ design.md generation
+
+# Phase 3: Implementation Planning
+Claude: [Begins implementation plan discussion]
+User: [Discusses priorities, risks, and effort]
+Claude: "The Implementation Phase is complete. May I proceed?"
+User: "Proceed"
+→ tasks.md generation
+
+# Completion
+Claude: "Spec-driven development preparation is complete. You can begin implementation."
+```
+
+### Differences from /plan
+
+| Feature                | /plan                          | /spec                                                                    |
+| ---------------------- | ------------------------------ | ------------------------------------------------------------------------ |
+| Target                 | General implementation plan    | Feature specification-driven development                                 |
+| Output format          | Single plan document           | 3 independent files (requirements.md, design.md, tasks.md)               |
+| Requirement definition | Basic requirement organization | Detailed acceptance criteria using EARS notation                         |
+| Design                 | Technology selection focused   | Codebase analysis-based                                                  |
+| Implementation         | General task decomposition     | Dependency-aware sequence                                                |
+| Quality assurance      | Basic test strategy            | Comprehensive quality requirements (testing, accessibility, performance) |
+| Synchronization        | Static plan                    | Dynamic spec updates                                                     |
+
+### Recommended Use Cases
+
+**Recommended for spec use**
+
+- New feature development
+- Complex feature modifications
+- API design
+- Database design
+- UI/UX implementation
+
+**Recommended for plan use**
+
+- System-wide design
+- Infrastructure construction
+- Refactoring
+- Technology selection
+- Architecture changes