OpenCode Reglas (AGENTS.md)

En OpenCode,las reglas (Rules) son el mecanismo central que controla el comportamiento de la IA。

Podemos, a través delAGENTS.mdarchivo, proporcionar instrucciones personalizadas a OpenCode para que desarrolle según las normas de tu proyecto.

Las herramientas determinan lo que la IA puede hacer; AGENTS.md determina cómo debe hacerlo la IA.

AGENTS.md = Establecer normas de desarrollo del equipo para la IA.

1. ¿Qué es AGENTS.md?

AGENTS.mdEs un archivo de reglas que se utiliza para:

  • Definir la estructura del proyecto
  • Restringir el estilo del código
  • Estandarizar el proceso de desarrollo
  • Guiar a la IA sobre cómo ejecutar tareas

Estos contenidos se añadirán al contexto del LLM.

Efectos:

  • La IA entiende mejor tu proyecto
  • El código generado cumple mejor con las normas
  • Se reducen las modificaciones repetidas

2. Inicialización rápida

Ejecutar en OpenCode:

/init

Este comando:

  • Escanea la estructura de tu proyecto
  • Analiza la forma de organización del código
  • Genera AGENTS.md automáticamente

Sugerencia:

  • Haz commit de AGENTS.md a Git
  • Como norma unificada del equipo

3. Estructura de ejemplo

# 项目说明

这是一个基于 TypeScript 的 monorepo 项目。

## 项目结构

- packages/ 核心模块
- infra/ 基础设施
- web/ 前端应用

## 代码规范

- 使用 TypeScript 严格模式
- 公共代码放在 packages/core
- 所有函数必须添加注释

## 开发约定

- 使用 workspace 方式引用模块
- API 必须统一错误处理

Esencia: «escribir» las normas del equipo «para que la IA las vea»

4. Alcance de las reglas

1. Reglas a nivel de proyecto

Ruta:

./AGENTS.md

Función:

  • Solo tiene efecto en el proyecto actual
  • Compartido por el equipo

2. Reglas globales

Ruta:

~/.config/opencode/AGENTS.md

Función:

  • Tiene efecto en todos los proyectos
  • De uso personal

Usos sugeridos:

  • Hábitos de codificación personales
  • Control del estilo de salida

5. Compatibilidad con Claude Code

OpenCode es compatible con el sistema de reglas de Claude Code:

  • Regla de proyecto: CLAUDE.md
  • Regla global: ~/.claude/CLAUDE.md
  • Directorio de habilidades: ~/.claude/skills/

Si no deseas usarlo, puedes desactivarlo:

export OPENCODE_DISABLE_CLAUDE_CODE=1

6. Prioridad de carga de reglas (Importante)

OpenCode carga en el siguiente orden al iniciar:

  1. Busca AGENTS.md desde el directorio actual hacia arriba
  2. Si no existe → busca CLAUDE.md
  3. Regla global ~/.config/opencode/AGENTS.md
  4. Regla global de Claude ~/.claude/CLAUDE.md

Puntos clave:

  • AGENTS.md tiene la máxima prioridad
  • En el mismo nivel, solo se usa el primer archivo que coincida

7. Reglas extendidas (instructions)

Puedes, enopencode.jsonla configuración, cargar archivos de reglas adicionales:

{
  "instructions": [
    "CONTRIBUTING.md",
    "docs/guidelines.md",
    ".cursor/rules/*.md"
  ]
}

Ventajas:

  • Reutilizar documentos existentes
  • Evitar mantenimiento duplicado

Admite reglas remotas

{
  "instructions": [
    "https://raw.githubusercontent.com/xxx/rules/main/style.md"
  ]
}

Nota:

  • Admite carga mediante URL
  • Tiempo de espera: 5 segundos

8. Reglas modulares (Avanzado)

Método recomendado (usar instructions)

{
  "instructions": [
    "docs/dev.md",
    "test/rules.md",
    "packages/*/AGENTS.md"
  ]
}

Ideal para:

  • monorepo
  • Proyectos grandes

Método 2: Referencia manual en AGENTS.md

# 规则加载说明

当遇到 @xxx 文件时，请使用 read 工具加载。

- 不要一次性加载全部文件
- 按需加载
- 加载后必须遵守

Ejemplo:

TypeScript 规范：@docs/typescript.md
React 规范：@docs/react.md
API 规范：@docs/api.md

Implementar la «carga de reglas bajo demanda»

9. Mejores prácticas (Importante)

1. Las reglas deben ser específicas

❌ No escribas:

El código debe ser estandarizado.

✅ Deberías escribir:

所有函数必须添加 JSDoc 注释

2. Las reglas deben ser ejecutables

La IA solo puede ejecutar reglas explícitas, no descripciones abstractas.

3. No escribas demasiado largo

Sugerencia:

  • Las reglas principales se escriben en AGENTS.md
  • Las reglas detalladas se dividen en archivos de instructions

4. Mantenimiento unificado por el equipo

  • Incorporarlo a la gestión de Git
  • Como parte de las normas de desarrollo
Otras extensiones