TWorkflow - Fluxo de Desenvolvimento com IA
clarity-digital-development/tworkflow
Fluxo realista (Context → Plan → Implement → Review → QA → Ship → Retro) para agentes IA
Ver no GitHubUm fluxo prático e comprovado para trabalhar com agentes de IA em projetos de código, estruturado em sete fases: contexto, planejamento, implementação, revisão, QA, deployment e retrospectiva. Inclui 9 documentos, 6 templates prontos para copiar e 2 skills instaláveis para Claude Code, com foco em higiene de contexto e detecção de falhas comuns.
Instalação
npx convez-ai clarity-digital-development/tworkflow1 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
- Estruturar trabalho com agentes de IA em repositórios pequenos e médios
- Manter controle da janela de contexto e orçamento de tokens
- Implementar revisão em múltiplas camadas e QA visual com screenshots
- Evitar falhas comuns: hallucinations, test gaming, sycophantic reviews
Veredito

Material sólido e honesto: prioriza princípios testados na prática sobre hype, documenta cada claim em docs oficiais, e funciona com múltiplos agentes (Claude Code, Cursor, Codex). Ideal para quem quer escalar desenvolvimento com IA sem teatro de personas ou prompts vazios.
README
A tradução para o português deste README ainda está na fila.
Structured Agentic Development
A practical workflow for everyday developers using AI coding agents on one to three repositories. Not a fleet-orchestration system — a repeatable loop you can run on the project in front of you:
Context → Plan → Implement → Review → QA → Ship → Retro
What's in the box:
- 9 short docs — one per phase, plus two cross-cutting guides on context hygiene and agent failure modes.
- 6 copy-paste templates — context file (two flavors), plan document, review checklists, QA report, session handoff.
- 2 installable Claude Code skills —
dev-workflowwalks the loop;context-checkpointwatches your context budget. - A worked example — one small feature carried through the whole loop.
Works with any coding agent that reads project context files (Claude Code, Codex CLI, Cursor, and others). Claude Code–specific material — model selection, plan mode, subagents, the skills — is clearly marked and skippable if you use a different tool.
Why this exists
I use AI coding agents every day on a small number of real repos. Most of the advice I found was either hype or theater — "act as a senior engineer" prompts, agent "companies" staffed with CEO and CTO personas, threads promising 10x results. What actually improved my output was boring: write the scope down before the code, keep diffs small, review with fresh context, look at real screenshots, and reset the session before the context window degrades.
This repo is that workflow, written down so you can copy it. Two rules keep it honest: every tool-specific claim traces to official documentation, and nothing depends on a pinned model version or price — so it should age better than a screenshot thread. The reasoning behind each piece is in docs/00-principles.md.
The loop
| Phase | What happens | Doc |
|---|---|---|
| Context | The agent gets a small, accurate project context file | docs/01-context.md |
| Plan | Scope is pinned down in a plan document before code is written | docs/02-planning.md |
| Implement | Small diffs, frequent checkpoints, scoped tasks | docs/03-implementation.md |
| Review | Three review lenses run as separate passes with checklists | docs/04-review.md |
| QA | Functional checks plus a visual QA step with real screenshots | docs/05-qa.md |
| Ship | Tests, docs sync, PR | docs/05-qa.md (Ship section) |
| Retro | What the plan got wrong feeds the next plan | docs/02-planning.md |
Cross-cutting, because agents fail the same ways in every phase:
- docs/07-context-hygiene.md — the 40% rule: treat the context window as a budget and reset deliberately, before quality degrades.
- docs/08-failure-modes.md — the failure-mode map: test gaming, hallucinated packages, sycophantic self-review, overconfident "done" claims, and which mechanism in this repo catches each.
Start with docs/00-principles.md, or see the whole loop run once on a small feature in examples/.
Quick start
Commands below work in bash and Windows PowerShell as-is.
-
Get the files:
git clone https://github.com/clarity-digital-development/tworkflow.git(or Download ZIP). -
Copy a context file template into your repo root:
- Claude Code: templates/CLAUDE.md.example →
CLAUDE.md - Codex CLI / Cursor / others: templates/AGENTS.md.example →
AGENTS.md
Fill it in. Keep it under a page (see docs/01-context.md for why).
- Claude Code: templates/CLAUDE.md.example →
-
Copy the templates folder into your repo so the context file's references resolve (run from your project root):
mkdir -p docs/templates cp path/to/tworkflow/templates/*.md docs/templates/ -
For your next non-trivial change, copy
docs/templates/PLAN.mdtodocs/plans/<date>-<slug>.mdand fill it in before prompting — see docs/02-planning.md. -
Before merging, run the review checklists in
docs/templates/REVIEW-CHECKLIST.md(fresh context, one lens at a time), then QA withdocs/templates/QA-REPORT.md.
Claude Code users: install the skills
Run from your clone of this repo:
# personal (all projects)
mkdir -p ~/.claude/skills
cp -r skills/dev-workflow ~/.claude/skills/
cp -r skills/context-checkpoint ~/.claude/skills/
For a project-scoped install (committed with your repo), run from your
project root instead, copying into .claude/skills/:
mkdir -p .claude/skills
cp -r path/to/tworkflow/skills/dev-workflow .claude/skills/
cp -r path/to/tworkflow/skills/context-checkpoint .claude/skills/
Then /dev-workflow walks the loop and /context-checkpoint checks your
context budget — or Claude invokes them automatically when the request
matches. Both bundle their templates and scripts, so they work even in
repos where you haven't vendored anything. Skill locations per the
official docs: https://code.claude.com/docs/en/skills
The context-checkpoint skill ships an optional hook that nudges the
agent automatically when context usage crosses 40% — setup instructions in
skills/context-checkpoint/scripts/context_hook.py
and the why in docs/07-context-hygiene.md.
Using it day to day
What the loop looks like once it's set up:
- Once per repo: fill in the context file. Exact commands, real boundaries, nothing aspirational.
- Trivial change? Just do it — the workflow says so. Non-trivial? Plan document first, and make the agent verify the plan's premises against the actual code before it writes anything. Wrong premises are where most agent work falls apart.
- Implement in plan-step commits. Watch context usage; past 40%, reset at the next clean boundary instead of pushing a degraded session (docs/07-context-hygiene.md).
- Before merge: three review passes in fresh context, then QA with real screenshots — code review can't see a broken layout.
- Five minutes after shipping: note what the plan got wrong. Wrong premises become context-file lines; blind spots become plan-template lines. This is the part that compounds.
What's different about this approach
Most agent-workflow repos assign personas to the agent: a "CEO" reviews scope, a "CTO" reviews architecture, a "QA lead" tests. The persona is decoration. What actually changes agent behavior is what each pass is scoped to look for, what it's allowed to touch, and whether it runs with fresh context. This repo keeps those mechanisms and drops the costumes: each phase is defined by an explicit checklist, not a job title.
The second difference is scope. This is written for a developer running one agent on one to three repos — the common case — not 10–15 parallel sessions. Everything here works in a single terminal.
FAQ
Isn't a ten-section plan overkill for small changes? Yes — and the workflow says so. Trivial changes skip the loop entirely; single-file fixes get a one-paragraph plan. The full loop is for multi-file, behavior-changing work. See the triage split in docs/02-planning.md.
Do I need Claude Code? No. Docs 00–05, 07, and 08 plus all templates are tool-agnostic. Claude Code gets two extras: the model-selection doc and the installable skills.
Does this work on Windows? Yes. The quick-start commands run as-is in PowerShell, and the bundled scripts are plain Python and Node.
Why no personas? Telling a model it's a "senior engineer" has negligible effect on accuracy. Checklists, scoped passes, and fresh context are what work — docs/00-principles.md.
Doesn't all this planning cost more tokens? It moves spend from rework to thinking. A wrong premise caught in a plan costs a sentence to fix; the same mistake caught after implementation costs the whole diff.
Contributing
Issues and PRs welcome — especially corrections where tool behavior has drifted from what these docs claim. Tool-specific claims should trace to official documentation (see Sources).
Sources
Tool-specific claims in these docs trace to official documentation:
- Claude Code docs — https://code.claude.com/docs
- Agent Skills format — https://agentskills.io and the Anthropic skills docs
- AGENTS.md convention — https://agents.md
Where behavior may have changed since writing, the docs say so and link out rather than asserting.
License
MIT — see LICENSE.