.projectstore / método / 2
A indústria inventou isso há muito tempo.
Os agentes tornaram isso barato.
ADRs, revisões, backlog, critérios de aceitação, vínculos do objetivo ao código. Equipes de engenharia maduras trabalham assim há vinte anos. O ProjectStore não inventa nada disso.
De onde vem cada peça
- 1969RFCs: decisões escritas e numeradas, depois discutidas abertamente.
- 1992DO-178B: na aviônica, todo requisito precisa ser rastreável até o código e até um teste.
- 1995Scrum: o trabalho como um backlog, ordenado e visível.
- 1999XP: histórias de usuário e critérios de aceitação que dizem quando uma está pronta.
- 2007Kanban para software: um quadro que mostra o que está em andamento.
- 2011ADRs, Michael Nygard: um arquivo curto por decisão de arquitetura.
- agoraAgentes de programação: cada passo leva minutos. Sem os artefatos, toda sessão começa vazia.
Um projeto, muitas mãos. A mesma base para todas.
Um ADR diz o que foi decidido e o que foi descartado. Uma spec diz como deve funcionar. Um épico e suas histórias dizem o que está sendo construído e quando cada parte está pronta. O quadro mostra o que está em andamento.
Com eles, um engenheiro que entra amanhã, um revisor de outra equipe e um agente em uma sessão nova partem todos do que a primeira pessoa sabia. Por isso as equipes que constroem sistemas grandes mantêm esses documentos há décadas.
O processo sempre foi valioso. O que custava caro era ter pessoas executando cada passo.
O processo funciona. Os documentos que ele produz são o que uma empresa guarda de mais valioso depois de um projeto: por que o sistema foi construído assim, o que contava como pronto, onde cada funcionalidade está no código. Mas, feito à mão, por pessoas, ele é lento. Um ADR leva uma tarde para ser escrito e uma semana para ser revisado. Os documentos ficam defasados em relação ao código. O quadro deixa de refletir a realidade. Então as equipes pulam etapas, e o “ágil” vira desculpa para não registrar nada.
Onde os artefatos faltam, é igual com pessoas e com agentes: questões já resolvidas voltam, ninguém sabe dizer por que o código é como é, e todo recém-chegado começa adivinhando.
Com agentes, é o contrário. Escrever um ADR, dividir um épico em histórias ou conferir um diff com os critérios: um agente faz isso em minutos, não em dias. O que falta a um agente é o que as pessoas têm de graça: memória entre sessões, contexto compartilhado com os colegas, o vínculo entre o objetivo e o código. Cada nova sessão começa vazia e decide de novo o que já estava resolvido.
o processo das pessoas+a velocidade dos agentes=ProjectStore
O ProjectStore junta as duas coisas. A velocidade dos agentes torna o velho processo barato pela primeira vez. Os documentos desse processo, guardados em arquivos ao lado do código, dão aos agentes o que eles nunca tiveram: o contexto do projeto, com vínculos para cima, até os objetivos, e para baixo, até o código. A regra é que cada passo seja revisado por um segundo agente, que não escreveu o rascunho. A velocidade ganha memória, e a memória ganha verificação.
Seis etapas, à mão e no ProjectStore.
| Etapa | A prática e sua idade | Feita por pessoas | No ProjectStore |
|---|---|---|---|
| Decisãopor quê | ADR, Michael Nygard, 2011. Antes disso, comitês de arquitetura e revisão de design. | Uma tarde para escrever, uma semana na fila de revisão. As alternativas rejeitadas ficam na cabeça de alguém. | O agente faz o rascunho em um minuto. Outro agente, o critic, procura pontos fracos. Você aprova. O resultado é um arquivo datado, que também registra o que foi rejeitado. |
| Contratocomo | Spec, design doc, RFC. As RFCs são numeradas desde 1969; design docs são a norma em grandes empresas. | Leva uma semana para escrever e, no release, já está desatualizado. Ninguém confere se o código ainda corresponde ao documento. | Uma spec lista o comportamento esperado em regras numeradas. As verificações dela valem para todas as histórias que ela cobre. Uma história não fecha enquanto a spec dela ainda estiver em rascunho. |
| Backlogo quê | Backlog do produto, do Scrum, 1995. Histórias de usuário, do XP, 1999. Kanban para software, 2007. | Reuniões de refinamento. O quadro se descola da realidade em uma semana, porque é mantido à mão. | Cada arquivo de história guarda o próprio status. O quadro, os índices e o mapa de vínculos são gerados a partir desses arquivos. Se ficarem desatualizados, um comando os reconstrói. |
| Planoonde | Design técnico, análise de impacto. O tech lead avalia onde isso entra no código existente. | O conhecimento de como as funcionalidades anteriores entraram no código existe só na cabeça do tech lead. E o tech lead está de férias. | O planner olha onde os épicos anteriores entraram no código. Ele diz onde a mudança deve ficar e o que reaproveitar. O plano vai para a história. |
| Aceitaçãoprova | Critérios de aceitação, Definição de Pronto. XP e Scrum, início dos anos 2000. | Um ciclo de QA no fim da sprint. “Pronto” por declaração; critérios conferidos por amostragem. | O reviewer confere o diff com cada critério e pede evidência: um teste, um comando executado, uma linha de código. Sem evidência, a história não fecha. |
| Rastreabilidadevínculos | Rastreabilidade de requisitos. Obrigatória na aviônica desde a DO-178B (1992) e em software médico. | Uma matriz no Excel “requisito → código → teste” que ninguém atualiza depois do segundo release. | Cada história tem vínculos para cima, com o épico, os ADRs e as specs, e para baixo, com o código. A evidência fica abaixo de cada critério de aceitação. O mapa de vínculos e o mapa de código são gerados, então ninguém os mantém à mão. |
Os vínculos que um agente recebe de graça: do objetivo à prova
- objetivoÉpicoCHECKOUT · por que estamos fazendo issoepic:
- por quêADRa decisão e as opções rejeitadasadr: [ ]
- comoSpeco comportamento esperadospecs: [ ]
- o quêHistóriaplano e critérios de aceitaçãocode_refs:
- ondeCódigosrc/billing/cards/ · onde os épicos anteriores já estão— evidence:
- provaEvidênciatests/cards.test.ts:58 · por critério
Os vínculos ficam no cabeçalho de cada arquivo, e a evidência é uma linha abaixo de cada critério de aceitação. O agente preenche tudo isso enquanto trabalha. O mapa de vínculos mostra a que cada documento está ligado. O mapa de código mostra onde está o código de cada épico. Uma nova sessão, um novo modelo ou um novo colega começa por essa cadeia, não do zero.
Install the projectstore plugin from https://github.com/SmartAndPoint/ProjectStore and set it up for this project.