Agentic Development Playbook
manjast/agentic-development-playbook
Workflow spec-driven para agentes de código IA com auditoria completa
Ver no GitHubFramework spec-driven para desenvolvimento com agentes de IA, mantendo specs, decisões, tarefas e logs de execução em arquivos versionados. Oferece um fluxo determinístico e rastreável com gates de validação, human-in-the-loop e conformance checks para garantir reprodutibilidade.
Instalação
npx convez-ai manjast/agentic-development-playbook1 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
- Desenvolvimento de software dirigido por especificação com agentes Claude/Cursor
- Auditoria e rastreamento de decisões em projetos de IA
- Validação determinística e gates de qualidade em pipelines de codificação automatizada
Veredito

Ferramenta madura e bem-estruturada para quem precisa de governança rigorosa em projetos com agentes de IA. Abordagem tool-agnostic com conformance checks sólidos, mas exige disciplina na adoção do workflow proposto.
README
A tradução para o português deste README ainda está na fila.
Agentic Development Playbook
A spec-driven workflow for AI coding agents with the repo as the source of truth: specs, decisions, tasks, and run records live in versioned files.
Targets the Claude Code / Cursor / Codex / Gemini CLI ecosystem. Tool-agnostic by design — see
docs/rationale.mdfor why no per-tool guidance is shipped.
Note on the folder name:
eval/is historical. This is a conformance check (structural lint), not a behavioral evaluation. Seedocs/rationale.mdfor why outcome-based evals are out of scope.
Conformance check (latest run)
check_template_fields/AGENTS.md PASS all required fields present
check_template_fields/CLAUDE.md PASS all required fields present
check_template_fields/DECISIONS.md PASS all required fields present
check_template_fields/GATES.md PASS all required fields present
check_template_fields/POC-BRIEF.md PASS all required fields present
check_template_fields/POC-CLOSURE.md PASS all required fields present
check_template_fields/REPORT.md PASS all required fields present
check_template_fields/SOURCE-DIGEST.md PASS all required fields present
check_template_fields/STATUS.md PASS all required fields present
check_template_fields/TASKS.md PASS all required fields present
check_template_fields/gitignore-poc.append.txt PASS all required fields present
check_template_fields/questions-triage.md PASS all required fields present
check_template_fields/task-card.md PASS all required fields present
check_run_manifest/eval/fixtures/example-project/run-manifest.json PASS all required keys present (8 top-level)
check_run_manifest/templates/run-manifest.json PASS all required keys present (8 top-level)
check_gates_ml_eval/eval/fixtures/example-project/GATES.ml-eval.md PASS 7/7 sub-checks present
check_gates_ml_eval/templates/GATES.ml-eval.md PASS 7/7 sub-checks present
Total: 17 Pass: 17 Fail: 0
The conformance check verifies (a) every template has its required fields, (b) any run-manifest.json conforms to the run-reproducibility schema, (c) any GATES.ml-eval.md has the 7 required sub-checks (each as a markdown checkbox; per-check content is not verified — see eval/check.py:476-481 for the design rationale). Runs in <5 sec on stdlib Python 3.12 or 3.13.
This is a structural check, not a behavioral evaluation — see docs/rationale.md for why outcome-based is out of scope, and python eval/check.py --self-test to verify the check itself is not vacuous.
What this prevents
The Playbook's discipline prevents five specific failure modes that plague AI-assisted coding work. Each prevention is supported by templates in this repo. #4 is structurally verified by the conformance check; #1–#3 and #5 are template-presence-supported but not content-verified by the current check — a known scope limit, see docs/rationale.md.
- Lost decisions across context windows —
DECISIONS.md(everyD-NNNentry is dated: question, options, decision, follow-up; append-only) - Drift between TASKS and reality —
TASKS.md(4 sections: In Progress, Ready, Blocked, Done) +STATUS.md(Date + Tracker + one-line current state) - Unreviewable mega-diffs —
task-card.md(explicit "In scope" / "Out of scope" sub-bullets) - Eval claims without evidence —
GATES.ml-eval.md(7 sub-checks) +run-manifest.json(structured run record: commit, seed, environment, budget) - Template sprawl that no one maintains — the 15-template discipline (13 user-facing + 2 eval-meta, with structure enforcement)
What this is
- A repo-native execution discipline for implementation work that needs clear scope, explicit verification, and reviewable task boundaries
- A set of templates for teams or solo builders who want a consistent operating shape once work becomes repo-level
- A light PoC/evaluation path for work that needs evidence, reports, and closure before hardening further
- A provider-agnostic setup built around
AGENTS.mdas the canonical instruction file
What this is not
- A requirements or spec-generation system
- A CLI or automation framework
- A multi-agent orchestration product
- A full public methodology stack covering every upstream and downstream phase
Core path
Use the core path when specs or architecture decisions already exist and the main need is disciplined implementation.
Core artifacts:
AGENTS.mdTASKS.mdDECISIONS.mdtask-card.mdGATES.md(optional)STATUS.md(optional)
Core rules:
- repo files are the source of truth
- one task = one commit
- verification before commit
- no drive-by refactors
- keep tasks small and reviewable
PoC / evaluation path
Use the PoC path when the first phase needs decision-grade evidence rather than a production-ready finish.
The public first pass includes templates for:
POC-BRIEF.mdPOC-CLOSURE.mdREPORT.mdSOURCE-DIGEST.mdquestions-triage.mdGATES.ml-eval.md(ML-eval gate, with 7 sub-checks)run-manifest.json(run reproducibility schema)
The eval/ folder in this repo is itself a working PoC of this path.
This path is useful when you need to:
- make the decision question explicit before implementation expands
- keep source digests smaller than raw inputs
- write reports that can support a gate decision
- close a PoC cleanly instead of letting it drift into pseudo-production
Templates included (15)
Core (7)
AGENTS.mdCLAUDE.md(pointer toAGENTS.mdfor Claude Code)TASKS.mdDECISIONS.mdSTATUS.mdGATES.mdtask-card.md
PoC / evaluation (6)
POC-BRIEF.mdPOC-CLOSURE.mdREPORT.mdSOURCE-DIGEST.mdquestions-triage.mdgitignore-poc.append.txt
Eval-meta (2 — structurally enforced by the conformance check)
GATES.ml-eval.md(ML-eval decision gate with 7 sub-checks)run-manifest.json(run reproducibility schema)
Quick start
- Copy the core templates from
templates/into your repo. - Fill in
AGENTS.mdand set your spec root. - Create
TASKS.mdand your first task card. - If the work is still decision-heavy, add the PoC/evaluation templates as needed.
Recommended minimum layout:
<repo>/
<SPEC_ROOT>/
AGENTS.md
TASKS.md
DECISIONS.md
tasks/
If your tool expects a different instruction filename, keep it as a short pointer to AGENTS.md. For example, if you use Gemini CLI, copy CLAUDE.md to GEMINI.md in your project.
For adopting the Playbook into an existing project, see docs/migration.md.
Example
See examples/worked-example.md for a simple end-to-end example of the core task flow.
For a short PoC/evaluation-oriented flow, see examples/worked-example-poc.md.
For filled-in task card examples (low-risk and high-risk variants), see examples/task-card-example.md and examples/task-card-example-high-risk.md.
The eval/ folder in this repo is also a runnable example: python eval/check.py shows the structural check in action, and python eval/check.py --self-test shows it catching deliberately broken inputs.
Where this fits
This repo assumes specs or architecture decisions already exist and focuses on making implementation legible and verifiable.
If your bigger problem is still upstream discovery, requirements shaping, or broad methodology design, solve that first. This playbook is intentionally narrower than that.
Principles
For the philosophy behind the Playbook, see docs/principles.md.
License
Apache-2.0