universal-dev-standards 3.5.1-beta.1 → 3.5.1-beta.11

package/bundled/skills/claude-code/git-workflow-guide/git-workflow.md

@@ -0,0 +1,313 @@
+# Git Workflow Strategies
+
+> **Language**: English | [繁體中文](../../../locales/zh-TW/skills/claude-code/git-workflow-guide/git-workflow.md)
+
+**Version**: 1.0.0
+**Last Updated**: 2025-12-24
+**Applicability**: Claude Code Skills
+
+---
+
+## Purpose
+
+This document provides detailed guidelines for Git workflow strategies (GitFlow, GitHub Flow, Trunk-Based).
+
+---
+
+## Strategy Selection Matrix
+
+| Factor | GitFlow | GitHub Flow | Trunk-Based |
+|--------|---------|-------------|-------------|
+| **Release frequency** | Monthly+ | Weekly | Multiple/day |
+| **Team size** | Large (10+) | Medium (5-15) | Small-Medium (3-10) |
+| **CI/CD maturity** | Basic | Intermediate | Advanced |
+| **Feature flags** | Optional | Optional | Required |
+| **Complexity** | High | Low | Medium |
+
+---
+
+## Strategy A: GitFlow
+
+**Best For**: Scheduled releases, multiple production versions, large teams
+
+### Branch Structure
+
+```
+main          ─●────────●─────────●── (Production: v1.0, v2.0)
+               ╱          ╲         ╲
+develop   ────●────●──────●─────────●── (Development)
+             ╱      ╲      ╲
+feature/*  ─●────────●      ╲  (Features)
+                              ╲
+release/*                      ●───● (Release prep)
+                                   ╱
+hotfix/*                      ────● (Emergency fixes)
+```
+
+### Branch Types
+
+| Branch | Purpose | Base | Merge To | Lifetime |
+|--------|---------|------|----------|----------|
+| `main` | Production code | - | - | Permanent |
+| `develop` | Integration | - | - | Permanent |
+| `feature/*` | New features | `develop` | `develop` | Temporary |
+| `release/*` | Release prep | `develop` | `main` + `develop` | Temporary |
+| `hotfix/*` | Urgent fixes | `main` | `main` + `develop` | Temporary |
+
+### Feature Development Flow
+
+```bash
+# Create from develop
+git checkout develop
+git pull origin develop
+git checkout -b feature/oauth-login
+
+# Work and commit
+git add .
+git commit -m "feat(auth): add OAuth2 login"
+git push -u origin feature/oauth-login
+
+# After PR approval, merge to develop
+git checkout develop
+git merge --no-ff feature/oauth-login
+git push origin develop
+
+# Delete feature branch
+git branch -d feature/oauth-login
+git push origin --delete feature/oauth-login
+```
+
+### Release Flow
+
+```bash
+# Create release branch
+git checkout develop
+git checkout -b release/v1.2.0
+
+# Prepare release (bump version, update changelog)
+npm version 1.2.0
+git add package.json CHANGELOG.md
+git commit -m "chore(release): prepare v1.2.0"
+
+# Merge to main
+git checkout main
+git merge --no-ff release/v1.2.0
+git tag -a v1.2.0 -m "Release v1.2.0"
+git push origin main --tags
+
+# Merge back to develop
+git checkout develop
+git merge --no-ff release/v1.2.0
+git push origin develop
+
+# Delete release branch
+git branch -d release/v1.2.0
+```
+
+### Hotfix Flow
+
+```bash
+# Create from main
+git checkout main
+git checkout -b hotfix/critical-fix
+
+# Fix and commit
+git add .
+git commit -m "fix(security): patch vulnerability"
+
+# Merge to main
+git checkout main
+git merge --no-ff hotfix/critical-fix
+git tag -a v1.2.1 -m "Hotfix v1.2.1"
+git push origin main --tags
+
+# Merge to develop
+git checkout develop
+git merge --no-ff hotfix/critical-fix
+git push origin develop
+```
+
+---
+
+## Strategy B: GitHub Flow
+
+**Best For**: Continuous deployment, web apps, small-medium teams
+
+### Branch Structure
+
+```
+main      ────●─────────●──────●── (Always deployable)
+               ╲         ╱      ╱
+feature/*       ●───●───●      ╱
+                              ╱
+bugfix/*                 ────●
+```
+
+### Branch Types
+
+| Branch | Purpose | Base | Merge To | Lifetime |
+|--------|---------|------|----------|----------|
+| `main` | Production | - | - | Permanent |
+| `feature/*` | Features | `main` | `main` | Temporary |
+| `bugfix/*` | Bug fixes | `main` | `main` | Temporary |
+
+### Workflow
+
+```bash
+# 1. Create from main
+git checkout main
+git pull origin main
+git checkout -b feature/user-profile
+
+# 2. Work and push
+git add .
+git commit -m "feat(profile): add avatar"
+git push -u origin feature/user-profile
+
+# 3. Open PR to main (via GitHub/GitLab UI)
+
+# 4. After approval and CI pass, merge (squash recommended)
+
+# 5. Deploy main to production
+
+# 6. Delete branch (auto or manual)
+```
+
+### Key Principles
+
+1. `main` is **always deployable**
+2. Branch from `main`
+3. Merge to `main` via PR
+4. Deploy immediately after merge
+
+---
+
+## Strategy C: Trunk-Based Development
+
+**Best For**: Mature CI/CD, high-trust teams, frequent integration
+
+### Branch Structure
+
+```
+main  ────●─●─●─●─●─●─●──► (Single trunk)
+           ╲│╱ ╲│╱ ╲│╱
+feature/*   ●   ●   ●  (Very short-lived, ≤2 days)
+```
+
+### Branch Types
+
+| Branch | Purpose | Base | Merge To | Lifetime |
+|--------|---------|------|----------|----------|
+| `main` | Trunk | - | - | Permanent |
+| `feature/*` | Small changes | `main` | `main` | ≤2 days |
+
+### Workflow
+
+```bash
+# 1. Create short-lived branch
+git checkout main
+git pull origin main
+git checkout -b feature/add-validation
+
+# 2. Small, atomic change
+git add .
+git commit -m "feat(validation): add email check"
+git push -u origin feature/add-validation
+
+# 3. Quick PR and merge (same day)
+git checkout main
+git pull origin main
+git rebase main feature/add-validation
+git checkout main
+git merge --ff-only feature/add-validation
+git push origin main
+
+# 4. Delete immediately
+git branch -d feature/add-validation
+```
+
+### Key Principles
+
+1. Integrate **multiple times per day**
+2. Branches live **≤2 days**
+3. Use **feature flags** for incomplete features
+4. **Automate everything**
+
+---
+
+## Merge Strategies Comparison
+
+### Merge Commit (`--no-ff`)
+
+```bash
+git merge --no-ff feature/user-auth
+```
+
+**Pros**: Complete history, easy to revert features
+**Cons**: Complex git log
+**Best For**: GitFlow, long-lived features
+
+### Squash Merge
+
+```bash
+git merge --squash feature/user-auth
+git commit -m "feat(auth): add user authentication"
+```
+
+**Pros**: Clean history, one commit per feature
+**Cons**: Loses detailed history
+**Best For**: GitHub Flow, feature PRs
+
+### Rebase + Fast-Forward
+
+```bash
+git rebase main feature/user-auth
+git checkout main
+git merge --ff-only feature/user-auth
+```
+
+**Pros**: Linear history, preserves commits
+**Cons**: Rewrites history
+**Best For**: Trunk-Based, short-lived branches
+
+---
+
+## Protected Branch Recommendations
+
+### For `main`
+
+- ✅ Require pull request reviews (1-2)
+- ✅ Require status checks (CI, tests, lint)
+- ✅ Require up-to-date branches
+- ❌ No force pushes
+- ❌ No deletions
+
+### For `develop` (GitFlow)
+
+- ✅ Require pull request reviews (1)
+- ✅ Require status checks
+- ❌ No force pushes
+
+---
+
+## Related Standards
+
+- [Git Workflow](../../../core/git-workflow.md)
+- [Branch Naming Reference](./branch-naming.md)
+- [Commit Message Guide](../../../core/commit-message-guide.md)
+
+---
+
+## Version History
+
+| Version | Date | Changes |
+|---------|------|---------|
+| 1.0.0 | 2025-12-24 | Added: Standard sections (Purpose, Related Standards, Version History, License) |
+
+---
+
+## License
+
+This document is released under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/).
+
+**Source**: [universal-dev-standards](https://github.com/AsiaOstrich/universal-dev-standards)

package/bundled/skills/claude-code/logging-guide/SKILL.md

@@ -0,0 +1,280 @@
+---
+name: logging-guide
+description: |
+  Implement structured logging with proper log levels and sensitive data handling.
+  Use when: adding logging, debugging, setting up observability.
+  Keywords: logging, log level, structured logging, observability, 日誌, 記錄, 結構化日誌.
+---
+
+# Logging Guide
+
+> **Language**: English | [繁體中文](../../../locales/zh-TW/skills/claude-code/logging-guide/SKILL.md)
+
+**Version**: 1.0.0
+**Last Updated**: 2025-12-30
+**Applicability**: Claude Code Skills
+
+---
+
+## Purpose
+
+This skill helps implement consistent, structured, and actionable application logs across all environments.
+
+## Quick Reference
+
+### Log Levels
+
+| Level | Code | When to Use | Production |
+|-------|------|-------------|------------|
+| **TRACE** | 10 | Very detailed debugging info | Off |
+| **DEBUG** | 20 | Detailed debugging info | Off |
+| **INFO** | 30 | Normal operation events | On |
+| **WARN** | 40 | Potential issues, recoverable | On |
+| **ERROR** | 50 | Errors that need attention | On |
+| **FATAL** | 60 | Critical failures | On |
+
+### Level Selection Decision Tree
+
+```
+Is it debugging only?        → DEBUG (off in prod)
+Normal operation completed?  → INFO
+Something unexpected but OK? → WARN
+Operation failed?            → ERROR
+App cannot continue?         → FATAL
+```
+
+### When to Use Each Level
+
+| Level | Examples |
+|-------|----------|
+| **TRACE** | Function entry/exit, loop iterations, variable values |
+| **DEBUG** | State changes, configuration values, query parameters |
+| **INFO** | App startup/shutdown, user actions, scheduled tasks |
+| **WARN** | Deprecated API, retry attempts, resource approaching limits |
+| **ERROR** | Failed operations, caught exceptions, integration failures |
+| **FATAL** | Unrecoverable errors, startup failures, lost critical resources |
+
+## Structured Logging
+
+### Required Fields
+
+```json
+{
+  "timestamp": "2025-01-15T10:30:00.123Z",
+  "level": "INFO",
+  "message": "User login successful",
+  "service": "auth-service",
+  "environment": "production"
+}
+```
+
+### Recommended Fields
+
+```json
+{
+  "timestamp": "2025-01-15T10:30:00.123Z",
+  "level": "INFO",
+  "message": "User login successful",
+  "service": "auth-service",
+  "environment": "production",
+  "trace_id": "abc123",
+  "span_id": "def456",
+  "user_id": "usr_12345",
+  "request_id": "req_67890",
+  "duration_ms": 150,
+  "http_method": "POST",
+  "http_path": "/api/v1/login",
+  "http_status": 200
+}
+```
+
+### Field Naming Conventions
+
+Use `snake_case` and prefix with domain:
+
+| Domain | Common Fields |
+|--------|---------------|
+| HTTP | http_method, http_path, http_status, http_duration_ms |
+| Database | db_query_type, db_table, db_duration_ms, db_rows_affected |
+| Queue | queue_name, queue_message_id, queue_delay_ms |
+| User | user_id, user_role, user_action |
+| Request | request_id, trace_id, span_id |
+
+## Detailed Guidelines
+
+For complete standards, see:
+- [Logging Standards](../../../core/logging-standards.md)
+
+### AI-Optimized Format (Token-Efficient)
+
+For AI assistants, use the YAML format files for reduced token usage:
+- Base standard: `ai/standards/logging.ai.yaml`
+
+## Sensitive Data Handling
+
+### Never Log
+
+- Passwords or secrets
+- API keys or tokens
+- Credit card numbers
+- Social security numbers
+- Full authentication tokens
+
+### Mask or Redact
+
+```javascript
+// Bad
+logger.info('Login attempt', { password: userPassword });
+
+// Good
+logger.info('Login attempt', { password: '***REDACTED***' });
+
+// Good - mask partial
+logger.info('Card processed', { last_four: '4242' });
+```
+
+### PII Handling
+
+- Log user IDs, not email addresses when possible
+- Use hashed identifiers for sensitive lookups
+- Configure data retention policies
+
+## Error Logging
+
+### Required Error Fields
+
+```json
+{
+  "level": "ERROR",
+  "message": "Database connection failed",
+  "error_type": "ConnectionError",
+  "error_message": "Connection refused",
+  "error_code": "ECONNREFUSED",
+  "stack": "Error: Connection refused\n    at connect (/app/db.js:45:11)..."
+}
+```
+
+### Error Context
+
+Always include:
+- What operation was attempted
+- Relevant identifiers (user_id, request_id)
+- Input parameters (sanitized)
+- Retry count if applicable
+
+```javascript
+logger.error('Failed to process order', {
+  error_type: err.name,
+  error_message: err.message,
+  order_id: orderId,
+  user_id: userId,
+  retry_count: 2,
+  stack: err.stack
+});
+```
+
+## Log Format
+
+### JSON Format (Production)
+
+```json
+{"timestamp":"2025-01-15T10:30:00.123Z","level":"INFO","message":"Request completed","request_id":"req_123","duration_ms":45}
+```
+
+### Human-Readable (Development)
+
+```
+2025-01-15T10:30:00.123Z [INFO] Request completed request_id=req_123 duration_ms=45
+```
+
+## Performance Considerations
+
+### Log Volume by Environment
+
+| Environment | Level | Strategy |
+|-------------|-------|----------|
+| Development | DEBUG | All logs |
+| Staging | INFO | Most logs |
+| Production | INFO | Sampling for high-volume |
+
+### High-Volume Endpoints
+
+- Use sampling (log 1 in 100)
+- Aggregate metrics instead of individual logs
+- Use separate log streams
+
+## Checklist
+
+### Required Fields
+
+- [ ] timestamp (ISO 8601)
+- [ ] level
+- [ ] message
+- [ ] service name
+- [ ] request_id or trace_id
+
+### Security
+
+- [ ] No passwords or secrets
+- [ ] No full tokens
+- [ ] PII masked or hashed
+- [ ] Credit cards never logged
+- [ ] Retention policies configured
+
+---
+
+## Configuration Detection
+
+This skill supports project-specific configuration.
+
+### Detection Order
+
+1. Check for existing logging library configuration
+2. Check `CONTRIBUTING.md` for logging guidelines
+3. If not found, **default to structured JSON logging**
+
+### First-Time Setup
+
+If no logging standard found:
+
+1. Suggest: "This project hasn't configured logging standards. Would you like to set up structured logging?"
+2. Suggest documenting in `CONTRIBUTING.md`:
+
+```markdown
+## Logging Standards
+
+### Log Levels
+- DEBUG: Development only, detailed diagnostic info
+- INFO: Normal operations (startup, user actions, tasks)
+- WARN: Unexpected but recoverable situations
+- ERROR: Failures that need investigation
+
+### Required Fields
+All logs must include: timestamp, level, message, service, request_id
+
+### Sensitive Data
+Never log: passwords, tokens, credit cards, SSN
+```
+
+---
+
+## Related Standards
+
+- [Logging Standards](../../../core/logging-standards.md)
+- [Error Code Standards](../../../core/error-code-standards.md)
+
+---
+
+## Version History
+
+| Version | Date | Changes |
+|---------|------|---------|
+| 1.0.0 | 2025-12-30 | Initial release |
+
+---
+
+## License
+
+This skill is released under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/).
+
+**Source**: [universal-dev-standards](https://github.com/AsiaOstrich/universal-dev-standards)