Exemplos de Bundles OKF

Oito bundles prontos pra produção em domínios diferentes. Cada um passa nas três regras de conformance, tem cross-links funcionais e estrutura de pastas que você de fato usaria.

Opinião: bundle bom é bundle que alguém abre o index.md e entende o domínio em 30 segundos. Se precisa de manual pra navegar, a estrutura tá errada.

1. Aplicação SaaS

Time de produto documentando métricas de receita, assinaturas e playbooks operacionais. Cenário: o time financeiro quer saber como o MRR é calculado e seus agentes precisam responder “por que a receita caiu?”

Estrutura de pastas

saas-app/
├── index.md
├── log.md
├── metrics/
│   ├── index.md
│   ├── monthly-recurring-revenue.md
│   └── churn-rate.md
├── tables/
│   ├── index.md
│   └── subscriptions.md
└── playbooks/
    ├── index.md
    └── revenue-review.md

`metrics/monthly-recurring-revenue.md`

---
type: Metric
title: Monthly Recurring Revenue
description: Receita recorrente de assinaturas normalizada para período mensal.
resource: dashboard://revenue/mrr
tags: [revenue, saas, finance]
timestamp: 2026-06-21T00:00:00Z
---

# Definição

MRR é a receita recorrente previsível gerada por assinaturas ativas na
[tabela de assinaturas](/tables/subscriptions.md). Normaliza planos anuais,
trimestrais e mensais para uma cifra mensal única.

Inclui assinaturas ativas com cobrança recorrente. Exclui taxas de setup,
reembolsos e cobranças por uso (a não ser que normalizadas em plano recorrente).

# Fórmula

MRR = Σ(valor_mensal_assinatura_ativa) ARR = MRR × 12


# Exemplos

```sql
SELECT SUM(monthly_amount_usd) AS mrr
FROM analytics.subscriptions
WHERE status = 'active'
  AND billing_type = 'recurring';

Relacionados

Churn Rate usa MRR como denominador
Subscriptions é a tabela fonte

Citações

[1] Dashboard de receita


O SQL é a fonte de verdade. Sem ambiguidade sobre "o que conta como recorrente" — a query responde. Repare que `churn-rate.md` linka de volta — o bundle é um grafo, não só uma árvore de pastas.

---

## 2. Data Warehouse

Time de dados documentando tabelas BigQuery, datasets e métricas. Cenário: analista novo chega e precisa entender schemas, joins e de onde saem os números de receita sem incomodar ninguém no Slack.

### Estrutura de pastas

data-warehouse/ ├── index.md ├── log.md ├── datasets/ │ ├── index.md │ └── sales.md ├── tables/ │ ├── index.md │ ├── orders.md │ └── customers.md └── metrics/ ├── index.md └── gross-revenue.md


### `tables/orders.md`

```markdown
---
type: BigQuery Table
title: Orders
description: Uma linha por pedido finalizado em todos os canais.
resource: https://console.cloud.google.com/bigquery?p=acme&d=sales&t=orders
tags: [sales, orders, revenue]
timestamp: 2026-06-21T00:00:00Z
---

# Schema

| Coluna | Tipo | Descrição |
|--------|------|-----------|
| `order_id` | STRING | Identificador único do pedido |
| `customer_id` | STRING | FK para [customers](/tables/customers.md) |
| `total_usd` | NUMERIC | Total do pedido em dólares |
| `placed_at` | TIMESTAMP | Quando o cliente enviou o pedido |
| `channel` | STRING | `web`, `mobile`, `pos` |

# Joins

Join com [customers](/tables/customers.md) via `customer_id`.

# Exemplos

