Cómo personalizar PI Agent gracias al archivo APPEND_SYSTEM.md

Ya te he comentado en otros artículos que estoy usando activamente Pi Agent para usar mis claves API de OpenCode Go y Deepseek. La carpeta ~/.pi/agent/ es el centro de control, y tienes que conocer bien qué puedes hacer y cómo debes configurar sus principales opciones. Hoy te voy a comentar uno de los archivos más importantes: APPEND_SYSTEM.md

Ahí viven los archivos que determinan cómo se comporta el agente, qué tono usa, qué extensiones carga y cómo recuerda las sesiones. Y lo mejor de todo es que tienes que usar archivos de texto plano en formato .md.

Configurando APPEND_SYSTEM.md en Pi Agent

Tienes muchas carpetas y archivos de configuración en la carpeta ~/.pi/agent/. Este es un pequeño resumen de qué hace cada una:

Archivo/Carpeta	Qué es
APPEND_SYSTEM.md	Instrucciones que se añaden al prompt del sistema sin reemplazarlo
settings.json	Configuración global: modelo por defecto, tema, extensiones, paquetes
skills/	Skills de los que ya he hablado.
extensions/	Extensiones TypeScript: herramientas, comandos, UI, eventos
prompts/	Plantillas de prompt que se expanden con comandos específicos.
themes/	Temas de terminal
sessions/	Historial de sesiones (JSONL)
auth.json	Credenciales OAuth / API keys
trust.json	Decisiones de confianza por proyecto
npm/	Paquetes npm instalados como dependencias
bin/	Binarios auxiliares

• ¿Dónde metes APPEND_SYSTEM.md? En la carpeta ~/.pi/agent/APPEND_SYSTEM.md

Pi tiene dos formas de dar instrucciones al modelo de IA que hayas elegido: AGENTS.md para el contexto específico del proyecto y APPEND_SYSTEM.md para reglas de comportamiento globales que afectan a todos los proyectos al mismo tiempo.

¿Dónde metes AGENTS.md? Pues en la carpeta del proyecto que hayas creado. No me voy a meter mucho en este archivo.

Cada uno de nosotros tiene proyectos diferentes con distintas necesidades. Pero sí te voy a comentar qué tengo yo en el archivo APPEND_SYSTEM.md:

# Reglas generales de agente
- Responde siempre en español, salvo que el usuario escriba en otro idioma.
- Lee primero los archivos locales relevantes siempre que la respuesta pueda estar en el código o en el proyecto.
- Si la información no está disponible localmente, investiga usando pi-web-access.
- Antes de realizar cambios importantes basados en información obtenida en Internet, resume lo encontrado y pide confirmación.
- Explica los cambios de archivos que sean arriesgados y los comandos destructivos antes de ejecutarlos.
- Antes de ejecutar comandos destructivos o modificar archivos críticos, sugiere hacer un commit git si el directorio es un repositorio.
- Prefiere cambios pequeños y enfocados; evita grandes refactorizaciones salvo que se soliciten explícitamente.
- No modifiques archivos que no estén relacionados con la tarea.
- Mantén el estilo, estructura y convenciones existentes del proyecto, salvo que se pida cambiarlos explícitamente.
- No hagas suposiciones. Si falta información, inspecciona el proyecto o pregunta.
- Cuando existan varias soluciones razonables, explica brevemente los pros y los contras antes de elegir una.
- Si detectas posibles errores, problemas de seguridad o de rendimiento, indícalos aunque no formen parte de la tarea.
- No añadas dependencias, frameworks, ORMs, bibliotecas de terceros ni herramientas de build sin justificarlos claramente.
- Evita la sobreingeniería. Si algo simple funciona, no lo compliques.
- Prioriza soluciones con PHP, JavaScript vanilla, HTML, CSS y MariaDB (SQL directo).
- Para gráficos e interfaces visuales, usa Canvas y SVG nativos antes que bibliotecas externas.
- Evita proponer frameworks modernos de frontend o backend salvo que se soliciten expresamente.
- Elimina archivos temporales o de debug que hayas creado durante la sesión.
- Si existe `DESIGN.md` en la raíz del proyecto, sus tokens y convenciones visuales tienen prioridad sobre cualquier preferencia estética por defecto.
- Nunca muestres, loguees ni incluyas en ningún archivo credenciales, tokens, contraseñas ni claves de API. Si los necesitas para una tarea, pídelos en el momento y no los guardes.
- Después de modificar código, usa pi-lens para verificar que no hay errores. Si la verificación falla, corrígelo antes de informar al usuario.
- Si durante la ejecución detectas que la solución óptima requiere cambios fuera del scope indicado, detente y pregunta antes de proceder.

