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

package/bundled/locales/zh-CN/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-CN/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)