coding-guidelines

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Coding Guidelines

编码指南

Principios core para trabajar con LLMs en tareas de desarrollo.

与LLM协作完成开发任务的核心原则。

4 Principios

4项原则

1. Pensa Antes de Codear

1. 思考再编码

NO empezar a escribir codigo inmediatamente.

Surfacea assumptions antes de implementar
Pregunta sobre preferencias: estructuras de datos, patrones, librerias
Presenta multiples opciones con trade-offs
Confirma alineamiento antes de codear

不要立即开始写代码。

在实现前明确假设
询问偏好：数据结构、模式、库
提供多种带有权衡的选项
编码前确认对齐

2. Simplicidad Primero

2. 简洁优先

El codigo mas simple que resuelve el problema.

KISS, DRY, YAGNI siempre
Sin abstracciones especulativas ("por si algun dia...")
Sin features no pedidas
Sin over-engineering: 3 lineas similares > abstraccion prematura

用最简单的代码解决问题。

始终遵循KISS、DRY、YAGNI原则
不做投机性抽象（“万一以后需要...”）
不添加未被要求的功能
避免过度设计：3行相似代码 > 过早抽象

3. Cambios Quirurgicos

3. 精准修改

Editar lo minimo necesario.

Matchear patterns existentes del codebase
No refactorizar codigo que no toca la feature
No agregar docstrings/comments donde no habia
No cambiar estilo/formato de codigo existente

仅修改必要的最小部分。

匹配代码库中已有的模式
不要重构与当前功能无关的代码
不要在原本没有的地方添加文档字符串/注释
不要修改现有代码的风格/格式

4. Objetivos Verificables

4. 可验证目标

Criterios claros para saber cuando esta listo.

Definir que significa "funciona"
Tests que validen el comportamiento esperado
Checkear lint, types, build antes de terminar

明确判断完成状态的标准。

定义“功能正常”的含义
编写验证预期行为的测试
完成前检查lint、类型、构建是否通过

Aplicacion por Lenguaje

按语言应用

Ver referencias para reglas especificas:

```
references/typescript.md
```
- TypeScript strict mode, testing, estructura
```
references/python.md
```
- Type hints, mypy, pytest, ruff

查看参考文档获取特定规则：

```
references/typescript.md
```
- TypeScript严格模式、测试、结构
```
references/python.md
```
- 类型提示、mypy、pytest、ruff

Ejemplos de Uso

使用示例

Ejemplo 1: Usuario pide agregar feature de logging

示例1：用户要求添加日志功能

Usuario: "Agregá logging a este servicio"

MAL (sin consultar):

typescript

// Empezar a agregar winston, estructurar logs, crear middleware...
import winston from 'winston';
const logger = winston.createLogger({...});

BIEN (consultar primero):

Antes de agregar logging, necesito entender:

1. ¿Qué librería de logging prefieren? (winston, pino, console estructurado)
2. ¿A dónde van los logs? (stdout, archivo, servicio externo)
3. ¿Qué nivel de detalle? (solo errores, debug incluido)
4. ¿Hay un formato estándar en el proyecto?

Vi que ya usan console.log en otros lugares. ¿Prefieren mantener
consistencia o migrar todo a una librería?

用户：“给这个服务添加日志功能”

错误做法（未咨询）：

typescript

// 直接开始添加winston、结构化日志、创建中间件...
import winston from 'winston';
const logger = winston.createLogger({...});

正确做法（先咨询）：

在添加日志前，我需要了解：

1. 你们偏好哪种日志库？（winston、pino、结构化console）
2. 日志要输出到哪里？（标准输出、文件、外部服务）
3. 需要什么详细程度？（仅错误、包含调试信息）
4. 项目中是否有标准格式？

我注意到其他地方使用了console.log。你们希望保持一致性，还是迁移到某个日志库？

Ejemplo 2: Usuario pide refactorizar

示例2：用户要求重构

Usuario: "Este archivo está muy largo, refactorizalo"

MAL (hacer todo):

typescript

// Extraer todo a archivos separados, agregar types, cambiar naming...

BIEN (proponer opciones):

El archivo tiene 450 líneas. Opciones:

A) Extraer helpers a utils/helpers.ts (reduce a ~300 líneas)
B) Separar por dominio: user.ts, auth.ts, session.ts
C) Solo extraer la función más larga (validateUserSession, 80 líneas)

¿Cuál preferís? Recomiendo C porque es el cambio mínimo
que mejora legibilidad sin reestructurar todo.

用户：“这个文件太长了，重构一下”

错误做法（全部修改）：

typescript

// 把所有内容提取到单独文件、添加类型、重命名变量...

正确做法（提供选项）：

这个文件有450行。可选方案：

A) 把工具函数提取到utils/helpers.ts（减少到约300行）
B) 按领域拆分：user.ts、auth.ts、session.ts
C) 仅提取最长的函数（validateUserSession，80行）

