Pular para o conteúdo principal

Caso de uso — Bootstrap de governança

Há uma janela curta no início de um repositório novo em que tudo é mais barato: criar pastas, decidir convenções, deixar placeholders para artefactos que ainda não existem. Passada essa janela, retrofitar governança custa o triplo. Este caso de uso aproveita-a: o MCP sabe que artefactos o manual identifica para cada capítulo (políticas, templates, registos, checklists), e o agente usa essa lista para gerar um scaffold coerente em minutos. O conteúdo dos artefactos fica em aberto — preencher é trabalho da equipa — mas o esqueleto deixa visível, desde o primeiro dia, o que falta.

Pré-requisitos​

  • MCP instalado.
  • Risk level alvo conhecido (L1 é típico no arranque; subir conforme o sistema cresce).

Fluxo​

1. Listar artefactos requeridos​

plan_sbd_toe_repo_governance(riskLevel, offset, limit)

Output esperado (campos): byChapter[] (os artefactos agrupados por capítulo, cada um {artefactId, chapterId, riskLevels[]}), totalArtefacts (o número de linhas capítulo↔artefacto), artefact_totals (distinct_count, os artefactos distintos, e chapter_relation_count, as linhas — nunca se somam linhas para contar artefactos), coverage e risk_level_effect. Os ids de artefacto têm a forma ART-<slug>-<hash>. A relação capítulo↔artefacto é uma projecção: não diz quem possui o artefacto nem obriga a produzi-lo. A resposta é paginada (offset / limit): percorrer todas as páginas antes de dar a lista por completa.

2. Passar o risk level​

Passar o riskLevel a plan_sbd_toe_repo_governance: a resposta declara o efeito do nível em risk_level_effect. Não há artefactos a eliminar por nível — nenhum capítulo é excluído; a aplicabilidade é graduada e o que muda é a exigência (ver sbd://toe/chapter-applicability/{riskLevel}).

3. Estruturar o repo​

Layout recomendado:

repo-root/
├── governance/
│   ├── 01-classificacao-aplicacoes/
│   │   ├── README.md                      # Refere ART-* + capítulo
│   │   └── classificacao.md                # Artefacto preenchido
│   ├── 02-requisitos-seguranca/
│   │   └── catalogo.md
│   ├── ...
├── policies/                              # (opcional) cópias adaptadas das policies do manual
├── AGENTS.md                              # Aponta ao SbD-ToE como guia
├── CLAUDE.md                              # Idem para Claude Code
└── .claude/skills/sbd-toe.md              # Skill canónica (de generate_sbd_toe_skill)

4. Scaffold automático​

Para cada artefacto devolvido:

<!-- governance/<chapter>/<artifact>.md -->

# <título>

> **Artefacto:** `ART-<slug>-<hash>`
> **Capítulo:** [<chapter>](https://www.securitybydesign.dev/sbd-toe/sbd-manual/<chapter>/intro)
> **Estado:** ⏳ pendente

## Propósito
<do que o MCP devolve para o artefacto>

## Conteúdo esperado
- ...

## Aprovação
- Owner: <role>
- Reviewers: <roles>

5. Inicializar a sessão de equipa​

Em AGENTS.md / CLAUDE.md, incluir bloco de inicialização:

## SbD-ToE

Este repositório segue o manual Security by Design — Theory of Everything.

- Risk level: L1
- Roles primários: developer, devops, appsec (rotativo)
- Skill: `.claude/skills/sbd-toe.md`
- Em qualquer sessão de design/implementação de segurança, inicializar:
  `setup_sbd_toe_agent(riskLevel="L1", projectRole="<role>")`

Disciplina de output​

  • O bootstrap gera placeholders — não preenche os artefactos. Cada artefacto requer trabalho de equipa.
  • Não declarar conformidade com base na existência de placeholders. Conformidade requer conteúdo preenchido + evidência.
  • Documentar o risk level assumido explicitamente em cada artefacto. Ao subir de L1 para L2, o capítulo 03 passa a listar os seus artefactos, e a lista por capítulo cresce, mas não aparecem artefactos novos. risk_level_effect declara que o nível filtra pouco, por desenho.

Skill / subagent — Claude Code​

.claude/agents/sbd-toe-bootstrap.md:

---
name: sbd-toe-bootstrap
description: Bootstrap inicial de governança SbD-ToE num repo novo — gera scaffold de artefactos por capítulo.
tools: Read, Write, Edit, Bash, mcp__sbd-toe__*
---

# Workflow

1. Perguntar risk_level alvo se não estiver explícito.
2. Chamar plan_sbd_toe_repo_governance.
3. Passar riskLevel a plan_sbd_toe_repo_governance e ler risk_level_effect (nenhum capítulo é excluído; paginar até ao fim).
4. Criar layout governance/<chapter>/<artifact>.md com placeholders.
5. Criar AGENTS.md + CLAUDE.md com bloco de inicialização.
6. Guardar a skill canónica via generate_sbd_toe_skill em .claude/skills/sbd-toe.md.
7. Reportar lista do que ficou criado + lista do que falta preencher.
8. Não inventar conteúdo de artefactos — só scaffold.

Quando re-correr​

TriggerAcção
Risk level sobe (L1→L2 ou L2→L3)Re-correr — a exigência muda; não apagar nada.
Upgrade do MCP serverRe-correr generate_sbd_toe_skill() para refrescar a skill.
Adição de cross-check normativo posterior ao snapshot do MCPAdicionar manualmente a partir do manual web até nova publicação — confirmar a cobertura em sbd://toe/version (ver content lag).

Anti-patterns​

  • ❌ Preencher os placeholders automaticamente com texto genérico — pior que vazio.
  • ❌ Apagar artefactos "que não vão ser usados" — esconde o gap.
  • ❌ Marcar artefactos como "concluídos" sem revisão humana.

Relacionado​