commit content

2026-03-06 02:02:59 +08:00
parent 99b07682e7
commit c28ada5050
733 changed files with 128794 additions and 248 deletions
--- a/.claude/skills/technical-design-doc-creator/README.md
+++ b/.claude/skills/technical-design-doc-creator/README.md
@@ -0,0 +1,411 @@
+# Technical Design Doc Creator
+
+A skill for AI coding agents that helps create comprehensive Technical Design Documents (TDDs) following industry standards.
+
+## What It Does
+
+This skill guides AI agents to create well-structured Technical Design Documents that include:
+
+- **Mandatory sections**: Context, Problem Statement, Scope, Technical Solution, Risks, Implementation Plan
+- **Critical sections**: Security (for payments/auth), Monitoring, Rollback Plan, Testing Strategy
+- **Optional sections**: Success Metrics, Glossary, Alternatives Considered, Dependencies, Performance Requirements, and more
+
+The skill automatically adapts to:
+
+- **Project size**: Small (< 1 week), Medium (1-4 weeks), Large (> 1 month)
+- **Project type**: Integration, Feature, Refactor, Infrastructure, Payment, Auth, Data migration
+- **User's language**: Automatically generates TDD in Portuguese, English, or Spanish based on your request
+
+## How to Use
+
+### Basic Usage
+
+Simply ask the AI agent to create a TDD:
+
+**English:**
+
+```
+Create a TDD for Stripe payment integration
+```
+
+**Portuguese:**
+
+```
+Crie um TDD para integração com Stripe
+```
+
+**Spanish:**
+
+```
+Crea un TDD para integración con Stripe
+```
+
+### Interactive Workflow
+
+The skill will guide you through an interactive process:
+
+1. **Initial Questions**: Project name, size, type, and context clarity
+2. **Mandatory Information**: Problem statement, scope, technical approach
+3. **Critical Sections**: Security, monitoring, rollback (if applicable)
+4. **Optional Sections**: Success metrics, glossary, alternatives, etc.
+
+### Examples
+
+#### Example 1: Payment Integration
+
+**Your Request:**
+
+```
+Create a TDD for integrating Stripe payments into our subscription system
+```
+
+**What Happens:**
+
+1. Agent asks about project size and type
+2. Agent requests: problem statement, scope, technical approach
+3. Agent identifies this is a payment system → **Security section becomes MANDATORY**
+4. Agent asks for: security requirements, monitoring metrics, rollback plan
+5. Agent generates comprehensive TDD with all required sections
+
+**Result:** A complete TDD with:
+
+- Context and problem statement
+- In-scope/out-of-scope features
+- Architecture diagram
+- API contracts
+- Security considerations (PCI DSS compliance, encryption, PII handling)
+- Testing strategy
+- Monitoring & observability
+- Rollback plan
+- Implementation timeline
+
+#### Example 2: Simple Feature
+
+**Your Request:**
+
+```
+Write a design doc for adding user profile pictures
+```
+
+**What Happens:**
+
+1. Agent identifies this as a small feature
+2. Agent asks for basic information
+3. Agent generates streamlined TDD with essential sections only
+
+**Result:** A focused TDD with:
+
+- Context
+- Problem statement
+- Scope (in/out)
+- Technical solution (file upload, storage, API endpoints)
+- Risks
+- Implementation plan
+- Testing strategy
+
+#### Example 3: Migration Project
+
+**Your Request:**
+
+```
+Crie um TDD para migração do banco de dados PostgreSQL para MongoDB
+```
+
+**What Happens:**
+
+1. Agent detects Portuguese language → generates TDD in Portuguese
+2. Agent identifies this as a migration project
+3. Agent requests: migration strategy, data mapping, rollback plan
+4. Agent offers migration plan section
+
+**Result:** A TDD in Portuguese with:
+
+- Contexto (Context)
+- Definição do Problema (Problem Statement)
+- Escopo (Scope)
+- Solução Técnica (Technical Solution)
+- Plano de Migração (Migration Plan)
+- Plano de Rollback (Rollback Plan)
+- Estratégia de Testes (Testing Strategy)
+
+## What to Expect
+
+### The Agent Will Ask Questions
+
+The skill is designed to gather complete information. Expect questions like:
+
+**For Problem Statement:**
+
+- What problem are we solving?
+- Why is this important now?
+- What happens if we don't solve it?
+
+**For Scope:**
+
+- What WILL be delivered in V1?
+- What will NOT be included (out of scope)?
+
+**For Technical Approach:**
+
+- What are the main components?
+- How does data flow through the system?
+- What APIs will be created/modified?
+
+**For Payment/Auth Projects:**
+
+- How will you handle authentication?
+- What encryption will be used?
+- What PII is collected?
+- Any compliance requirements (GDPR, PCI DSS)?
+
+**For Production Systems:**
+
+- How will you monitor this?
+- What metrics matter?
+- How will you rollback if something fails?
+
+### The Generated TDD
+
+The TDD will include:
+
+1. **Header & Metadata**: Tech Lead, Team, Epic link, Status, Dates
+2. **Context**: Background, domain, stakeholders
+3. **Problem Statement**: Specific problems with quantified impact
+4. **Scope**: Clear in-scope and out-of-scope items
+5. **Technical Solution**: Architecture, data flow, APIs, database changes
+6. **Risks**: Risk matrix with impact, probability, and mitigation
+7. **Implementation Plan**: Phased breakdown with estimates
+8. **Security** (if applicable): Authentication, encryption, compliance
+9. **Testing Strategy**: Unit, integration, E2E test plans
+10. **Monitoring & Observability**: Metrics, alerts, dashboards
+11. **Rollback Plan**: Triggers and steps for reverting changes
+12. **Optional sections**: Success metrics, glossary, alternatives, dependencies, etc.
+
+## Tips for Best Results
+
+### 1. Provide Context Early
+
+Instead of:
+
+```
+Create a TDD for Stripe
+```
+
+Try:
+
+```
+Create a TDD for integrating Stripe payments. We need to support subscriptions,
+handle webhooks, and comply with PCI DSS. This is for our SaaS product.
+```
+
+### 2. Be Specific About Scope
+
+The agent will ask, but you can provide upfront:
+
+```
+Create a TDD for user authentication. In scope: email/password, JWT tokens,
+password reset. Out of scope: OAuth, 2FA, social login (those are V2).
+```
+
+### 3. Mention Project Size
+
+```
+Create a TDD for the database migration project. This is a large project
+(expected 2 months).
+```
+
+### 4. Specify Critical Requirements
+
+For payment/auth systems, mention security requirements:
+
+```
+Create a TDD for Stripe integration. We need PCI DSS compliance, webhook
+signature validation, and encrypted storage of payment method tokens.
+```
+
+### 5. Use Your Language
+
+The skill automatically detects your language. Just write naturally:
+
+- **English**: "Create a TDD for..."
+- **Portuguese**: "Crie um TDD para..."
+- **Spanish**: "Crea un TDD para..."
+
+## Language Support
+
+The skill supports multiple languages:
+
+| Language   | Example Trigger                           |
+| ---------- | ----------------------------------------- |
+| English    | "Create a TDD for Stripe integration"     |
+| Portuguese | "Crie um TDD para integração com Stripe"  |
+| Spanish    | "Crea un TDD para integración con Stripe" |
+
+All section headers and content are automatically translated to match your language.
+
+## Integration with Other Skills
+
+### Confluence Publishing
+
+After generating a TDD, the agent will offer to publish it to Confluence:
+
+```
+Would you like me to publish this TDD to Confluence?
+- I can create a new page in your space
+- Or update an existing page
+```
+
+### Jira Integration
+
+The TDD includes a metadata section for Epic/Ticket links. You can manually add these or ask the agent to help create Jira tickets.
+
+## What Makes This Skill Different
+
+### 1. Industry Standards
+
+Follows patterns from:
+
+- Google Design Docs
+- Amazon PR-FAQ (Working Backwards)
+- RFC Pattern
+- ADR (Architecture Decision Records)
+- SRE Book (Monitoring, Rollback, SLOs)
+- PCI DSS & OWASP (Security)
+
+### 2. Architecture-Focused, Not Implementation
+
+The TDD documents **decisions and contracts**, not code:
+
+✅ **Includes**: API contracts, data schemas, architecture diagrams, strategies
+❌ **Avoids**: CLI commands, code snippets, framework-specific implementation
+
+### 3. Adaptive to Project Size
+
+- **Small projects**: Essential sections only (7-9 sections)
+- **Medium projects**: Mandatory + critical sections (11-13 sections)
+- **Large projects**: All sections (up to 20 sections)
+
+### 4. Mandatory Sections Enforcement
+
+The agent will **insist** on completing mandatory sections before finalizing the TDD. You can't skip:
+
+- Problem Statement
+- Scope
+- Technical Solution
+- Risks
+- Implementation Plan
+
+### 5. Critical Sections for Specific Project Types
+
+- **Payment/Auth**: Security section is MANDATORY
+- **Production**: Monitoring and Rollback are MANDATORY
+- **Integration**: Dependencies and Security are highly recommended
+
+## Common Use Cases
+
+### ✅ Good Use Cases
+
+- New feature development
+- External API integration
+- System migration or refactoring
+- Infrastructure changes
+- Payment/billing system design
+- Authentication/authorization system
+- Data processing pipelines
+
+### ❌ Not Ideal For
+
+- Bug fixes (too small)
+- Code refactoring without architectural changes
+- Documentation updates
+- Simple configuration changes
+
+## Example Output Structure
+
+```
+# TDD - [Project Name]
+
+## Metadata
+- Tech Lead: @Name
+- Team: Name1, Name2
+- Status: Draft
+- Created: 2026-02-04
+
+## Context
+[Background and domain description]
+
+## Problem Statement & Motivation
+[Specific problems with impact]
+
+## Scope
+### ✅ In Scope
+[What will be delivered]
+
+### ❌ Out of Scope
+[What won't be included]
+
+## Technical Solution
+[Architecture, APIs, data flow, database changes]
+
+## Risks
+[Risk matrix with mitigation]
+
+## Implementation Plan
+[Phased breakdown with estimates]
+
+## Security Considerations
+[Authentication, encryption, compliance]
+
+## Testing Strategy
+[Unit, integration, E2E tests]
+
+## Monitoring & Observability
+[Metrics, alerts, dashboards]
+
+## Rollback Plan
+[Triggers and steps]
+
+[Additional optional sections...]
+```
+
+## Troubleshooting
+
+### The Agent Keeps Asking Questions
+
+**This is normal!** The skill is designed to gather complete information. Answer the questions to get a comprehensive TDD.
+
+### I Want to Skip a Section
+
+Mandatory sections cannot be skipped. For optional sections, you can say:
+
+```
+Skip the Alternatives Considered section for now
+```
+
+### The TDD is Too Detailed
+
+For small projects, specify the size:
+
+```
+This is a small project (< 1 week), keep it simple
+```
+
+### The TDD is Missing Something
+
+Tell the agent what's missing:
+
+```
+Add a section on performance requirements
+```
+
+## Next Steps After Creating a TDD
+
+1. **Review**: Check all sections are complete
+2. **Share**: Get feedback from team members
+3. **Approve**: Get sign-off from stakeholders
+4. **Implement**: Use the TDD as a guide during development
+5. **Update**: Keep the TDD updated as the project evolves
+
+## Support
+
+For issues or questions about this skill, refer to the main [agent-skills repository](https://github.com/tech-leads-club/agent-skills).