你偏好哪种？我推荐方案C，因为这是最小改动，既能提升可读性又无需整体重构。

Ejemplo 3: Usuario pide implementar validación

示例3：用户要求实现表单验证

Usuario: "Agregá validación al form de registro"

MAL (asumir):

typescript

// Instalar zod, crear schemas, agregar validación client y server...
import { z } from 'zod';
const userSchema = z.object({...});

BIEN (preguntar scope):

¿Qué tipo de validación necesitás?

1. Solo frontend (mostrar errores en el form)
2. Solo backend (retornar 400 con errores)
3. Ambos (schema compartido)

Vi que el proyecto usa yup en otros forms.
¿Sigo con yup o preferís otra librería?

用户：“给注册表单添加验证功能”

错误做法（自行假设）：

typescript

// 安装zod、创建schema、添加前后端验证...
import { z } from 'zod';
const userSchema = z.object({...});

正确做法（询问范围）：

你需要哪种类型的验证？

1. 仅前端（在表单中显示错误）
2. 仅后端（返回400错误及详情）
3. 前后端都要（共享schema）

我注意到项目中其他表单使用了yup。我是继续用yup还是换其他库？

Anti-patrones

反模式

❌ Saltar a codear sin discutir

❌ 未讨论就直接编码

typescript

// Usuario: "Agregá cache"
// Inmediatamente:
import Redis from 'ioredis';
const redis = new Redis(); // ← ¿Quién pidió Redis?

Problema: Asumiste Redis cuando podría ser in-memory, localStorage, o un servicio externo.

typescript

// 用户：“添加缓存”
// 直接开始：
import Redis from 'ioredis';
const redis = new Redis(); // ← 谁要求用Redis的？

**问题：**你默认使用Redis，但实际可能是内存缓存、localStorage或外部服务。

❌ Agregar features "por las dudas"

❌ 额外添加“以防万一”的功能

typescript

// Te pidieron: agregar un botón de logout
// Agregaste:
<Button onClick={logout}>Logout</Button>
<ConfirmModal /> {/* ← Nadie pidió confirmación */}
<SessionTimeoutWarning /> {/* ← Nadie pidió esto */}

Problema: Features no solicitadas = código extra que mantener.

typescript

// 要求：添加一个登出按钮
// 你却添加了：
<Button onClick={logout}>Logout</Button>
<ConfirmModal /> {/* ← 没人要求确认弹窗 */}
<SessionTimeoutWarning /> {/* ← 没人要求这个 */}

**问题：**未被要求的功能 = 需要维护的额外代码。

❌ Refactorizar de paso

❌ 顺便重构

typescript

// Te pidieron: corregir bug en calculateTotal()
// Hiciste:
- function calculateTotal(items) {
+ function calculateTotal(items: CartItem[]): Money { // ← Tipos nuevos
    // ... fix del bug ...
  }
+ // También renombré variables para mayor claridad ← NO
+ // Y extraje la lógica de descuentos ← NO

Problema: El PR tiene cambios mezclados, difícil de revisar.

typescript

// 要求：修复calculateTotal()中的bug
// 你却做了：
- function calculateTotal(items) {
+ function calculateTotal(items: CartItem[]): Money { // ← 新增类型
    // ... 修复bug ...
  }
+ // 我还重命名了变量以提升可读性 ← 没必要
+ // 并且提取了折扣逻辑 ← 没必要

**问题：**PR中混合了多种修改，难以评审。

❌ Over-engineering

❌ 过度设计

typescript

// Te pidieron: guardar preferencia de tema (dark/light)
// Hiciste:
class ThemeManager implements IThemeProvider {
  private strategy: ThemeStrategy;
  private observers: ThemeObserver[] = [];
  constructor(config: ThemeConfig) { ... }
}

// Cuando bastaba:
localStorage.setItem('theme', 'dark');

Problema: Complejidad innecesaria. Un boolean no necesita un patrón Observer.

typescript

// 要求：保存主题偏好（深色/浅色）
// 你却做了：
class ThemeManager implements IThemeProvider {
  private strategy: ThemeStrategy;
  private observers: ThemeObserver[] = [];
  constructor(config: ThemeConfig) { ... }
}

// 其实只需要：
localStorage.setItem('theme', 'dark');

**问题：**不必要的复杂度。一个布尔值不需要观察者模式。

❌ Asumir en vez de preguntar

❌ 假设而非询问

typescript

// Usuario: "No funciona el login"
// Empezaste a reescribir el auth flow completo...

// Cuando el bug era:
- if (password = storedHash) // typo: = en vez de ===
+ if (password === storedHash)

Problema: Investigar primero, preguntar qué error ven, antes de reescribir.

typescript

// 用户：“登录功能用不了”
// 你直接开始重写整个认证流程...

// 而实际bug是：
- if (password = storedHash) // 笔误：用了=而非===
+ if (password === storedHash)

**问题：**应该先调查、询问用户看到的错误，再动手重写。