chore: ignora graphify-out gerado
This commit is contained in:
@@ -0,0 +1,89 @@
|
||||
---
|
||||
layer: wiki
|
||||
type: Document
|
||||
tags: [projecto, modelo, organizacao, estrutura]
|
||||
title: Estrutura
|
||||
description: >-
|
||||
Este documento define a estrutura de pastas e ficheiros obrigatória para todos os projectos do ecossistema Descomplicar®…
|
||||
timestamp: 2026-05-13T11:27:31.572569+00:00
|
||||
---
|
||||
# ESTRUTURA.md — Standard de Hierarquia de Projectos
|
||||
|
||||
## Introdução
|
||||
Este documento define a estrutura de pastas e ficheiros obrigatória para todos os projectos do ecossistema Descomplicar®. A consistência da estrutura permite que agentes de IA e programadores transitem entre projectos com atrito zero.
|
||||
|
||||
## Hierarquia Base (Root)
|
||||
|
||||
```text
|
||||
/ (root)
|
||||
├── docs/ # Documentação específica do projecto
|
||||
│ ├── PLANS/ # Planos de acção e roadmaps específicos
|
||||
│ └── SPECS/ # Especificações técnicas e requisitos do projecto
|
||||
├── scripts/ # Scripts de automação local (opcional)
|
||||
├── tests/ # Testes globais ou de integração
|
||||
├── index.md # Navegação OKF — links only, minúsculas (Obsidian + Wayland)
|
||||
├── AGENTS.md # Contexto para agentes IA — 5W2H + relacionamentos (Wayland, Hermes, Claude, OpenCode)
|
||||
├── CLAUDE.md # Instruções específicas para Claude Code
|
||||
├── GEMINI.md # Instruções específicas para Gemini CLI
|
||||
├── STATUS.md # Estado actual — PDCA (Plan/Do/Check/Act)
|
||||
├── CHANGELOG.md # Histórico de versões e decisões
|
||||
├── MEMORY.md # Factos duráveis, decisões, workarounds (append-only)
|
||||
├── README.md # Visão geral humana — o que é, porquê existe
|
||||
├── desk.project # Ligação ao Desk CRM (JSON)
|
||||
└── ... # Ficheiros de código (src, backend, frontend, etc.)
|
||||
```
|
||||
|
||||
**Nota:** PROCs e RUNBOOKs NÃO residem aqui. Consultar `06-Operacoes/Procedimentos/` e `06-Operacoes/Runbooks/` no Hub — são a fonte de verdade centralizada.
|
||||
|
||||
## Definição de Directórios e Ficheiros Críticos
|
||||
|
||||
### 1. `/docs`
|
||||
Documentação que vive e morre com o projecto.
|
||||
- **PLANS/**: Documentos que descrevem "o que vamos fazer" neste projecto (ex: `PLANS/PLAN-MIGRACAO-DB.md`).
|
||||
- **SPECS/**: Definições técnicas, diagramas de arquitectura e contratos de API específicos.
|
||||
|
||||
### 2. Documentação Centralizada (Externo ao Projecto)
|
||||
Os procedimentos operacionais e manuais de manutenção não residem na pasta do projecto para evitar duplicação e garantir que todos seguem a versão mais recente (Single Source of Truth).
|
||||
|
||||
- **PROCs** no Hub em `06-Operacoes/Procedimentos/`
|
||||
- **Runbooks** no Hub em `06-Operacoes/Runbooks/`
|
||||
- **Quick References** no Hub em `06-Operacoes/Documentacao/Quick-Reference/`
|
||||
|
||||
**Nunca** criar pastas `docs/PROC` ou `docs/RUNBOOK` num projecto. A referência correcta é sempre o Hub.
|
||||
|
||||
---
|
||||
|
||||
### 3. Ficheiros de Governance de IA (`AGENTS.md`, `GEMINI.md`, `CLAUDE.md`)
|
||||
Servem para alinhar o comportamento dos agentes neste repositório. Devem conter regras de estilo, convenções de código e restrições de segurança específicas do projecto. Pelo menos `AGENTS.md` é obrigatório.
|
||||
|
||||
### 4. `MEMORY.md`
|
||||
**Obrigatório.** Deve ser actualizado no final de cada sessão.
|
||||
- Formato: Secções por data (ordem cronológica inversa).
|
||||
- Conteúdo: O que foi feito, problemas encontrados e o que ficou pendente.
|
||||
|
||||
### 4. `desk.project`
|
||||
Ficheiro JSON que mapeia o repositório local à tarefa ou projecto correspondente no Desk CRM.
|
||||
|
||||
## Regras de Nomenclatura
|
||||
- Pastas: `UPPERCASE` para categorias de documentação (`PLANS`, `SPECS`), `lowercase` para código.
|
||||
- Ficheiros: `kebab-case.md` (letras minúsculas e hífens).
|
||||
- Excepções: Ficheiros de sistema como `README.md`, `CHANGELOG.md` ou ficheiros de governance em `UPPERCASE`.
|
||||
|
||||
## Validação de Estrutura
|
||||
Um projecto é considerado "em conformidade" se contiver, no mínimo:
|
||||
1. `docs/` com as pastas `PLANS/` e `SPECS/` (mesmo que vazias).
|
||||
2. `AGENTS.md` com directrizes específicas do projecto.
|
||||
3. `MEMORY.md` com registo de sessões.
|
||||
4. `desk.project` com task_id válido no Desk CRM.
|
||||
|
||||
> **Validação automática:** Executar `scripts/validate-structure.sh` na raiz do projecto para verificar conformidade.
|
||||
|
||||
---
|
||||
|
||||
## Convenção para Pastas Hub (Sistemas e Aplicações)
|
||||
|
||||
Para pastas de documentação no Hub (`04-Stack/02.04-Sistemas/`, `04-Stack/02.05-Aplicações/`, etc.) aplica-se uma convenção própria:
|
||||
|
||||
→ Ver **`06-Operacoes/Procedimentos/Cross-Departamental/PROC-Estrutura-Pasta-Projecto.md`** (XDP-PRJ-001)
|
||||
|
||||
**Diferença principal:** pastas Hub não têm `docs/`, `scripts/` nem `tests/` — são documentação pura. O `AGENTS.md` contém o 5W2H do sistema e os relacionamentos com o ecossistema.
|
||||
Reference in New Issue
Block a user