coding-standards

Files (2)

• SKILL.md
• openai.yaml · agents/

SKILL.md (first lines)

# 编码标准和最佳实践

适用于跨项目的基本编码约定。

此技能是共享的基础，不是详细的框架手册。

- 使用 `frontend-patterns` 进行 React、状态、表单、渲染和 UI 架构。
- 使用 `backend-patterns` 或 `api-design` 进行存储库/服务层、端点设计、验证和服务器特定关注点。
- 当您需要最短的可重用规则层而不是完整的技能演练时，使用 `rules/common/coding-style.md`。

## 何时激活

- 开始新项目或模块
- 审查代码质量和可维护性
- 重构现有代码以遵循约定
- 强制命名、格式或结构一致性
- 设置 linting、格式或类型检查规则
- 向新贡献者介绍编码约定

## 范围边界

为以下情况激活此技能：
- 描述性命名
- 不变性默认值
- 可读性、KISS、DRY 和 YAGNI 强制执行
- 错误处理期望和代码气味审查

不要将此技能作为主要来源用于：
- React 组合、钩子或渲染模式
- 后端架构、API 设计或数据库分层
- 当存在更窄的 ECC 技能时的特定于领域的框架指导

## 代码质量原则

### 1. 可读性优先
- 代码被阅读的次数多于编写的次数
- 清晰的变量和函数名称
- 优先使用自记录代码而不是注释
- 一致的格式

### 2. KISS（保持简单，愚蠢）
- 有效的最简单解决方案
- 避免过度工程
- 没有过早优化
- 易于理解 > 聪明的代码

### 3. DRY（不要重复自己）
- 将常用逻辑提取到函数中
- 创建可重用组件
- 跨模块共享工具
- 避免复制粘贴编程

### 4. YAGNI（你不会需要它）
- 不在需要之前构建功能
- 避免投机性的一般性
- 仅在需要时添加复杂性
- 从简单开始，需要时重构

## TypeScript/JavaScript 标准

### 变量命名

```typescript
// PASS：GOOD：描述性名称
const marketSearchQuery = 'election'
const isUserAuthenticated = true
const totalRevenue = 1000

// FAIL：BAD：不清楚的名称
const q = 'election'
const flag = true
const x = 1000
```

### 函数命名

```typescript
// PASS：GOOD：动词-名词模式
async function fetchMarketData(marketId: string) { }
function calculateSimilarity(a: number[], b: number[]) { }
function isValidEmail(email: string): boolean { }

// FAIL：BAD：不清楚或仅名词
async function market(id: string) { }
function similarity(a, b) { }
function email(e) { }
```

### 不变性模式（关键）

```typescript
// PASS：始终使用扩展运算符
const updatedUser = {
  ...user,
  name: 'New Name'
}

const updatedArray = [...items, newItem]

// FAIL：绝不直接变异
user.name = 'New Name'  // BAD
items.push(newItem)     // BAD
```

### 错误处理

```typescript
// PASS：GOOD：全面的错误处理
async function fetchData(url: string) {
  try {
    const response = await fetch(url)

    if (!response.ok) {
      throw new Error(`HTTP ${response.status}: ${response.statusText}`)
    }

    return await response.json()
  } catch (error) {
    console.error('Fetch failed:', error)

From aaione/everything-claude-code-zh, MIT.

More from aaione/everything-claude-code-zh