---
id: analyze-project-structure
agent: architect
title: Analisar a estrutura do projeto para uma nova feature
inputs: [story]
outputs: [mapa de estrutura, pontos de integração, recomendação REUSE/ADAPT/CREATE]
elicit: false
modes: [interactive, yolo]
---

# Analisar a estrutura do projeto para uma nova feature

**Objetivo:** mapear onde uma feature da story vai morar dentro da estrutura existente — quais módulos
ela toca, o que reusa e onde encaixa — antes que uma linha seja escrita, para que o @dev implemente
sem reinventar o que já existe.

**Pré-condições:**
- Existe uma story (ou spec) que descreve a feature. Sem ela, **pare** e elicite o escopo — não
  analiso estrutura para um alvo que não rastreia a um pedido.
- O repositório está acessível e legível. Se for um codebase desconhecido, prefiro rodar primeiro a
  task `document-project` para ter o mapa antes de analisar o encaixe.

## Passos

1. **Leia a story COMPLETA** — ACs, notas, restrições. Extraio o que a feature precisa tocar:
   camadas (frontend/backend/dados/infra), entidades de domínio e contratos de API.
2. **Mapeie a árvore relevante** (`Glob`/`Read`) — não o repositório inteiro, só os diretórios que a
   feature habita. Identifico a convenção de organização (por camada, por feature, por domínio) e a
   sigo; não imponho uma estrutura nova sem justificativa.
3. **Liste os pontos de integração.** Para cada camada que a feature toca, anoto o ponto exato de
   encaixe: rota/handler, serviço, modelo de dados, componente. Cada ponto vira uma fronteira com um
   dono (banco → @data-engineer; UI → @ux-design-expert; código → @dev).
4. **Decida REUSE > ADAPT > CREATE** para cada peça. Procuro o utilitário/componente/serviço que já
   resolve. Se existe, REUSE. Se quase resolve, ADAPT (sem quebrar quem consome). Só CREATE quando
   nada serve — e registro o porquê. Over-engineering é dívida desde o dia um.
5. **Rode o teste do 10× nos pontos de integração.** Para cada encaixe, pergunto o que quebra ao
   escalar: N+1, hot path, acoplamento que vira gargalo. Anoto o failure mode, não só o caminho feliz.
6. **Entregue o mapa de estrutura ao @dev** — árvore relevante, pontos de integração com donos,
   recomendação REUSE/ADAPT/CREATE por peça, e os riscos de escala. Roteio o que for de outra camada
   ao especialista dono.

## Critério de pronto (DoD)

- [ ] Cada camada que a feature toca tem o ponto de integração exato identificado, com dono
- [ ] Cada peça tem decisão explícita REUSE/ADAPT/CREATE, com justificativa para CREATE
- [ ] Os pontos de integração têm o failure mode ao escalar anotado (teste do 10×)
- [ ] O mapa rastreia inteiramente à story — sem feature ou módulo inventado
- [ ] Frentes de outra camada (dados/UI/infra) foram roteadas ao especialista dono

## Falha / recuperação

- **A story é vaga demais para localizar o encaixe** → paro, registro a lacuna e devolvo ao @sm/@po.
  Não chuto a estrutura de uma feature que não entendo.
- **O codebase é desconhecido e sem documentação** → rodo `document-project` primeiro; analisar
  encaixe sobre um mapa que não existe gera recomendação errada.
- **A análise revela que a feature exige mudança estrutural cross-stack** → escalo para a task
  `architect-analyze-impact` antes de recomendar o encaixe.
- **A feature toca schema/DDL, UI ou infra** → defino a fronteira e o contrato, mas delego a
  implementação da camada ao dono (@data-engineer, @ux-design-expert, @devops).