Passive Docs Index (PDI)

Elimine o ponto de decisão de busca de documentação para assistentes de código AI

PDI cria um índice de documentação comprimido que está sempre disponível no seu CLAUDE.md, garantindo que assistentes de IA tenham acesso imediato à documentação de frameworks sem precisar decidir se devem buscá-la.

O Problema

Estudos mostram que assistentes de IA têm uma taxa de falha de 56% ao acionar busca de documentação - frequentemente não consultam documentação quando deveriam. Isso leva a:

• Código usando APIs deprecadas
• Padrões incorretos do pré-treinamento
• Erros de integração entre bibliotecas

Causa raiz: O "ponto de decisão" - quando o agente precisa decidir "devo buscar documentação?", frequentemente escolhe não buscar.

A Solução

PDI cria um contexto passivo - documentação que está sempre presente, eliminando o ponto de decisão. Em vez do AI decidir "devo consultar isso?", o índice de documentação relevante já está no contexto.

| Abordagem | Taxa de Trigger | Custo de Tokens | |-----------|-----------------|-----------------| | Skills | 44% | Variável | | PDI Index | 100% | ~4KB constante |

Início Rápido

# Instalar globalmente
bun add -g passive-docs-index
# ou
npm install -g passive-docs-index

# Inicializar no seu projeto
pdi init

# Adicionar documentação de frameworks
pdi add hono drizzle zod

# Verificar status
pdi status

Como Funciona

┌─────────────────────────────────────────────────────────────┐
│                        CLAUDE.md                            │
│  ┌───────────────────────────────────────────────────────┐  │
│  │ [Conteúdo existente do usuário]                       │  │
│  └───────────────────────────────────────────────────────┘  │
│  ┌───────────────────────────────────────────────────────┐  │
│  │ <!-- pdi:begin -->                                    │  │
│  │ [Índice Comprimido ~4KB]                              │  │
│  │ <!-- pdi:end -->                                      │  │
│  └───────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                    .claude-docs/                            │
│  ├── frameworks/     (docs de dependências externas)        │
│  ├── internal/       (padrões específicos do projeto)       │
│  └── config.json     (configuração PDI)                     │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼ (fallback)
┌─────────────────────────────────────────────────────────────┐
│                    MCP Tools                                │
│  Context7 → query-docs (quando docs locais insuficientes)   │
└─────────────────────────────────────────────────────────────┘

Exemplo de Índice no CLAUDE.md

<!-- pdi:begin - auto-generated by passive-docs-index, do not edit manually -->
[Framework Docs]|root:.claude-docs/frameworks
|CRITICAL:Prefer retrieval-led reasoning over pre-training-led reasoning
|CRITICAL:Read the relevant .mdx files BEFORE writing code that uses these libraries
|[email protected]|api:{app.mdx,context.mdx,routing.mdx,middleware.mdx}|patterns:{error-handling.mdx,validation.mdx}
|[email protected]|schema:{tables.mdx,relations.mdx}|queries:{select.mdx,insert.mdx}
|[email protected]|basics:{schemas.mdx,validation.mdx}|advanced:{transforms.mdx}

[Internal Patterns]|root:.claude-docs/internal
|CRITICAL:Follow these project-specific patterns for consistency
|database:{two-schema-pattern.mdx,feature-gating.mdx}
|conventions:{esm-imports.mdx,path-aliases.mdx}
<!-- pdi:end -->

<!-- MCP Fallback: Context7 for expanded queries
     hono=/honojs/hono, drizzle=/drizzle-team/drizzle-orm -->

Comandos

pdi init

Inicializa o PDI no seu projeto. Detecta dependências e cria a estrutura .claude-docs/.

pdi init                # Inicialização básica
pdi init --force        # Sobrescrever configuração existente
pdi init --no-detect    # Pular detecção de dependências
pdi init --internal     # Também criar estrutura para docs internos

Saída:

✓ Created .claude-docs/
✓ Created config.json
✓ Updated .gitignore

Detected dependencies:
  ├── [email protected]         → [email protected] docs available
  ├── [email protected]  → [email protected] docs available
  └── [email protected]          → [email protected] docs available

Run: pdi add hono drizzle zod

pdi add <frameworks...>

Adiciona documentação para frameworks específicos.

pdi add hono drizzle           # Adicionar múltiplos frameworks
pdi add zod --version 3.x      # Especificar versão
pdi add better-auth --force    # Sobrescrever docs existentes
pdi add react --minimal        # Apenas docs essenciais
pdi add vite --no-index        # Não atualizar índice no CLAUDE.md

Saída:

Fetching [email protected] docs...
  Source: Context7 (/honojs/hono)
  ✓ api/app.mdx (2.1KB)
  ✓ api/context.mdx (3.4KB)
  ✓ api/routing.mdx (2.8KB)
  Total: 7 files, 17KB

✓ Updated index in CLAUDE.md

pdi sync

Sincroniza documentação com as dependências do package.json.

pdi sync              # Sincronização interativa
pdi sync --yes        # Aceitar todas as mudanças automaticamente
pdi sync --check      # Apenas verificar, sem modificar
pdi sync --prune      # Remover docs de pacotes desinstalados