```sql
SELECT customer_id, SUM(total_usd) AS lifetime_value
FROM sales.orders
GROUP BY customer_id
ORDER BY lifetime_value DESC
LIMIT 100;

Relacionados

Parte do dataset sales
Usado pela métrica Gross Revenue

Citações

[1] Tabela BigQuery


Tabelas com schema são o que faz a mágica. O agente lê as descrições das colunas, entende as FKs e escreve joins corretos sem adivinhar.

---

## 3. Aplicação Laravel

Time de dev documentando models Eloquent, rotas, policies e jobs de background. Cenário: dev novo (ou agente de código) precisa entender o que o User model faz, quais rotas o expõem e o que acontece quando um perfil é atualizado.

### Estrutura de pastas

laravel-app/ ├── index.md ├── log.md ├── models/ │ ├── index.md │ └── user.md ├── routes/ │ ├── index.md │ └── api-users.md ├── policies/ │ ├── index.md │ └── user-policy.md └── jobs/ ├── index.md └── sync-stripe-customer.md


### `models/user.md`

```markdown
---
type: Laravel Model
title: User
description: Model de conta autenticada para clientes e operadores internos.
resource: repo://app/Models/User.php
tags: [laravel, model, authentication]
timestamp: 2026-06-21T00:00:00Z
---

# Responsabilidades

O User model representa uma conta autenticada. É dono de recursos voltados
ao cliente (pedidos, assinaturas, API keys) e gerencia autenticação via
Laravel Sanctum.

# Schema

| Coluna | Tipo | Descrição |
|--------|------|-----------|
| `id` | BIGINT | Primary key |
| `name` | VARCHAR | Nome de exibição |
| `email` | VARCHAR | Email de login (unique) |
| `role` | ENUM | `customer`, `operator`, `admin` |
| `stripe_id` | VARCHAR | Stripe customer ID (nullable) |
| `created_at` | TIMESTAMP | Criação da conta |

# Relacionamentos

- `hasMany` Orders
- `hasOne` Subscription
- `belongsToMany` Teams

# Relacionados

- Protegido pela [user policy](/policies/user-policy.md)
- Exposto via [rota API users](/routes/api-users.md)
- Sincronizado com Stripe pelo [job de sync](/jobs/sync-stripe-customer.md)

# Citações