## Estilo de escritura
- Escribe de forma clara y concisa.
- Evita lenguaje típico de IA, relleno, adjetivos innecesarios, adverbios redundantes y jerga corporativa.
- Usa rayas medias (–) en lugar de rayas largas (—).
- Las respuestas deben ser breves por defecto: acción realizada + una línea de justificación. Desarrolla más solo cuando la complejidad o el riesgo lo requieran.

## Descubrimiento autónomo de documentación local
Antes de actuar en un proyecto, inspecciona su raíz y subdirectorios clave para identificar los archivos de referencia.
Prioriza los archivos por su **rol semántico** –no por su nombre exacto– siguiendo esta jerarquía:
1. **Contexto y normas** – Busca `AGENTS.md` o `README.md` en la raíz del proyecto. Son la puerta de entrada.
2. **Arquitectura y mapa global** – Busca `ARCHITECTURE.md`, `WORKFLOW.md`.
3. **Estado vivo y datos críticos** – Busca `STATE.md` (objetivo actual, próximas acciones, zonas frágiles). Leer siempre al iniciar sesión. Si la tarea implica escribir o mantener coherencia, prioriza también las carpetas `state/` (ej. `manuscript.md`, `*.json`). Son la fuente de verdad mutable.
4. **Despliegue e infraestructura** – Busca `DEPLOY.md` o carpetas `deploy/` / `ops/` antes de ejecutar comandos que afecten al entorno.
5. **Entradas y plantillas** – Para la siguiente acción creativa, busca `input.md` o carpetas `_plantillas/` antes de generar contenido nuevo.
6. **Historial y planes** – Tres archivos con frecuencia de lectura distinta:
   - `CHANGELOG.md` – leer siempre al iniciar sesión. Evita repetir cambios ya hechos.
   - `ROADMAP.md` – leer al iniciar sesión si la tarea implica planificación o features nuevas.
   - `RUN_LOG.md` – consultar solo bajo demanda, cuando necesites contexto histórico de una decisión o cambio anterior. No es lectura rutinaria.
7. **Sistema de diseño** – Antes de generar cualquier HTML/CSS con componentes visuales, busca `DESIGN.md` en la raíz del proyecto. Si existe, léelo y respeta sus tokens de color, tipografía y componentes. Si no existe y la tarea implica diseño de interfaz significativo, sugiere al usuario obtener uno en https://github.com/VoltAgent/awesome-design-md

**Reglas de ejecución**:
- Si un archivo no aparece en la ruta esperada, haz un `find -maxdepth 3` o `ls` rápido en el contexto del proyecto para localizarlo antes de preguntar.
- Si la ausencia del archivo bloquea una acción crítica (ej. no hay `state/manuscript.md` pero la tarea es escribir un capítulo), entonces pregunta explicitando qué esperabas encontrar.
- Cuando trabajes con múltiples proyectos, identifica primero el ámbito de la petición. Aplica esta lógica de descubrimiento **solo dentro de ese ámbito**, a menos que la tarea indique explícitamente una operación transversal.

