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

package/bundled/skills/claude-code/documentation-guide/readme-template.md

@@ -0,0 +1,404 @@
+# README Template & Best Practices
+
+> **Language**: English | [繁體中文](../../../../locales/zh-TW/skills/claude-code/documentation-guide/readme-template.md)
+
+**Version**: 1.0.0
+**Last Updated**: 2025-12-24
+**Applicability**: Claude Code Skills
+
+---
+
+## Purpose
+
+This document provides templates and best practices for writing README files.
+
+---
+
+## README Sections Reference
+
+### Essential Sections (Minimum)
+
+| Section | Purpose | Required |
+|---------|---------|:--------:|
+| Project Name | Identity | ✅ |
+| Description | What it does | ✅ |
+| Installation | How to install | ✅ |
+| Usage | How to use | ✅ |
+| License | Legal terms | ✅ |
+
+### Recommended Sections
+
+| Section | Purpose | When to Include |
+|---------|---------|-----------------|
+| Badges | Status indicators | CI, npm, coverage |
+| Features | Key capabilities | Multi-feature projects |
+| Quick Start | Fast onboarding | Complex setup |
+| API Reference | Technical docs | Libraries/APIs |
+| Configuration | Setup options | Configurable tools |
+| Contributing | How to help | Open source |
+| Changelog | Version history | Versioned projects |
+| FAQ | Common questions | User-facing projects |
+| Acknowledgments | Credits | Community projects |
+
+---
+
+## README Templates
+
+### Minimal README
+
+```markdown
+# Project Name
+
+Brief description of what this project does.
+
+## Installation
+
+```bash
+npm install project-name
+```
+
+## Usage
+
+```javascript
+const lib = require('project-name');
+lib.doSomething();
+```
+
+## License
+
+MIT
+```
+
+### Standard README
+
+```markdown
+# Project Name
+
+Brief description of what this project does.
+
+## Features
+
+- Feature 1
+- Feature 2
+- Feature 3
+
+## Installation
+
+```bash
+npm install project-name
+```
+
+## Usage
+
+```javascript
+const { feature } = require('project-name');
+
+// Basic usage
+feature.doSomething();
+
+// With options
+feature.doSomething({ option: 'value' });
+```
+
+## Documentation
+
+See [docs/](docs/) for detailed documentation.
+
+## Contributing
+
+Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+MIT - see [LICENSE](LICENSE)
+```
+
+### Full README
+
+```markdown
+# Project Name
+
+[![CI Status](https://github.com/org/repo/actions/workflows/ci.yml/badge.svg)](https://github.com/org/repo/actions)
+[![npm version](https://badge.fury.io/js/project-name.svg)](https://www.npmjs.com/package/project-name)
+[![Coverage](https://codecov.io/gh/org/repo/branch/main/graph/badge.svg)](https://codecov.io/gh/org/repo)
+
+Brief description of what this project does and why it exists.
+
+## Features
+
+- **Fast**: 10x faster than alternatives
+- **Simple**: Easy to learn API
+- **Extensible**: Plugin architecture
+- **Type-safe**: Full TypeScript support
+
+## Installation
+
+### npm
+
+```bash
+npm install project-name
+```
+
+### yarn
+
+```bash
+yarn add project-name
+```
+
+### pnpm
+
+```bash
+pnpm add project-name
+```
+
+## Quick Start
+
+```javascript
+const { Client } = require('project-name');
+
+const client = new Client({ apiKey: 'your-key' });
+
+const result = await client.doSomething();
+console.log(result);
+```
+
+## Documentation
+
+- [Getting Started](docs/getting-started.md)
+- [API Reference](docs/api-reference.md)
+- [Configuration](docs/configuration.md)
+- [Examples](examples/)
+
+## Configuration
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `apiKey` | string | - | Your API key |
+| `timeout` | number | 30000 | Request timeout in ms |
+| `retries` | number | 3 | Number of retry attempts |
+
+## Examples
+
+See the [examples/](examples/) directory for complete examples:
+
+- [Basic Usage](examples/basic/)
+- [Advanced Features](examples/advanced/)
+- [Integration](examples/integration/)
+
+## Contributing
+
+We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+### Development Setup
+
+```bash
+git clone https://github.com/org/repo.git
+cd repo
+npm install
+npm test
+```
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for version history.
+
+## FAQ
+
+### How do I do X?
+
+Answer to common question.
+
+### Why does Y happen?
+
+Explanation of behavior.
+
+## Support
+
+- [GitHub Issues](https://github.com/org/repo/issues)
+- [Documentation](https://docs.example.com)
+- [Discord](https://discord.gg/example)
+
+## Acknowledgments
+
+- [Library A](https://example.com) - Used for X
+- [Person B](https://github.com/person) - Initial idea
+
+## License
+
+MIT - see [LICENSE](LICENSE) for details.
+```
+
+---
+
+## Section Details
+
+### Project Name & Description
+
+**Good**:
+```markdown
+# FastJSON
+
+A blazing-fast JSON parser for Node.js with streaming support.
+```
+
+**Bad**:
+```markdown
+# my-project
+
+This is a project.
+```
+
+### Badges
+
+Common badges:
+```markdown
+[![CI](https://github.com/org/repo/actions/workflows/ci.yml/badge.svg)](https://github.com/org/repo/actions)
+[![npm](https://img.shields.io/npm/v/package.svg)](https://www.npmjs.com/package/package)
+[![Coverage](https://codecov.io/gh/org/repo/branch/main/graph/badge.svg)](https://codecov.io/gh/org/repo)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+```
+
+### Installation
+
+Include multiple package managers if applicable:
+
+```markdown
+## Installation
+
+### npm
+```bash
+npm install package-name
+```
+
+### yarn
+```bash
+yarn add package-name
+```
+```
+
+### Usage Examples
+
+**Good** - Shows real use case:
+```markdown
+## Usage
+
+```javascript
+const { parseJSON } = require('fast-json');
+
+// Parse a JSON file
+const data = parseJSON('./config.json');
+console.log(data.settings);
+
+// Parse with options
+const strictData = parseJSON('./data.json', { strict: true });
+```
+```
+
+**Bad** - Too abstract:
+```markdown
+## Usage
+
+```javascript
+const lib = require('lib');
+lib.func();
+```
+```
+
+### Configuration Table
+
+```markdown
+## Configuration
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `timeout` | number | 30000 | Request timeout (ms) |
+| `retries` | number | 3 | Max retry attempts |
+| `debug` | boolean | false | Enable debug logging |
+```
+
+---
+
+## Common Mistakes
+
+### ❌ Too Vague
+
+```markdown
+# Project
+
+A project for doing things.
+
+## Install
+
+Install it.
+
+## Use
+
+Use it.
+```
+
+### ❌ No Examples
+
+```markdown
+# JSON Parser
+
+A JSON parser library.
+
+See API docs for usage.
+```
+
+### ❌ Outdated Information
+
+```markdown
+## Requirements
+
+- Node.js 8+  ← Outdated
+- npm 5+      ← Outdated
+
+## Installation
+
+```bash
+npm install old-package-name  ← Wrong package name
+```
+```
+
+### ❌ Broken Links
+
+```markdown
+See [documentation](docs/old-path.md) for more info.  ← Link doesn't exist
+```
+
+---
+
+## README Quality Checklist
+
+- [ ] Project name clearly stated
+- [ ] Purpose explained in 1-2 sentences
+- [ ] Installation instructions complete
+- [ ] Usage example actually works
+- [ ] All links verified working
+- [ ] Version requirements accurate
+- [ ] License clearly stated
+- [ ] Contact/support info provided (for user-facing projects)
+
+---
+
+## Related Standards
+
+- [Documentation Structure Reference](./documentation-structure.md)
+- [Documentation Writing Standards](../../../core/documentation-writing-standards.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/error-code-guide/SKILL.md

@@ -0,0 +1,264 @@
+---
+name: error-code-guide
+description: |
+  Design consistent error codes following the PREFIX_CATEGORY_NUMBER format.
+  Use when: defining error codes, creating error handling, designing APIs.
+  Keywords: error code, error handling, error format, API errors, 錯誤碼, 錯誤處理.
+---
+
+# Error Code Guide
+
+> **Language**: English | [繁體中文](../../../locales/zh-TW/skills/claude-code/error-code-guide/SKILL.md)
+
+**Version**: 1.0.0
+**Last Updated**: 2025-12-30
+**Applicability**: Claude Code Skills
+
+---
+
+## Purpose
+
+This skill helps design consistent error codes following the standard format, enabling better debugging, monitoring, and user experience.
+
+## Quick Reference
+
+### Error Code Format
+
+```
+<PREFIX>_<CATEGORY>_<NUMBER>
+```
+
+| Component | Description | Example |
+|-----------|-------------|---------|
+| PREFIX | Application/service identifier | AUTH, PAY, USR |
+| CATEGORY | Error category | VAL, SYS, BIZ |
+| NUMBER | Unique numeric identifier | 001, 100, 404 |
+
+### Examples
+
+```
+AUTH_VAL_001    → Authentication validation error
+PAY_SYS_503     → Payment system unavailable
+USR_BIZ_100     → User business rule violation
+API_NET_408     → API network timeout
+```
+
+### Error Categories
+
+| Category | Full Name | Description | HTTP Status |
+|----------|-----------|-------------|-------------|
+| **VAL** | Validation | Client input validation failures | 400 |
+| **BIZ** | Business | Business rule violations | 422 |
+| **SYS** | System | Internal system failures | 500 |
+| **NET** | Network | Communication failures | 502/503/504 |
+| **AUTH** | Auth | Security-related errors | 401/403 |
+
+### Category Code Ranges
+
+| Range | Description | Example |
+|-------|-------------|---------|
+| *_VAL_001-099 | Field validation | Missing required field |
+| *_VAL_100-199 | Format validation | Invalid email format |
+| *_VAL_200-299 | Constraint validation | Password too short |
+| *_BIZ_001-099 | State violations | Order already cancelled |
+| *_BIZ_100-199 | Rule violations | Cannot return after 30 days |
+| *_BIZ_200-299 | Limit violations | Daily limit exceeded |
+| *_AUTH_001-099 | Authentication | Invalid credentials |
+| *_AUTH_100-199 | Authorization | Insufficient permissions |
+| *_AUTH_200-299 | Token/session | Token expired |
+
+## HTTP Status Code Mapping
+
+| Category | HTTP Status | Description |
+|----------|-------------|-------------|
+| VAL | 400 | Bad Request |
+| BIZ | 422 | Unprocessable Entity |
+| AUTH (001-099) | 401 | Unauthorized |
+| AUTH (100-199) | 403 | Forbidden |
+| SYS | 500 | Internal Server Error |
+| NET | 502/503/504 | Gateway errors |
+
+## Detailed Guidelines
+
+For complete standards, see:
+- [Error Code Standards](../../../core/error-code-standards.md)
+
+### AI-Optimized Format (Token-Efficient)
+
+For AI assistants, use the YAML format files for reduced token usage:
+- Base standard: `ai/standards/error-codes.ai.yaml`
+
+## Error Response Format
+
+### Single Error
+
+```json
+{
+  "success": false,
+  "error": {
+    "code": "AUTH_VAL_001",
+    "message": "Email is required",
+    "field": "email",
+    "requestId": "req_abc123"
+  }
+}
+```
+
+### Multiple Errors
+
+```json
+{
+  "success": false,
+  "errors": [
+    {
+      "code": "AUTH_VAL_001",
+      "message": "Email is required",
+      "field": "email"
+    },
+    {
+      "code": "AUTH_VAL_201",
+      "message": "Password must be at least 8 characters",
+      "field": "password"
+    }
+  ],
+  "requestId": "req_abc123"
+}
+```
+
+## Internal Error Object
+
+```typescript
+interface ApplicationError {
+  // Core fields
+  code: string;          // "AUTH_VAL_001"
+  message: string;       // Technical message for logs
+
+  // User-facing
+  userMessage: string;   // Localized user message
+  userMessageKey: string; // i18n key: "error.auth.val.001"
+
+  // Context
+  field?: string;        // Affected field: "email"
+  details?: object;      // Additional context
+
+  // Debugging
+  timestamp: string;     // ISO 8601
+  requestId: string;     // Correlation ID
+}
+```
+
+## Internationalization (i18n)
+
+### Message Key Format
+
+```
+error.<prefix>.<category>.<number>
+```
+
+### Example Translation Files
+
+```yaml
+# en.yaml
+error:
+  auth:
+    val:
+      001: "Email is required"
+      101: "Invalid email format"
+    auth:
+      001: "Invalid credentials"
+
+# zh-TW.yaml
+error:
+  auth:
+    val:
+      001: "電子郵件為必填欄位"
+      101: "電子郵件格式無效"
+    auth:
+      001: "帳號或密碼錯誤"
+```
+
+## Examples
+
+### ✅ Good Error Codes
+
+```javascript
+AUTH_VAL_001  // Missing required field: email
+AUTH_VAL_101  // Invalid email format
+ORDER_BIZ_001 // Order already cancelled
+ORDER_BIZ_201 // Daily purchase limit exceeded
+DB_SYS_001    // Database query failed
+SEC_AUTH_001  // Invalid credentials
+SEC_AUTH_201  // Token expired
+```
+
+### ❌ Bad Error Codes
+
+```javascript
+ERR_001       // Too vague, no prefix or category
+INVALID       // Not descriptive
+error         // Not a code
+AUTH_ERROR    // Missing number
+```
+
+## Checklist
+
+- [ ] Unique code for each error
+- [ ] Category matches error type
+- [ ] User message is localized
+- [ ] HTTP status is correct
+- [ ] Error is documented
+- [ ] Code is in registry
+
+---
+
+## Configuration Detection
+
+This skill supports project-specific configuration.
+
+### Detection Order
+
+1. Check for existing error code patterns in codebase
+2. Check `CONTRIBUTING.md` for error code guidelines
+3. If not found, **default to PREFIX_CATEGORY_NUMBER format**
+
+### First-Time Setup
+
+If no error code standard found:
+
+1. Suggest: "This project hasn't configured error code standards. Would you like to set up an error code registry?"
+2. Suggest creating `errors/registry.ts`:
+
+```typescript
+export const ErrorCodes = {
+  AUTH_VAL_001: {
+    code: 'AUTH_VAL_001',
+    httpStatus: 400,
+    messageKey: 'error.auth.val.001',
+    description: 'Email field is required',
+  },
+  // ... more codes
+} as const;
+```
+
+---
+
+## Related Standards
+
+- [Error Code Standards](../../../core/error-code-standards.md)
+- [Logging Standards](../../../core/logging-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)