Saída:

Checking package.json...
  ├── hono: 4.9.12 → docs at 4.x (OK)
  ├── drizzle-orm: 0.44.6 → docs at 0.44 (OK)
  └── better-auth: 1.3.27 → docs at 1.2.x (UPDATE AVAILABLE)

Update better-auth docs? [y/N]

pdi status

Mostra o status atual do PDI.

pdi status

Saída:

PDI Status for my-project
═════════════════════════

Frameworks (3):
  ├── [email protected]      7 files  17KB  ✓ up-to-date
  ├── [email protected]  8 files  22KB  ✓ up-to-date
  └── [email protected]       4 files   9KB  ⚠ update available

Internal (2 categories):
  ├── database     3 files   8KB
  └── conventions  2 files   4KB

Index: 2.8KB / 4KB limit (70% used)
Total docs: 60KB / 80KB limit (75% of limit)

Last sync: 2026-02-02 16:00:00

pdi clean

Remove documentação órfã e otimiza o índice.

pdi clean              # Limpeza interativa
pdi clean --yes        # Remover sem confirmar
pdi clean --dry-run    # Mostrar o que seria removido

Saída:

Found orphan docs:
  └── .claude-docs/frameworks/lodash/ (not in package.json)

Remove orphan docs? [y/N] y
✓ Removed lodash/ (4 files, 8KB)

Index optimization:
  Before: 4.2KB
  After: 3.8KB
  Saved: 0.4KB (10%)

pdi list

Lista templates de frameworks disponíveis.

pdi list                      # Listar todos
pdi list --category backend   # Filtrar por categoria

pdi update [frameworks...]

Atualiza documentação para versões mais recentes.

pdi update              # Atualizar todos
pdi update hono drizzle # Atualizar específicos

pdi generate internal

Analisa código e gera documentação de padrões internos.

pdi generate internal                 # Gerar todos
pdi generate internal --category db   # Categoria específica
pdi generate internal --dry-run       # Preview
pdi generate internal --ai            # Usar AI para melhorar descrições

Frameworks Suportados

| Framework | Categoria | Versão | Library ID (Context7) | |-----------|-----------|--------|----------------------| | Hono | Backend | 4.x | /honojs/hono | | Drizzle ORM | Database | 0.44 | /drizzle-team/drizzle-orm | | Better Auth | Auth | 1.x | /better-auth/better-auth | | Zod | Validation | 4.x | /colinhacks/zod | | TanStack Query | Frontend | 5.x | /tanstack/query | | TanStack Router | Frontend | 1.x | /tanstack/router | | React | Frontend | 19.x | /facebook/react | | Vite | Build | 6.x | /vitejs/vite | | Vitest | Testing | 3.x | /vitest-dev/vitest | | Tailwind CSS | Styling | 4.x | /tailwindlabs/tailwindcss |

Estrutura do Projeto

your-project/
├── .claude-docs/
│   ├── config.json              # Configuração PDI
│   ├── frameworks/              # Docs de dependências externas
│   │   ├── hono/
│   │   │   ├── api/
│   │   │   │   ├── app.mdx
│   │   │   │   ├── context.mdx
│   │   │   │   ├── routing.mdx
│   │   │   │   └── middleware.mdx
│   │   │   └── patterns/
│   │   │       ├── error-handling.mdx
│   │   │       └── validation.mdx
│   │   ├── drizzle/
│   │   │   ├── schema/
│   │   │   ├── queries/
│   │   │   └── migrations/
│   │   └── zod/
│   │       ├── basics/
│   │       └── advanced/
│   └── internal/                # Padrões específicos do projeto
│       ├── database/
│       │   └── two-schema-pattern.mdx
│       ├── conventions/
│       │   └── esm-imports.mdx
│       └── workflows/
│           └── add-route.mdx
├── CLAUDE.md                    # Contém o índice comprimido
└── package.json

Configuração

O arquivo config.json controla o comportamento do PDI:

{
  "$schema": "https://pdi.dev/schema/config.json",
  "version": "1.0.0",
  "project": {
    "name": "my-project",
    "type": "backend"
  },
  "sync": {
    "lastSync": "2026-02-02T16:00:00Z",
    "autoSyncOnInstall": true
  },
  "frameworks": {
    "hono": {
      "version": "4.x",
      "source": "context7",
      "libraryId": "/honojs/hono",
      "lastUpdate": "2026-02-01T00:00:00Z",
      "files": 7
    }
  },
  "internal": {
    "enabled": true,
    "categories": ["database", "conventions"],
    "totalFiles": 5
  },
  "mcp": {
    "fallbackEnabled": true,
    "preferredProvider": "context7",
    "libraryMappings": {
      "hono": "/honojs/hono",
      "drizzle": "/drizzle-team/drizzle-orm"
    },
    "cacheHours": 168
  },
  "limits": {
    "maxIndexKb": 4,
    "maxDocsKb": 80,
    "maxFilesPerFramework": 20
  }
}

Opções de Configuração