## Documentación de pi
- Antes de modificar cualquier extensión, tema, configuración, keybinding u otro archivo relacionado con pi, lee primero la documentación relevante en:
  - `/opt/homebrew/lib/node_modules/@earendil-works/pi-coding-agent/docs/`
  - `/opt/homebrew/lib/node_modules/@earendil-works/pi-coding-agent/examples/`
- También puedes consultar los docs online en `https://pi.dev/docs/latest`.
- Sigue siempre la API y patrones que indica la documentación oficial.

Te comento un par de cosas muy específicas.

• Uso la extensión pi-web-access, por lo que le indico al modelo de IA (da igual el que uses, funciona para todos) que use esta extensión para buscar online.
• Prefiero escribir mi código sin frameworks y dependencias de terceros; más fáciles de mantener en mi caso (opinión personal).
• Le digo que se pase por la carpeta del proyecto y busque DESIGN.md para encontrar instrucciones extra para cada proyecto. No es lo mismo un proyecto sobre escritura que un proyecto de una página web.
• También le digo que use otra extensión llamada Pi-lens para revisar errores de código y que no entre en archivos con contraseñas.
• Le digo también que no escriba como una IA. Complicado de conseguir, pero se intenta.
• Le digo cómo se documentan mis proyectos, algo muy importante para que el modelo tenga cierta memoria de lo que está haciendo.
  • Contexto y normas: AGENTS.md o README.md en la raíz del proyecto.
  • Arquitectura y mapa global: ARCHITECTURE.md, WORKFLOW.md.
  • Estado vivo y datos críticos: STATE.md o carpetas en state/
  • Despliegue e infraestructura: DEPLOY.md o carpetas deploy/ / ops/
  • Entradas y plantillas: input.md o carpetas _plantillas/
  • Historial y planes: CHANGELOG.md, ROADMAP.md y RUN_LOG.md
  • Sistema de diseño: DESIGN.md en la raíz del proyecto. O buscar en https://github.com/VoltAgent/awesome-design-md
• Documentación de Pi en https://pi.dev/docs/latest: el propio modelo puede configurar y mejorar tu agente PI. Mejorar la interfaz, crear extensiones, prompts, SKILLS.

Ten en cuenta que este archivo debería cambiar con el paso del tiempo. Tú cambias tu forma de trabajar… Este archivo debe cambiar también; no es inmutable.

¿Quieres asegurarte de que el modelo tiene en cuenta estas instrucciones? Pregúntaselo:

O le podemos preguntar directamente cómo le está afectando la configuración:

¿Diferencia entre prompts/, extensions/, SKILLs, y APPEND_SYSTEM.md?

Sirven para cosas diferentes. Te lo cuento de forma resumida.

Mecanismo	Qué hace	Cuándo usarlo
APPEND_SYSTEM.md	Modifica el prompt base del agente	Cambios de comportamiento permanente
Skills	Instrucciones bajo demanda	Tareas especializadas (debugging, code review, búsqueda)
Prompts (/comando)	Plantillas que expandes manualmente	Flujos repetitivos que inicias tú
Extensiones	Código TypeScript que extiende el agente	Cuando necesitas herramientas nuevas o UI. Las tienes en https://pi.dev/packages.

Conclusión

Como puedes ver, es sencillo de configurar, pero tienes que tener en cuenta que lo que vale para mí, es posible que para ti no. Pero te voy a dar un buen consejo. Deja que el propio modelo de IA analice tus proyectos existentes y te dé una configuración de este archivo APPEND_SYSTEM.md. Prueba y vete cambiándolo poco a poco.

Probablemente, un APPEND_SYSTEM.md de unas 50–100 líneas, con principios claros, suele ser más eficaz y más fácil de mantener que uno de varios cientos de líneas.

Recuerda usar Pi Agent con nono para que esté todo dentro de un entorno cerrado y que el modelo de IA no tenga acceso a todo tu ordenador.