[1] [Arquivo fonte](repo://app/Models/User.php)

Repare na convenção resource: repo:// — aponta para o arquivo no codebase. Qualquer agente resolve isso e abre o fonte real. E a seção “Relacionados” tece o grafo: model → policy → rota → job. Um conceito, quatro conexões.

4. Site WordPress

Agência documentando custom post types, taxonomias, campos ACF e templates. Cenário: freelancer herda o projeto ou agente precisa entender a arquitetura de conteúdo antes de mexer.

Estrutura de pastas

wordpress-site/
├── index.md
├── log.md
├── post-types/
│   ├── index.md
│   └── product.md
├── taxonomies/
│   ├── index.md
│   └── product-category.md
├── acf/
│   ├── index.md
│   └── product-fields.md
└── templates/
    ├── index.md
    └── single-product.md

`post-types/product.md`

---
type: WordPress Post Type
title: Product
description: Custom post type para gerenciar landing pages de produtos e catálogo.
resource: wp-admin/edit.php?post_type=product
tags: [wordpress, post-type, content, ecommerce]
timestamp: 2026-06-21T00:00:00Z
---

# Registro

Registrado em `functions.php` via `register_post_type('product', ...)`.
Suporta title, editor, thumbnail, excerpt e custom fields.

# Features

- Publicamente consultável com archive em `/products/`
- Template single: [single-product](/templates/single-product.md)
- Categorizado por [Product Category](/taxonomies/product-category.md)
- Enriquecido com grupo ACF [Product Fields](/acf/product-fields.md)

# Schema

| Campo | Fonte | Descrição |
|-------|-------|-----------|
| `post_title` | Core | Nome do produto |
| `post_content` | Core | Descrição longa |
| `post_excerpt` | Core | Descrição curta para cards |
| `featured_image` | Core | Imagem hero |
| `price` | ACF | Preço de exibição |
| `sku` | ACF | Código de estoque |

# Relacionados

- Template: [single-product](/templates/single-product.md)
- Taxonomia: [Product Category](/taxonomies/product-category.md)
- Campos: [Product Fields](/acf/product-fields.md)

# Citações

[1] [WP Admin](wp-admin/edit.php?post_type=product)

O modelo de conteúdo do WordPress é notoriamente espalhado entre CPTs, taxonomias, ACF e templates. Um bundle OKF conecta os quatro. Um agente lendo isso sabe exatamente o que “Product” é sem fazer grep no functions.php.

5. Documentação de API

Bundle para documentar uma REST API com conhecimento contextual. Não substitui OpenAPI — responde “o que acontece quando você usa errado” e “por que esse endpoint existe.”

Estrutura de pastas

api-docs/
├── index.md
├── log.md
├── endpoints/
│   ├── index.md
│   ├── create-customer.md
│   └── list-customers.md
├── schemas/
│   ├── index.md
│   └── customer.md
└── errors/
    ├── index.md
    └── rate-limit.md

`endpoints/create-customer.md`

---
type: API Endpoint
title: Create Customer
description: Cria um novo registro de cliente e retorna o objeto criado.
resource: https://api.example.com/v1/customers
tags: [api, customers, write]
timestamp: 2026-06-21T00:00:00Z
---

# Request

```http
POST /v1/customers
Content-Type: application/json
Authorization: Bearer {token}

Aceita payload conforme o schema Customer.

{
  "name": "Jane Doe",
  "email": "jane@example.com",
  "segment": "enterprise"
}

Response

Retorna 201 Created com o objeto completo incluindo id e created_at gerados pelo servidor.

Erros

Status	Descrição
400	Erro de validação — campos obrigatórios faltando
409	Email já existe
429	Rate limit excedido

Relacionados

Schema: Customer
Erro: Rate Limit

Citações

[1] Referência da API


A tabela de erros é a seção de maior valor. "O que dá errado e como resolver" é exatamente o que um agente (ou dev frustrado às 2h da manhã) precisa.

---

## 6. Conhecimento da Empresa

Time de operações documentando equipes, políticas, sistemas e playbooks de escalação. Cenário: agente de suporte com IA precisa saber a política de reembolso, quem é dono do billing e quando escalar — de uma fonte canônica.

### Estrutura de pastas

company-knowledge/ ├── index.md ├── log.md ├── teams/ │ ├── index.md │ └── support.md ├── policies/ │ ├── index.md │ └── refunds.md ├── systems/ │ ├── index.md │ └── billing.md └── playbooks/ ├── index.md └── incident-response.md


### `policies/refunds.md`

```markdown
---
type: Policy
title: Política de Reembolso
description: Regras que os times de suporte e billing usam ao avaliar pedidos de reembolso.
resource: docs://policies/refunds
tags: [support, billing, policy]
timestamp: 2026-06-21T00:00:00Z
---

# Propósito

Define quando o suporte pode aprovar reembolso sozinho, quando precisa de
revisão do billing, e quais casos devem ser escalados para gestão.

# Matriz de Decisão

| Condição | Ação | Aprovador |
|----------|------|-----------|
| Até 14 dias, sem uso | Aprovar automaticamente | Agente de suporte |
| Até 14 dias, com uso | Pro-rata e reembolsar | Líder de suporte |
| 15-30 dias | Reembolso parcial (50%) | Time de billing |
| Mais de 30 dias | Negar (exceto casos excepcionais) | VP Suporte |
| Chargeback/disputa | Escalar imediatamente | [Incident Response](/playbooks/incident-response.md) |

# Processo

1. Verificar assinatura ativa no [sistema de billing](/systems/billing.md).
2. Checar métricas de uso no dashboard de analytics.
3. Aplicar a matriz de decisão acima.
4. Processar reembolso via Stripe (parcial ou total).
5. Registrar resultado no ticket para auditoria.

# Relacionados

- Executado pelo: [Time de suporte](/teams/support.md)
- Usa: [Sistema de Billing](/systems/billing.md)
- Escala para: [Incident Response](/playbooks/incident-response.md)

# Citações

[1] [Fonte da política](docs://policies/refunds)

Esse é o tipo de doc que torna um agente de suporte com IA realmente útil. A matriz de decisão é inequívoca — o agente lê, aplica as regras, e ou processa o reembolso ou escala.

7. Contexto de Agente IA

Bundle que define o que um agente pode e não pode fazer. Sistemas que ele acessa, ferramentas que pode chamar, procedimentos que deve seguir e limites que nunca pode cruzar. Esse é o bundle OKF que o agente lê sobre ele mesmo.

Estrutura de pastas

ai-agent-context/
├── index.md
├── log.md
├── systems/
│   ├── index.md
│   └── billing.md
├── tools/
│   ├── index.md
│   └── stripe.md
├── playbooks/
│   ├── index.md
│   └── support-triage.md
└── constraints/
    ├── index.md
    └── agent-safety-rules.md

`constraints/agent-safety-rules.md`

---
type: Constraint
title: Regras de Segurança do Agente
description: Limites operacionais que o agente IA deve seguir antes de usar ferramentas ou alterar sistemas voltados ao cliente.
resource: docs://agent-context/safety-rules
tags: [agent, safety, constraint, guardrails]
timestamp: 2026-06-21T00:00:00Z
---

# Regras Fundamentais

1. **Ler antes de agir.** Sempre ler conceitos relevantes de sistema,
   ferramenta e playbook antes de tomar qualquer ação.
2. **Sem ações destrutivas sem aprovação.** Não alterar dados de billing,
   processar reembolsos, enviar mensagens externas ou modificar configurações
   de produção sem aprovação humana explícita.
3. **Sem exfiltração de dados.** Nunca compartilhar PII de clientes, dados
   de pagamento ou informações internas com terceiros ou em logs.
4. **Consciência de escopo.** Usar apenas ferramentas listadas neste bundle.
   Não tentar acessar sistemas não documentados aqui.
5. **Falhar com segurança.** Se incerto sobre o impacto de uma ação, escalar
   para humano em vez de prosseguir.

# Ações Proibidas

- Processar reembolsos ou créditos
- Modificar planos de assinatura
- Enviar emails para clientes em nome da empresa
- Acessar bancos de dados de produção diretamente
- Compartilhar API keys, tokens ou credenciais

# Gatilhos de Escalação

Escalar para humano imediatamente quando:
- Cliente expressa intenção de se machucar ou machucar outros
- Ameaças legais ou consultas regulatórias
- Suspeita de comprometimento de conta
- Ação afetaria mais de um cliente

# Relacionados

- Se aplica a: [Ferramenta Stripe](/tools/stripe.md), [Sistema de Billing](/systems/billing.md)
- Contexto para: [Triagem de Suporte](/playbooks/support-triage.md)

# Citações

[1] [Fonte das regras](docs://agent-context/safety-rules)

Esse é o meta-exemplo — um bundle OKF descrevendo os próprios limites do agente. O agente lê esse bundle, descobre quais ferramentas existem, o que pode fazer e o que exige escalação. Sem ginástica de system prompt. Só arquivos que ele pode cat.

8. Site Astro

Time de desenvolvimento documentando pages, componentes, content collections e integrações de um site Astro. Cenário: dev ou agente de código precisa entender o roteamento, o fluxo de dados e como o conteúdo chega à página renderizada.

Estrutura de pastas

astro-site/
├── index.md
├── log.md
├── pages/
│   ├── index.md
│   ├── docs-slug.md
│   └── blog-index.md
├── components/
│   ├── index.md
│   └── header.md
├── collections/
│   ├── index.md
│   ├── docs.md
│   └── blog.md
└── integrations/
    ├── index.md
    ├── starlight.md
    └── sitemap.md

`pages/docs-slug.md`

---
type: Astro Page
title: Docs Slug
description: Rota dinâmica que renderiza páginas de documentação a partir da content collection docs.
resource: repo://src/pages/docs/[...slug].astro
tags: [astro, page, routing, docs]
timestamp: 2026-06-21T00:00:00Z
---

# Roteamento

Rota dinâmica file-based em `src/pages/docs/[...slug].astro`. Usa
`getStaticPaths()` para gerar uma página por entrada na
[collection docs](/collections/docs.md).

# Fluxo de Dados

1. `getStaticPaths()` chama `getCollection('docs')` para buscar todas as entradas.
2. O `slug` de cada entrada vira o path da URL (`/docs/{slug}`).
3. A página renderiza o markdown compilado via `entry.render()`.

# Exemplos

```astro
---
import { getCollection } from 'astro:content';
import DocsLayout from '../../layouts/DocsLayout.astro';

export async function getStaticPaths() {
  const docs = await getCollection('docs');
  return docs.map(entry => ({
    params: { slug: entry.slug },
    props: { entry },
  }));
}

const { entry } = Astro.props;
const { Content } = await entry.render();
---
<DocsLayout title={entry.data.title}>
  <Content />
</DocsLayout>

Relacionados

Collection: Docs
Componente: Header (renderizado no layout)

Citações

[1] Documentação de routing do Astro


### `collections/docs.md`

```markdown
---
type: Content Collection
title: Docs
description: Collection de documentação com validação de frontmatter via schema Zod.
resource: repo://src/content/docs/
tags: [astro, collection, content, docs]
timestamp: 2026-06-21T00:00:00Z
---

# Schema

Definido em `src/content.config.ts` usando `defineCollection` + Zod do Astro:

```typescript
import { defineCollection, z } from 'astro:content';

const docs = defineCollection({
  type: 'content',
  schema: z.object({
    title: z.string(),
    description: z.string().optional(),
    order: z.number().default(999),
    draft: z.boolean().default(false),
  }),
});

export const collections = { docs };

Campos do Frontmatter

Campo	Tipo	Obrigatório	Descrição
`title`	string	sim	Título da página
`description`	string	não	Meta description para SEO
`order`	number	não	Ordem na sidebar (padrão: 999)
`draft`	boolean	não	Excluído do build de produção se true

Diretório

Arquivos ficam em src/content/docs/. Subdiretórios criam slugs aninhados (ex: guides/getting-started.md → /docs/guides/getting-started).

Relacionados

Renderizado por: Página Docs Slug

Citações

[1] Content collections do Astro


As abstrações do Astro — pages, components, collections, integrations — mapeiam perfeitamente para conceitos OKF. O fluxo de dados de collection → page → component fica explícito nos cross-links. Um agente lendo esse bundle entende a arquitetura sem abrir um único arquivo `.astro`.

---

## Padrões em todos os oito bundles

1. **`type` é específico do domínio.** Não existe lista fixa. Use `Metric`, `BigQuery Table`, `Laravel Model`, `WordPress Post Type`, `Astro Page`, `Constraint` — o que seu time de fato chama essas coisas.

2. **Cross-links são generosos.** Se um conceito referencia outro, linke. Cada bundle acima é um grafo, não só uma pasta. O bundle Laravel tem 4 conceitos com 8+ cross-links entre eles.

3. **`index.md` é um mapa, não uma lixeira.** Uma linha por item. Link direto + descrição. Zero preâmbulo.

4. **Campos extras no frontmatter são livres.** A spec permite qualquer chave adicional. `method`, `severity`, `queue` — adicione o que o consumidor precisar pra filtrar.

5. **`# Citations` no final.** Links externos que validam o conteúdo. Agentes usam pra verificar. Humanos usam pra aprofundar.

6. **Body é estruturado.** Headings, tabelas, blocos de código. Mais estrutura = melhor retrieval por agentes. Parágrafos de prosa são ruído.

7. **Um conceito por arquivo.** Nunca misture responsabilidades. A política de reembolso não fica dentro do doc do time de suporte — tem seu próprio arquivo com seus próprios cross-links.

8. **O campo `resource` ancora na realidade.** Aponta pro recurso real — uma tabela BigQuery, um arquivo no GitHub, um dashboard Stripe, uma URL de admin. O conceito descreve; o resource É.