Each file has a clear role.
The names form a navigation contract for people and assistants. Their content must describe your project.
Document and tool reference
| File | Role | When to read or run |
|---|---|---|
| PATHS.toml | Paths, modules, official sources and checks. | Read first. |
| AGENTS.md | Permanent execution rules for assistants and contributors. | At the start and before risky actions. |
| PRD.md | Product requirements, real state and gaps. | When defining or reviewing work. |
| ESCOPO.md | Product scope, boundaries, modules and naming. | Before changing architecture or roles. |
| QUALITY_ROADMAP.md | Workflow, SOLID, task-based reading and definition of done. | During planning, work and review. |
| GOVERNANCA.md | Risks, priorities, dependencies and release gates. | For risk and release decisions. |
| DEMANDAS.md | Actionable backlog in packages and batches. | When choosing, finishing or blocking work. |
| TELAS.md | Routes, screens, states and CRUD boundaries. | For experience and navigation changes. |
| TESTES.md | Risk-based checks, fixtures, coverage and retesting. | Before and after implementation. |
| BUGS.md | Reproduction, diagnosis, fix and retest. | When investigating or closing bugs. |
| DECISOES.md | Key decisions, reasons, impact and rollback. | When a choice changes architecture or operations. |
| RUNBOOK.md | Setup, operations, diagnosis, deploy, smoke tests and recovery. | To repeat operational procedures. |
| docs/prd-classifications.json | Reviewed states and evidence for each item. | After inventory and during review. |
| docs/PRD_RASTREABILIDADE.md | Generated matrix of requirements, modules and evidence. | To review coverage and snapshot gaps. |
| check.sh | Runs model validation and configured project checks. | Based on risk and at applicable closure. |
| scripts/prd_inventory.py | Finds items, reconciles states and generates the matrix. | During PRD bootstrap, update and validation. |
How to handle conflicting information
Use PATHS for paths and checks, QUALITY_ROADMAP for workflow and boundaries, GOVERNANCA for risks and operations, and the backlog for planned work. PRD and topic documents connect intent to code. Confirm the adopted project’s own precedence.
If a document says ready but the real flow fails, record the conflict. Do not change a state to hide the failure. Keep local evidence, remote evidence and human acceptance separate.
Translate without breaking references
The original kit keeps Portuguese filenames. You may translate their content and keep the names so references and validators stay consistent. If you rename files, update PATHS, links, scripts and documents together.
What traceability connects
- Requirement → module → screen or route → contract → data → test.
- Decision → reason → affected code → risk → recovery path.
- Bug → reproduction → confirmed cause → fix → retest.
Keep readingExamples →