5. O Roteiro

Parte II — A Linguagem

O roteiro é o coração do Corsoo. É a narrativa completa do projeto — cada fluxo, cada tela, cada função escrita em linguagem natural, legível por humanos e parseável por máquinas.

O roteiro não é um documento técnico. É uma narrativa. Qualquer pessoa — dono da empresa, desenvolvedor, designer, cliente — consegue ler e entender o que o projeto faz. Essa é a diferença entre o roteiro e tudo o que o cemitério das metodologias produziu: o diagrama UML exclui o dono; o roteiro inclui todo mundo.

E dele deriva tudo: inventário, escaleta, estimativas, cronograma, orçamento, mapa de risco. Qualquer tela, qualquer sistema, qualquer regra que não estiver no roteiro — não existe no projeto.

A marcação `@[type:Name]`

Todo ator dentro do texto — tudo que faz ou recebe uma ação — é marcado com a sintaxe:

@[type:Name]

Exemplo:

O @[actor:Usuário] acessa a @[screen:Tela de Login] e insere suas credenciais.
O @[system:API de Autenticação] valida o @[data:Email] e a @[data:Senha].
A @[rule:Senha mínimo 8 caracteres] é aplicada.
Em caso de sucesso, o sistema gera um @[resource:JWT Token] e redireciona
para o @[screen:Dashboard].
Em caso de falha, exibe mensagem de erro na @[screen:Tela de Login]
e oferece link para o @[flow:Recuperação de Senha].

Os tipos universais

Type	O que marca	Exemplo
`actor`	Persona ou usuário humano	`@[actor:Usuário]`
`screen`	Tela, interface, componente visual	`@[screen:Tela de Login]`
`action`	Ação executada por ator ou sistema	`@[action:Entrar]`
`system`	Sistema externo, API, serviço, agente não humano	`@[system:API de Autenticação]`
`resource`	Recurso técnico — biblioteca, token, dado técnico	`@[resource:JWT Token]`
`flow`	Referência a outro fluxo do projeto	`@[flow:Recuperação de Senha]`
`rule`	Regra de negócio ou validação obrigatória	`@[rule:Senha mínimo 8 caracteres]`
`data`	Campo, entidade de domínio, dado de negócio	`@[data:Email]`
`component`	Componente reutilizável entre telas	`@[component:Sidebar]`

As quatro regras da marcação

Tipos não são fixos. Novos tipos podem ser criados conforme o projeto exige. Os tipos acima são os universais do Corsoo v1 — um projeto de construção civil terá @[material:...], um de marketing terá @[peca:...].
Categorias emergem do projeto. Não se deve engessar os tipos antes de conhecer o domínio.
Toda marcação gera inventário. O parser lê o roteiro e extrai automaticamente todos os elementos marcados.
O texto deve ser legível sem as marcações. Se retirar as tags, a frase ainda faz sentido. A marcação anota a narrativa — não a substitui.

Marcas de controle

Além dos atores, o roteiro usa marcas de controle para condições e gatilhos. São palavras-chave em caixa alta, sem tipo:

Marca	Função	Exemplo
`@[SE]`	Condição	`@[SE] @[data:logline] existe`
`@[SENÃO]`	Alternativa da condição	`@[SENÃO] → exibe placeholder`
`@[AO]`	Gatilho de evento	`@[AO] sexto dígito preenchido`
`@[EM_DESENVOLVIMENTO]`	Comportamento provisório, existente só para facilitar testes	`@[EM_DESENVOLVIMENTO] código exibido na tela`

Nota normativa: roteiros antigos marcavam condições como @[rule:SE]. A forma oficial é a marca de controle pura — @[SE] — reservando rule para regras de negócio nomeadas.

Os dois registros do roteiro

O roteiro tem dois registros de escrita. Ambos usam a mesma marcação; mudam a forma e o momento.

Registro narrativo — na fase de desenvolvimento

Prosa corrida, um parágrafo ou poucos por fluxo. É o registro da concepção — o que se escreve para entender e aprovar o projeto:

O @[actor:Gestor] cria um novo projeto informando o nome e a visibilidade.
O @[system:API] registra o projeto e atribui automaticamente um Número
Corsoo sequencial. O projeto aparece no @[screen:Slate] e no
@[screen:Portfólio].

