convez.ai
SkillProdutividadeIntermediário
zYellow0826

Task Snapshot

zYellow0826/task-snapshot

Previne OOM em refatorações grandes delegando para subagentes

Ver no GitHub
InicialPluginScore · de 0 a 100

Skill para Claude Code que força o agente principal a delegar trabalho pesado para subagentes e manter apenas snapshots de início e fim em seu contexto. Previne crashes por falta de memória (OOM) durante grandes refatorações e migrações de código.

Instalação

$npx convez-ai zYellow0826/task-snapshot

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Refatorações em larga escala sem travamento de máquina
  • Migrações de código em repositórios grandes
  • Edições em batch que tocam múltiplos arquivos com monitoramento de consumo de RAM

Veredito

Solução pragmática que resolve um problema real de performance ao escalar tarefas de código. Padrão bem documentado e fácil de adotar, ideal para quem trabalha com refatorações em projetos grandes.

README

A tradução para o português deste README ainda está na fila.

task-snapshot

A Claude Code skill that forces the main agent to dispatch heavy work to subagents and keep only start / end snapshots in its own context — preventing OOM crashes during large refactors.

简体中文 · English


Background — three crashes

I was running a large refactor across a sizable codebase with Claude Code. Three times during that session, my machine locked up hard and rebooted itself.

The cause wasn't Claude misbehaving — it was Claude being too thorough. The main agent was diligently keeping everything in context: every file it Read, every Grep hit, every diff, every step. Token after token piled up inside both the editor process and the model's context. On a big project that means RAM goes to the moon, the IDE freezes, and eventually the OS taps out.

After the third reboot I told Claude, in roughly these words:

"Why are you crashing my machine three times to run one task? You don't need to keep the whole process. Just give the main agent a snapshot at the start and a snapshot at the end."

The performance difference was immediate. That sentence is the entire skill. This repo is just a formalization of it that you can drop into Claude Code so you don't have to remember to say it every time.

What this skill does

The main agent is the director, not the actor. The director only logs "scene start" and "scene end" — the actors do the scene and digest it themselves.

When triggered:

  1. The main agent immediately spawns one or more subagents (via the Agent tool) for the heavy work.
  2. Subagents read files, edit code, run tests, and iterate inside their own isolated context — invisible to the main agent.
  3. Subagents return only a structured summary (≤200 words). No source dumps, no full diffs, no step-by-step narration.
  4. Before/after the dispatch, the main agent records a real timestamp + a git rev-parse --short HEAD as audit/rollback anchors.
  5. Even if every intermediate step is discarded, you can always reconstruct what changed via git log <start>..<end> and git diff <start>..<end>.

Install

git clone https://github.com/zYellow0826/task-snapshot.git
mkdir -p ~/.claude/skills
cp -r task-snapshot/task-snapshot ~/.claude/skills/

Claude Code loads everything under ~/.claude/skills/ on startup.

The shipped SKILL.md is in Chinese. If you want the English version, rename:

cd ~/.claude/skills/task-snapshot
mv SKILL.md SKILL.zh.md && mv SKILL.en.md SKILL.md

(Claude reads both languages fine — pick whichever you prefer reading/editing yourself.)

How it triggers

Auto-fires when any of these are true:

  • Likely to touch >10 files
  • Likely to require >5 rounds of Read / Grep / Bash
  • User says things like "the whole project / the whole repo / batch / big refactor / migration"
  • User complains about memory / lag / reboots / performance / RAM usage

You can also force it with: "use task-snapshot mode for this".

Workflow

┌──────────────────────────────────────────────────────┐
│ Step 1  Main agent: date + git rev-parse             │
│         Emits "TASK START" snapshot (≤15 lines)      │
└──────────────────────┬───────────────────────────────┘
                       │
                       ▼
┌──────────────────────────────────────────────────────┐
│ Step 2  Agent() dispatches N subagents               │
│         · parallel / sequential                       │
│         · periodic git commits                        │
│         · return structured summary only (≤200 words)│
└──────────────────────┬───────────────────────────────┘
                       │
                       ▼
┌──────────────────────────────────────────────────────┐
│ Step 3  Main agent: date + git rev-parse             │
│         Emits "TASK END" snapshot (≤30 lines)        │
│         Includes ready-to-run git log/diff/reset cmds│
└──────────────────────────────────────────────────────┘

What the main agent is forbidden to do

  • ❌ Use Read to slurp many large files "just to get a feel"
  • ❌ Use Grep across the repo and keep thousands of lines in context
  • ❌ Use TodoWrite with 20+ items spelling out every step
  • ❌ Recap "what subagent X did, I agree, now let's…" after every return
  • ❌ Run long Bash (full build, full test suite) and keep the output in context

When not to use this

  • Single-file edits, Q&A, looking up one symbol — direct is faster; subagents are pure overhead.
  • The user explicitly asks "walk me through every step" — comply, but mention the memory cost once.
  • Multi-turn tasks that depend tightly on the main agent's reasoning between steps. (You can still offload reads / searches / verification.)

License

MIT

Ver o original no GitHub

Bom para

Relacionados