無程式碼也能輕鬆打造專業LINE官方帳號！一鍵導入模板，讓AI助你行銷加分！
Planning-with-Files es un innovador proyecto de codigo abierto de OthmanAdi que implementa un sistema de planificacion persistente basado en Markdown para agentes de codificacion de IA. Inspirado en el enfoque de planificacion de Manus, el proyecto utiliza un sistema estructurado de 3 archivos para mantener un documento de plan vivo que evoluciona a medida que el agente de IA trabaja en las tareas. Esta disenado tanto como una habilidad de Claude Code como una integracion independiente a traves del Agents SDK.
La idea central detras de Planning-with-Files es que los agentes de codificacion de IA, particularmente aquellos que trabajan en tareas complejas de multiples pasos, se benefician enormemente de una planificacion persistente y estructurada que sobrevive a traves de los turnos de conversacion y las limitaciones de la ventana de contexto del modelo. Al mantener los planes en archivos Markdown que se leen, actualizan y reescriben a medida que avanza el trabajo, el sistema permite a los agentes de IA mantener estrategias coherentes a largo plazo incluso cuando las ventanas de contexto se agotan.
Como funciona el sistema de 3 archivos?
El sistema de planificacion mantiene tres archivos Markdown distintos que trabajan juntos para proporcionar una gestion integral de tareas. El archivo de plan contiene la estrategia de alto nivel y el desglose de tareas. El archivo de progreso rastrea lo que se ha completado, lo que esta en progreso y lo que queda. El archivo de bloc de notas proporciona espacio para razonamiento intermedio, notas y descubrimientos que no pertenecen al plan en si.
| Archivo | Proposito | Frecuencia de Actualizacion | Contenido de Ejemplo |
|---|---|---|---|
| PLAN.md | Desglose de tareas y estrategia de alto nivel | Cuando cambian los hitos | Lista de tareas, dependencias, criterios de exito |
| PROGRESS.md | Estado en tiempo real de cada tarea | Despues de cada accion | Verificaciones completadas, paso actual, bloqueos |
| SCRATCHPAD.md | Memoria de trabajo y notas intermedias | Continuamente | Observaciones, decisiones, fragmentos |
Que es la planificacion al estilo Manus?
Manus es un asistente de codificacion de IA conocido por su enfoque metódico y de planificacion primero para tareas complejas. Antes de comenzar la implementacion, Manus crea un plan detallado, lo valida contra los requisitos y luego ejecuta paso a paso, actualizando el plan a medida que surge nueva informacion. Planning-with-Files trae esta misma metodologia a cualquier agente de codificacion de IA al codificar la disciplina de planificacion en archivos Markdown persistentes que el agente lee y actualiza.
flowchart LR
A[Solicitud del Usuario] --> B[Inicializar Plan]
B --> C[Crear PLAN.md]
C --> D[Crear PROGRESS.md]
D --> E[Crear SCRATCHPAD.md]
E --> F{Ejecutar Tarea}
F --> G[Actualizar PROGRESS.md]
G --> H[Actualizar SCRATCHPAD.md]
H --> I{Tarea Completa?}
I -->|No| F
I -->|Si| J[Finalizar PLAN.md]
J --> K[Enviar Resultado]Instalacion y Configuracion
| Metodo | Comando | Notas |
|---|---|---|
| Habilidad de Claude Code (CLI) | claude add skill othmanadi/planning-with-files | Se instala automaticamente como habilidad |
| Clonacion Manual | git clone https://github.com/OthmanAdi/planning-with-files | Copiar archivos de plan manualmente |
| Agents SDK | npm install @agents-sdk/planning | Para uso programatico |
| Cursor IDE | Copiar .cursorrules del repositorio | Integracion con Cursor AI |
Que problemas resuelve Planning-with-Files?
Los agentes de codificacion de IA, incluso con grandes ventanas de contexto, enfrentan varios desafios fundamentales. El desbordamiento de la ventana de contexto ocurre cuando el historial de la conversacion excede la capacidad del modelo. La perdida de enfoque de la tarea ocurre cuando los agentes se desvian del objetivo original durante sesiones largas. La dificultad para rastrear el progreso significa que los agentes pueden rehacer trabajo completado o perder requisitos. La falta de persistencia significa que cuando una sesion termina, todo el contexto de planificacion se pierde. Planning-with-Files aborda todos estos problemas externalizando el estado de planificacion en archivos que persisten a traves de las sesiones y sobreviven a los reinicios de la ventana de contexto.
sequenceDiagram
participant Agent as Agente IA
participant Plan as PLAN.md
participant Progress as PROGRESS.md
participant Scratch as SCRATCHPAD.md
participant User as Usuario
User->>Agent: Solicitud de tarea compleja
Agent->>Plan: Crear desglose de tareas
Agent->>Progress: Inicializar seguimiento
loop Por Paso
Agent->>Plan: Leer plan actual
Agent->>Progress: Actualizar estado
Agent->>Scratch: Registrar observaciones
Scratch-->>Agent: Recordar contexto
Agent->>User: Reportar progreso
User->>Agent: Retroalimentacion
Agent->>Progress: Ajustar plan
end
Agent->>User: Tarea completa con resumenQue herramientas de codificacion de IA soportan este sistema?
El sistema esta disenado principalmente para Claude Code, donde funciona como una habilidad que se puede invocar con comandos de barra. Tambien soporta Cursor IDE a traves de la configuracion de cursorrules. El formato del archivo de plan es intencionalmente neutro en cuanto al proveedor – los mismos archivos Markdown funcionan con cualquier asistente de codificacion de IA, y el sistema se puede integrar en marcos de agentes personalizados a traves del Agents SDK. El formato de archivo es Markdown plano, por lo que tambien puede ser leido y editado por humanos.
Cual es la filosofia detras de la planificacion con archivos?
La filosofia es directa: los agentes de IA deberian externalizar su estado de planificacion en formatos legibles por humanos. Al usar archivos Markdown en lugar de formatos de base de datos propietarios o almacenamiento especifico de herramientas, los planes se vuelven inspeccionables, editables y compartibles entre humanos y IA. Esto crea un modelo de colaboracion transparente donde ambas partes pueden ver el estado actual del trabajo, entender lo que se ha hecho y acordar lo que viene despues. Tambien permite flujos de trabajo interesantes como revisar el plan de un agente antes de que comience la ejecucion, o hacer que multiples agentes se coordinen a traves de archivos de plan compartidos.
Preguntas Frecuentes
Que es Planning-with-Files? Es un sistema de planificacion persistente en Markdown para agentes de codificacion de IA que utiliza tres archivos (PLAN.md, PROGRESS.md, SCRATCHPAD.md) para gestionar tareas complejas.
Como funciona el sistema de 3 archivos? PLAN.md contiene el desglose de tareas y la estrategia, PROGRESS.md rastrea el estado en tiempo real de cada tarea y SCRATCHPAD.md almacena la memoria de trabajo y el razonamiento intermedio.
Como lo instalo? Instalar como habilidad de Claude Code via claude add skill othmanadi/planning-with-files, o clonar manualmente el repositorio y configurarlo para tu herramienta de IA.
Que herramientas de IA son compatibles? Disenado para Claude Code, tambien funciona con Cursor IDE via cursorrules y programaticamente a traves del Agents SDK.
Que problemas resuelve? Desbordamiento de ventana de contexto, perdida de enfoque de tarea, dificultad para rastrear progreso y falta de persistencia entre sesiones para agentes de codificacion de IA.