| Campo | Descrição | Padrão | |-------|-----------|--------| | project.type | Tipo do projeto (backend/frontend/fullstack/library/cli) | auto-detectado | | sync.autoSyncOnInstall | Sincronizar automaticamente após npm install | true | | mcp.fallbackEnabled | Permitir fallback para MCP quando docs locais insuficientes | true | | mcp.cacheHours | Tempo de cache para queries MCP | 168 (1 semana) | | limits.maxIndexKb | Tamanho máximo do índice no CLAUDE.md | 4 | | limits.maxDocsKb | Tamanho máximo total dos docs | 80 |

Populando Documentação

PDI cria arquivos de documentação placeholder. Para popular com conteúdo real:

Via Claude (Recomendado)

Peça ao Claude para usar Context7 MCP para buscar e atualizar os docs:

Por favor, use Context7 para buscar documentação do Hono sobre routing
e atualize o arquivo em .claude-docs/frameworks/hono/api/routing.mdx

Manual

Edite os arquivos .mdx diretamente com seu conteúdo preferido.

Formato do Arquivo .mdx

---
# Part of Passive Docs Index for [email protected]
# Source: Context7 (/honojs/hono)
# Last updated: 2026-02-01
# Category: api
---

# Routing

## Overview

Hono uses a simple and intuitive routing system...

## Route Parameters

```typescript
app.get('/users/:id', (c) => {
  const id = c.req.param('id');
  return c.json({ id });
});

Common Patterns

...

## Boas Práticas

1. **Mantenha o índice abaixo de 4KB**: O índice deve ser escaneável rapidamente
2. **Total de docs abaixo de 80KB**: Detalhe suficiente sem sobrecarregar o contexto
3. **Alinhamento de versão**: Use `pdi sync` após `npm install` para manter docs atualizados
4. **Padrões internos**: Documente convenções específicas do projeto em `.claude-docs/internal/`
5. **Instruções CRITICAL**: Use para padrões que devem ser seguidos sem exceção

## Integração com MCP

PDI integra com Context7 MCP para fallback quando documentação local é insuficiente:

```markdown
<!-- MCP Fallback Protocol -->
<!--
When local docs in .claude-docs/ don't answer your question:
1. Query Context7: mcp__plugin_context7_context7__query-docs
2. Use the libraryId from config.json

Library IDs:
- hono: /honojs/hono
- drizzle: /drizzle-team/drizzle-orm

Only use MCP for:
- Edge cases not covered in local docs
- Very recent API changes
- Integration patterns between libraries
-->

API Programática

PDI também pode ser usado programaticamente:

import {
  readConfig,
  writeConfig,
  parseIndex,
  generateIndex,
  buildIndexSections,
  updateClaudeMdIndex,
  getTemplate,
  hasTemplate,
  listTemplates,
} from 'passive-docs-index';

// Ler configuração
const config = await readConfig('/path/to/project');

// Verificar se template existe
if (hasTemplate('hono')) {
  const template = getTemplate('hono');
  console.log(template.structure);
}

// Construir e atualizar índice
const sections = buildIndexSections(
  '.claude-docs/frameworks',
  '.claude-docs/internal',
  frameworksData,
  internalData
);

await updateClaudeMdIndex('/path/to/project', sections);

Por Que Não Skills?

Skills requerem que o AI tome uma decisão de trigger. Pesquisas mostram que este ponto de decisão tem alta taxa de falha. A abordagem passiva do PDI significa que o índice de documentação está sempre presente - nenhuma decisão necessária.

Comparação

| Aspecto | Skills | PDI | |---------|--------|-----| | Taxa de Trigger | 44% | 100% | | Custo de Tokens | Variável | ~4KB constante | | Decisão Requerida | Sim | Não | | Sempre em Contexto | Não | Sim |

Contribuindo

Contribuições são bem-vindas! Por favor:

1. Fork o repositório
2. Crie uma branch para sua feature (git checkout -b feature/nova-feature)
3. Commit suas mudanças (git commit -am 'Add nova feature')
4. Push para a branch (git push origin feature/nova-feature)
5. Abra um Pull Request

Adicionando Novos Templates

Para adicionar suporte a um novo framework, edite src/lib/templates.ts:

export const MEU_FRAMEWORK_TEMPLATE: FrameworkTemplate = {
  name: 'meu-framework',
  displayName: 'Meu Framework',
  version: '1.x',
  source: 'context7',
  libraryId: '/org/meu-framework',
  category: 'backend',
  priority: 'P1',
  description: 'Descrição do framework',
  structure: {
    basics: {
      'getting-started.mdx': {
        query: 'Query para Context7 sobre getting started',
        topics: ['setup', 'installation'],
      },
    },
  },
};

Roadmap

• [x] CLI básico (init, add, status, sync, clean)
• [x] Templates para 10 frameworks principais
• [x] Integração com Context7 MCP
• [ ] Comando pdi generate internal completo
• [ ] Hook para npm install / bun install
• [ ] Skills Claude (/pdi-analyze, /pdi-generate)
• [ ] Plugin para VS Code
• [ ] Dashboard web para visualização

Licença

MIT © 2026

Feito com ❤️ para melhorar a experiência de desenvolvimento com AI assistants.