Protocolo de Estrutura de Dados (DSP)

Agentes de codificação de LLM perdem contexto entre tarefas. Em bases de código grandes, eles gastam a maior parte de seus tokens em "orientação" — descobrindo onde as coisas estão, o que depende do quê e o que é seguro mudar. O DSP resolve isso externalizando o mapa estrutural do projeto em um grafo persistente e consultável, armazenado em um diretório .dsp/ ao lado do código.

DSP NÃO é documentação para humanos e NÃO é um dump de AST. Ele captura três coisas: significado (por que uma entidade existe), limites (o que ela importa e expõe) e razões (por que cada conexão existe). Isso é suficiente para um agente navegar, refatorar e gerar código sem carregar toda a árvore de origem na janela de contexto.

Quando Usar

Use esta habilidade quando:

• O projeto possui um diretório .dsp/ (DSP já está configurado)
• O usuário pede para configurar o DSP, inicializar ou mapear a estrutura de um projeto
• Criando, modificando ou excluindo arquivos de código em um projeto rastreado pelo DSP (para manter o grafo atualizado)
• Navegando na estrutura do projeto, entendendo dependências ou encontrando módulos específicos
• O usuário menciona DSP, dsp-cli, .dsp ou mapeamento de estrutura
• Realizando análise de impacto antes de uma refatoração ou substituição de dependência

Conceitos Principais

Código = grafo

O DSP modela a base de código como um grafo direcionado. Nós são entidades, arestas são importações e compartilhamentos/exportações.

Existem dois tipos de entidades:

• Objeto: qualquer "coisa" que não seja uma função (módulo/arquivo/classe/configuração/recurso/dependência externa)
• Função: uma função/método/handler/pipeline exportado

Identidade por UID, não por caminho de arquivo

Cada entidade recebe um UID estável: obj-<8hex> para objetos, func-<8hex> para funções. Caminhos de arquivo são atributos que podem mudar; UIDs sobrevivem a renomeações, movimentações e reformatações.

Para entidades dentro de um arquivo, o UID é ancorado com um marcador de comentário no código-fonte:

// @dsp func-7f3a9c12
export function calculateTotal(items) { ... }

# @dsp obj-e5f6g7h8
class UserService:

Toda conexão tem um "porquê"

Quando uma importação é registrada, o DSP armazena uma breve razão explicando por que essa dependência existe. Isso fica no índice reverso exports/ da entidade importada. Um grafo de dependência sem razões diz o que importa o quê; razões dizem o que é seguro mudar e quem vai quebrar.

Formato de armazenamento

Cada entidade recebe um pequeno diretório sob .dsp/:

.dsp/
├── TOC                        # ordered list of all entity UIDs from root
├── obj-a1b2c3d4/
│   ├── description            # source path, kind, purpose (1-3 sentences)
│   ├── imports                # UIDs this entity depends on (one per line)
│   ├── shared                 # UIDs of public API / exported entities
│   └── exports/               # reverse index: who imports this and why
│       ├── <importer_uid>     # file content = "why" text
│       └── <shared_uid>/
│           ├── description    # what is exported
│           └── <importer_uid> # why this specific export is imported
└── func-7f3a9c12/
    ├── description
    ├── imports
    └── exports/

Tudo é texto puro. Comparável. Revisável. Nenhum banco de dados é necessário.

Cobertura completa de importação

Todo arquivo ou artefato que é importado em qualquer lugar deve ser representado em .dsp como um Objeto — código, imagens, estilos, configurações, JSON, wasm, tudo. Dependências externas (pacotes npm, stdlib, etc.) são registradas como kind: external, mas seus internos nunca são analisados.

Como Funciona

Configuração Inicial

A habilidade depende de um script CLI Python autônomo dsp-cli.py. Se ele estiver faltando no projeto, baixe-o:

curl -O https://raw.githubusercontent.com/k-kolomeitsev/data-structure-protocol/main/skills/data-structure-protocol/scripts/dsp-cli.py

Requer Python 3.10+. Todos os comandos usam python dsp-cli.py --root <project-root> <command>.

Inicialização (mapeamento inicial)

Se .dsp/ estiver vazio, percorra o projeto a partir do(s) ponto(s) de entrada raiz via DFS nas importações:

1. Identifique os pontos de entrada raiz (package.json principal, ponto de entrada do framework, main.py, etc.)
2. Documente o arquivo raiz: create-object, create-function para cada exportação, create-shared, add-import para todas as dependências
3. Pegue a primeira importação não externa, documente-a completamente, desça em suas importações
4. Volte quando não houver mais importações locais não visitadas; continue até que todos os arquivos alcançáveis sejam documentados
5. Dependências externas: create-object --kind external, adicione ao TOC, mas nunca desça em node_modules/site-packages/etc.

…