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

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

@@ -0,0 +1,412 @@
+---
+source: skills/claude-code/documentation-guide/readme-template.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2025-12-25
+status: current
+---
+
+# README 範本與最佳實踐
+
+> **語言**: [English](../../../../../skills/claude-code/documentation-guide/readme-template.md) | 繁體中文
+
+**版本**: 1.0.0
+**最後更新**: 2025-12-24
+**適用範圍**: Claude Code Skills
+
+---
+
+## 目的
+
+本文件提供撰寫 README 檔案的範本和最佳實踐。
+
+---
+
+## README 章節參考
+
+### 必要章節（最小需求）
+
+| 章節 | 目的 | 必要 |
+|---------|---------|:--------:|
+| 專案名稱 | 識別 | ✅ |
+| 描述 | 功能說明 | ✅ |
+| 安裝 | 安裝方式 | ✅ |
+| 使用 | 使用方式 | ✅ |
+| 授權 | 法律條款 | ✅ |
+
+### 建議章節
+
+| 章節 | 目的 | 何時包含 |
+|---------|---------|-----------------|
+| Badges | 狀態指標 | CI、npm、覆蓋率 |
+| 功能 | 主要能力 | 多功能專案 |
+| 快速開始 | 快速上手 | 複雜設定 |
+| API 參考 | 技術文件 | 函式庫/API |
+| 配置 | 設定選項 | 可配置工具 |
+| 貢獻 | 如何協助 | 開源專案 |
+| 變更記錄 | 版本歷程 | 版本化專案 |
+| FAQ | 常見問題 | 面向使用者的專案 |
+| 致謝 | 感謝名單 | 社群專案 |
+
+---
+
+## README 範本
+
+### 最小 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
+```
+
+### 標準 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)
+```
+
+### 完整 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.
+```
+
+---
+
+## 章節細節
+
+### 專案名稱與描述
+
+**良好**:
+```markdown
+# FastJSON
+
+A blazing-fast JSON parser for Node.js with streaming support.
+```
+
+**不良**:
+```markdown
+# my-project
+
+This is a project.
+```
+
+### 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)
+```
+
+### 安裝
+
+如果適用，包含多個套件管理器：
+
+```markdown
+## Installation
+
+### npm
+```bash
+npm install package-name
+```
+
+### yarn
+```bash
+yarn add package-name
+```
+```
+
+### 使用範例
+
+**良好** - 展示真實使用案例：
+```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 });
+```
+```
+
+**不良** - 過於抽象：
+```markdown
+## Usage
+
+```javascript
+const lib = require('lib');
+lib.func();
+```
+```
+
+### 配置表格
+
+```markdown
+## Configuration
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `timeout` | number | 30000 | Request timeout (ms) |
+| `retries` | number | 3 | Max retry attempts |
+| `debug` | boolean | false | Enable debug logging |
+```
+
+---
+
+## 常見錯誤
+
+### ❌ 過於模糊
+
+```markdown
+# Project
+
+A project for doing things.
+
+## Install
+
+Install it.
+
+## Use
+
+Use it.
+```
+
+### ❌ 沒有範例
+
+```markdown
+# JSON Parser
+
+A JSON parser library.
+
+See API docs for usage.
+```
+
+### ❌ 資訊過時
+
+```markdown
+## Requirements
+
+- Node.js 8+  ← 過時
+- npm 5+      ← 過時
+
+## Installation
+
+```bash
+npm install old-package-name  ← 錯誤的套件名稱
+```
+```
+
+### ❌ 連結失效
+
+```markdown
+See [documentation](docs/old-path.md) for more info.  ← 連結不存在
+```
+
+---
+
+## README 品質檢查清單
+
+- [ ] 專案名稱清楚說明
+- [ ] 用 1-2 句話解釋目的
+- [ ] 安裝說明完整
+- [ ] 使用範例確實可運作
+- [ ] 所有連結都已驗證有效
+- [ ] 版本需求準確
+- [ ] 授權清楚說明
+- [ ] 提供聯絡/支援資訊（面向使用者的專案）
+
+---
+
+## 相關標準
+
+- [Documentation Structure Reference](./documentation-structure.md)
+- [Documentation Writing Standards](../../../core/documentation-writing-standards.md)
+
+---
+
+## 版本歷史
+
+| 版本 | 日期 | 變更 |
+|---------|------|---------|
+| 1.0.0 | 2025-12-24 | 新增：標準章節（目的、相關標準、版本歷史、授權） |
+
+---
+
+## 授權
+
+本文件採用 [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) 授權。
+
+**來源**: [universal-dev-standards](https://github.com/AsiaOstrich/universal-dev-standards)

package/bundled/locales/zh-TW/skills/claude-code/error-code-guide/SKILL.md

@@ -0,0 +1,269 @@
+---
+name: error-code-guide
+description: |
+  設計一致的錯誤碼，遵循 PREFIX_CATEGORY_NUMBER 格式。
+  使用時機：定義錯誤碼、建立錯誤處理、設計 API。
+  關鍵字：error code, error handling, error format, API errors, 錯誤碼, 錯誤處理。
+source: ../../../../../skills/claude-code/error-code-guide/SKILL.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2026-01-08
+status: current
+---
+
+# 錯誤碼指南
+
+> **語言**: [English](../../../../../skills/claude-code/error-code-guide/SKILL.md) | 繁體中文
+
+**版本**: 1.0.0
+**最後更新**: 2025-12-30
+**適用範圍**: Claude Code Skills
+
+---
+
+## 目的
+
+此技能幫助設計一致的錯誤碼，遵循標準格式，實現更好的除錯、監控和使用者體驗。
+
+## 快速參考
+
+### 錯誤碼格式
+
+```
+<前綴>_<類別>_<編號>
+```
+
+| 元素 | 說明 | 範例 |
+|------|------|------|
+| 前綴 (PREFIX) | 應用/服務識別碼 | AUTH, PAY, USR |
+| 類別 (CATEGORY) | 錯誤類別 | VAL, SYS, BIZ |
+| 編號 (NUMBER) | 唯一數字識別碼 | 001, 100, 404 |
+
+### 範例
+
+```
+AUTH_VAL_001    → 認證驗證錯誤
+PAY_SYS_503     → 付款系統無法使用
+USR_BIZ_100     → 使用者商業規則違規
+API_NET_408     → API 網路逾時
+```
+
+### 錯誤類別
+
+| 類別 | 全名 | 說明 | HTTP 狀態碼 |
+|------|------|------|-------------|
+| **VAL** | Validation | 客戶端輸入驗證失敗 | 400 |
+| **BIZ** | Business | 商業規則違規 | 422 |
+| **SYS** | System | 內部系統錯誤 | 500 |
+| **NET** | Network | 通訊錯誤 | 502/503/504 |
+| **AUTH** | Auth | 安全相關錯誤 | 401/403 |
+
+### 類別編號範圍
+
+| 範圍 | 說明 | 範例 |
+|------|------|------|
+| *_VAL_001-099 | 欄位驗證 | 缺少必填欄位 |
+| *_VAL_100-199 | 格式驗證 | 電子郵件格式無效 |
+| *_VAL_200-299 | 約束驗證 | 密碼太短 |
+| *_BIZ_001-099 | 狀態違規 | 訂單已取消 |
+| *_BIZ_100-199 | 規則違規 | 超過 30 天無法退貨 |
+| *_BIZ_200-299 | 限制違規 | 超過每日限制 |
+| *_AUTH_001-099 | 認證 | 帳號密碼錯誤 |
+| *_AUTH_100-199 | 授權 | 權限不足 |
+| *_AUTH_200-299 | Token/Session | Token 已過期 |
+
+## HTTP 狀態碼對應
+
+| 類別 | HTTP 狀態碼 | 說明 |
+|------|-------------|------|
+| 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 |
+
+## 詳細指南
+
+完整標準請參考：
+- [錯誤碼標準](../../../core/error-code-standards.md)
+
+### AI 優化格式（節省 Token）
+
+AI 助手可使用 YAML 格式檔案以減少 Token 使用量：
+- 基礎標準：`ai/standards/error-codes.ai.yaml`
+
+## 錯誤回應格式
+
+### 單一錯誤
+
+```json
+{
+  "success": false,
+  "error": {
+    "code": "AUTH_VAL_001",
+    "message": "電子郵件為必填欄位",
+    "field": "email",
+    "requestId": "req_abc123"
+  }
+}
+```
+
+### 多個錯誤
+
+```json
+{
+  "success": false,
+  "errors": [
+    {
+      "code": "AUTH_VAL_001",
+      "message": "電子郵件為必填欄位",
+      "field": "email"
+    },
+    {
+      "code": "AUTH_VAL_201",
+      "message": "密碼至少需要 8 個字元",
+      "field": "password"
+    }
+  ],
+  "requestId": "req_abc123"
+}
+```
+
+## 內部錯誤物件
+
+```typescript
+interface ApplicationError {
+  // 核心欄位
+  code: string;          // "AUTH_VAL_001"
+  message: string;       // 技術訊息（用於日誌）
+
+  // 使用者介面
+  userMessage: string;   // 本地化使用者訊息
+  userMessageKey: string; // i18n 鍵值: "error.auth.val.001"
+
+  // 上下文
+  field?: string;        // 相關欄位: "email"
+  details?: object;      // 附加資訊
+
+  // 除錯
+  timestamp: string;     // ISO 8601
+  requestId: string;     // 關聯 ID
+}
+```
+
+## 國際化 (i18n)
+
+### 訊息鍵值格式
+
+```
+error.<前綴>.<類別>.<編號>
+```
+
+### 翻譯檔案範例
+
+```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: "帳號或密碼錯誤"
+```
+
+## 範例
+
+### ✅ 良好的錯誤碼
+
+```javascript
+AUTH_VAL_001  // 缺少必填欄位: email
+AUTH_VAL_101  // 電子郵件格式無效
+ORDER_BIZ_001 // 訂單已取消
+ORDER_BIZ_201 // 超過每日購買限制
+DB_SYS_001    // 資料庫查詢失敗
+SEC_AUTH_001  // 帳號密碼錯誤
+SEC_AUTH_201  // Token 已過期
+```
+
+### ❌ 不良的錯誤碼
+
+```javascript
+ERR_001       // 太模糊，沒有前綴或類別
+INVALID       // 不具描述性
+error         // 不是錯誤碼
+AUTH_ERROR    // 缺少編號
+```
+
+## 檢查清單
+
+- [ ] 每個錯誤有唯一代碼
+- [ ] 類別符合錯誤類型
+- [ ] 使用者訊息已本地化
+- [ ] HTTP 狀態碼正確
+- [ ] 錯誤已記錄文件
+- [ ] 代碼已加入註冊表
+
+---
+
+## 設定偵測
+
+此技能支援專案特定設定。
+
+### 偵測順序
+
+1. 檢查程式碼庫中現有的錯誤碼模式
+2. 檢查 `CONTRIBUTING.md` 中的錯誤碼指南
+3. 若無找到，**預設使用 PREFIX_CATEGORY_NUMBER 格式**
+
+### 首次設定
+
+若未找到錯誤碼標準：
+
+1. 建議：「此專案尚未設定錯誤碼標準。您要建立錯誤碼註冊表嗎？」
+2. 建議建立 `errors/registry.ts`：
+
+```typescript
+export const ErrorCodes = {
+  AUTH_VAL_001: {
+    code: 'AUTH_VAL_001',
+    httpStatus: 400,
+    messageKey: 'error.auth.val.001',
+    description: '電子郵件欄位為必填',
+  },
+  // ... 更多錯誤碼
+} as const;
+```
+
+---
+
+## 相關標準
+
+- [錯誤碼標準](../../../core/error-code-standards.md)
+- [日誌標準](../../../core/logging-standards.md)
+
+---
+
+## 版本歷史
+
+| 版本 | 日期 | 變更 |
+|------|------|------|
+| 1.0.0 | 2025-12-30 | 初始發布 |
+
+---
+
+## 授權
+
+此技能採用 [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) 授權。
+
+**來源**: [universal-dev-standards](https://github.com/AsiaOstrich/universal-dev-standards)