Registro decupado — da pré-produção em diante

Blocos estruturados, um por passo, com condições explícitas. É o registro da execução — o que o time abre de manhã para trabalhar:

@[screen:Novo Projeto]

@[actor:Gestor] cria novo projeto na plataforma.

@[screen:Novo Projeto] exibe:
  - Campo @[data:nome_do_projeto] obrigatório
  - @[data:visibilidade] com seleção entre Privado e Público
  - @[action:Criar Projeto] → submete formulário

@[system:API] POST /projects com nome e visibilidade

@[SE] nome vazio
  @[action:Criar Projeto] desabilitado

@[SE] sucesso
  Modal fecha e lista de projetos é recarregada

O registro narrativo responde "o que este fluxo faz?". O registro decupado responde "o que exatamente eu construo hoje?". A decupagem (Capítulo 10) é a transformação de um no outro.

O inventário

Ao parsear o roteiro, o sistema gera automaticamente o inventário do projeto:

{
  "inventory": {
    "actors": ["Usuário", "Administrador"],
    "screens": ["Tela de Login", "Dashboard", "Perfil"],
    "systems": ["API de Autenticação", "Serviço de Email"],
    "resources": ["JWT Token", "bcrypt"],
    "rules": ["Senha mínimo 8 caracteres", "Email único no sistema"],
    "data": ["Email", "Senha", "Nome completo"],
    "flows": ["Recuperação de Senha", "Cadastro"]
  }
}

O inventário é a fonte de verdade do projeto. Dele saem:

Inventário de telas → o design sabe tudo que precisa produzir
Inventário de atores e personas → o teste sabe quem simular
Inventário de sistemas → a arquitetura sabe o que integrar e o que mockar
Inventário de regras → o QA sabe o que validar
Mapa de dependências → a produção sabe a ordem

Cada edição do roteiro atualiza o inventário. Nunca o contrário: ninguém adiciona uma tela "direto no inventário" — adiciona no roteiro, e o inventário reflete. (A especificação do parser está no Apêndice B.)

Como escrever um bom roteiro

Um fluxo por vez, cada fluxo uma jornada. Começa, acontece, termina, tem resultado. Se não tem resultado, não é fluxo — é fragmento.

Tempo presente, voz ativa. "O usuário acessa", não "o usuário deverá acessar". O roteiro descreve o projeto funcionando, não uma promessa.

O herói como sujeito. Quem age é o ator, não "o sistema" genérico. Quando o sistema age, ele é um ator marcado: @[system:...].

Nomeie com consistência. @[screen:Tela de Login] e @[screen:Login] viram duas telas no inventário. O parser deduplica por tipo e nome exato — o roteirista mantém o vocabulário estável.

Marque o que importa, não cada palavra. A marcação existe para gerar inventário e dependências. Marcar artigos e adjetivos só polui a leitura.

Caminho feliz e caminhos de erro. Todo fluxo tem pelo menos um @[SE] de falha. Roteiro que só narra sucesso está pela metade.

O teste do roteiro

Um roteiro está pronto quando passa nos três testes:

Teste da leitura limpa — retire mentalmente todas as marcações. O texto continua sendo uma narrativa que qualquer pessoa entende?
Teste do inventário — todo elemento de que o projeto precisa aparece marcado em algum fluxo? O que não está no roteiro não existe; se o time "sabe" de algo que o roteiro não diz, o roteiro está incompleto.
Teste da jornada — cada fluxo tem início, meio, fim e resultado? A soma dos fluxos completa a missão da logline?

O roteiro é vivo — mas muda por emenda

Até o greenlight, o roteiro é rascunho: reescreve-se à vontade. Depois do greenlight, o roteiro é contrato — e contrato não se altera silenciosamente. Mudanças passam a ser feitas por Emenda de Roteiro, com registro de o que mudou, por que, e impacto em prazo e orçamento (ver Capítulo 9).

Isso não é burocracia — é o mesmo mecanismo do cinema: reescrita em produção existe, mas ninguém finge que o roteiro "sempre foi assim". A emenda protege o time (o escopo cresceu? está documentado) e protege o dono (o prazo mudou? sabe-se quando e por quê).

Corsoo, Engenharia de Organização · corsoo.org

← Logline e Argumento · Sumário · Próximo: Hierarquia de Trabalho →