TraceCraft
konono/tracecraft
Jornaling estruturado para registrar como a IA chegou ao resultado
Ver no GitHubSkill de journaling estruturado para Claude Code e opencode que captura o processo de raciocínio completo da IA — investigações, hipóteses, falhas e decisões — em documentos revisáveis e reproduzíveis. Transforma o processo de trabalho em um deliverable auditável, registrando worklog, findings, troubleshooting, decisões, guias finais e retrospectivas.
Instalação
npx convez-ai konono/tracecraft1 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
Casos de uso
- Auditar e revisar trabalho realizado por agentes IA
- Documentar investigações e decisões técnicas para reprodução futura
- Gerar guias step-by-step a partir de sessões de trabalho com IA
- Analisar padrões de falha e aprendizados em projetos assistidos por IA
Veredito

Ferramenta sólida para quem trabalha com Claude Code e precisa de rastreabilidade completa do trabalho da IA. Preenche uma lacuna real ao capturar não apenas o resultado, mas todo o processo de raciocínio — essencial para auditoria, reprodução e aprendizado. Instalação clara e suporta tanto modo automático quanto manual.
README
A tradução para o português deste README ainda está na fila.
tracecraft
Record how AI got there, not just what it built.
A structured journaling skill for Claude Code and opencode that captures the full reasoning process — investigations, hypotheses, failures, and decisions — as reviewable, reproducible documents.
Why
When AI agents complete a task, you get the final result. But you lose:
- What was investigated and why
- Which hypotheses were formed
- What was tried and failed
- Why the final approach was chosen
tracecraft treats the work process itself as a deliverable, making it possible to review, reproduce, learn from, and audit AI-assisted work.
What It Records
Each session generates a structured journal under .tracecraft/:
| File | Purpose |
|---|---|
worklog.md | Chronological work log with steps, expectations, and actual results |
findings.md | Investigation results — what was discovered and its impact |
troubleshooting.md | Problem isolation, root cause analysis, and resolution |
decisions.md | Key decisions with alternatives considered and trade-offs |
final-guide.md | Reproducible step-by-step guide distilled from the work |
retrospective.md | Lessons learned and reusable patterns |
Installation
Claude Code
Requires Python 3.6+ and Claude Code.
sh install.sh --global # all projects
sh install.sh --project # current project only
sh install.sh # interactive
The installer:
- Copies the hook scripts to
.claude/hooks/ - Copies the skill definition to
.claude/skills/ - Registers the
UserPromptSubmitandPreCompacthooks in.claude/settings.json
opencode
Requires opencode.
sh install.sh --opencode --global # all projects (~/.config/opencode/)
sh install.sh --opencode --project # current project only (.opencode/)
The installer:
- Copies the skill definition to
skills/tracecraft/SKILL.md - Copies the custom command to
commands/tracecraft.md - Installs templates to
.tracecraft/templates/
Usage
tracecraft works in two modes:
Auto mode (Claude Code with hooks)
Once installed, the hook detects each new Claude Code session and automatically prompts journal initialization. Journals are updated in real-time as you work.
Manual mode (opencode / without hooks)
Run /tracecraft at the end of a session to generate all journal files at once from the conversation history. This is the default mode for opencode, which does not support hooks.
Commands
| Command | Description |
|---|---|
/tracecraft start [title] | Start a new journal session |
/tracecraft step <name> | Add a work step to the log |
/tracecraft finding <topic> | Record an investigation result |
/tracecraft issue <name> | Record a problem and its resolution |
/tracecraft decision <topic> | Record a key decision |
/tracecraft finalize | Generate the final guide and retrospective |
/tracecraft status | Show current journal state |
Uninstallation
sh uninstall.sh --global # Claude Code global
sh uninstall.sh --project # Claude Code project
sh uninstall.sh --opencode --global # opencode global
sh uninstall.sh --opencode --project # opencode project