Skip to content

README_PT.md

Latest commit

 

History

History
341 lines (241 loc) · 15.5 KB

README_PT.md

File metadata and controls

341 lines (241 loc) · 15.5 KB
Raw

🧰 AI Development Context Framework

Especificações, guardrails e memória de projeto para Agents de programação.

License: MIT Markdown Claude Code Edition Stars

Files Guardrails Triage Sync


🧭  Seu Agent de programação continua perdendo a intenção do produto, as decisões de arquitetura e o contexto das tarefas entre sessões?
📚  Um projeto pequeno precisa de uma estrutura leve, enquanto um maior exige especificações e transições de contexto duradouras?
🔒  Você quer que o Agent mantenha o progresso livremente e proteja as decisões que exigem aprovação?

✨ Transforme uma conversa de produto em um sistema vivo de contexto para Agents de programação.

Conversar → especificar → inicializar → construir → manter o contexto


🧩 Edições · ✨ Destaques · 🗺 Fluxo · 📦 Arquivos · ⚡ Instalação · 🚀 Uso · 🛡 Princípios · 🎬 Exemplo · 📂 Estrutura · 📌 Notas

English · 简体中文 · Español · Deutsch · 日本語 · Русский · Português · 한국어

🧩 Escolha uma edição

Full Lite
Skills spec-gen, project-init, readme-craft spec-gen-lite, project-init-lite
Arquivos do projeto 3 arquivos principais, até 9 quando acionados 3 arquivos principais
Modelo de tarefas Fila priorizada, cabeçalhos de triagem, problemas, decisões e transições Fila por fases com dimensionamento [S/M/L/XL]
Melhor opção Trabalho com vários módulos, projetos longos, várias sessões ou transições em equipe Projetos individuais focados, protótipos e ciclos curtos de entrega
Fonte de instalação skills/ lite/skills/

As duas edições ficam neste repositório. Instale apenas uma edição em cada ambiente de programação para manter claros os dois pares de gatilhos de Skill que se sobrepõem.

✨ Três Skills, um framework

Skill Entrada Saída Lugar no fluxo
spec-gen Conversa de produto e restrições Um SPEC.md estruturado Primeiro: definir o produto
project-init Um SPEC.md existente Arquivos de orientação e gestão do projeto Segundo: preparar o ambiente de programação
readme-craft Fatos do repositório e público Um README.md de projeto bem estruturado Independente: explicar publicamente o projeto

O caminho principal de desenvolvimento usa spec-gen seguido de project-init. readme-craft é um Skill de documentação independente incluído no mesmo repositório.

🗺 Fluxo de trabalho

flowchart LR
    A([Conversar sobre o produto]) --> B[spec-gen]
    B --> C[SPEC.md]
    C --> D[project-init]
    D --> E[CLAUDE.md]
    D --> F[TODO.md]
    D -. quando necessário .-> G[ARCHITECTURE · SCHEMA · DESIGN]
    E --> H([Agent de programação])
    F --> H
    G --> H
    H -. primeiro problema .-> I[ISSUES.md]
    H -. primeira decisão .-> J[DECISIONS.md]
    H -. transição entre sessões .-> K[PROGRESS.md]
    H --> L([Construir com contexto])

    M([Fatos do repositório]) --> N[readme-craft]
    N --> O[README.md]

    style A fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px,color:#000
    style B fill:#DBEAFE,stroke:#3B82F6,stroke-width:2px,color:#000
    style C fill:#EDE9FE,stroke:#8B5CF6,stroke-width:2px,color:#000
    style D fill:#DBEAFE,stroke:#3B82F6,stroke-width:2px,color:#000
    style E fill:#F1F5F9,stroke:#64748B,stroke-width:1px,color:#000
    style F fill:#F1F5F9,stroke:#64748B,stroke-width:1px,color:#000
    style G fill:#F8FAFC,stroke:#94A3B8,stroke-width:1px,stroke-dasharray:4 4,color:#000
    style H fill:#DCFCE7,stroke:#22C55E,stroke-width:2px,color:#000
    style I fill:#FEF2F2,stroke:#EF4444,stroke-width:1px,stroke-dasharray:4 4,color:#000
    style J fill:#FFFBEB,stroke:#F59E0B,stroke-width:1px,stroke-dasharray:4 4,color:#000
    style K fill:#F0FDF4,stroke:#22C55E,stroke-width:1px,stroke-dasharray:4 4,color:#000
    style L fill:#DCFCE7,stroke:#22C55E,stroke-width:2px,color:#000
    style M fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px,color:#000
    style N fill:#DBEAFE,stroke:#3B82F6,stroke-width:2px,color:#000
    style O fill:#EDE9FE,stroke:#8B5CF6,stroke-width:2px,color:#000
Loading

project-init lê o SPEC e decide quanta estrutura o projeto precisa. Ele também grava regras de manutenção em linguagem natural no CLAUDE.md. Um Agent que siga essas regras pode criar arquivos com estado quando ocorrer o primeiro gatilho real; nenhum hook de execução impõe esse comportamento.

📦 O que é gerado

Arquivos principais

Arquivo Origem Finalidade
SPEC.md spec-gen Escopo do produto, módulos, restrições, necessidades de dados e limites do MVP
CLAUDE.md project-init Ponto de entrada do Agent, permissões, mapa do repositório e regras de automação
TODO.md project-init Fila priorizada com uma seção focada na tarefa atual

Adicionados quando o SPEC exige

Arquivo Gatilho Finalidade
ARCHITECTURE.md Três ou mais módulos funcionais Estrutura do sistema, dependências, interfaces e fluxo de dados
SCHEMA.md Um banco de dados ou modelo de dados complexo Entidades, campos, restrições, índices e migrações
DESIGN.md Uma interface de usuário Sistema visual, componentes, fluxos, estados e comportamento responsivo

Criados durante o desenvolvimento

Arquivo Primeiro gatilho Finalidade
ISSUES.md Um bug, problema técnico, limitação ou pergunta em aberto Acompanhamento estruturado de problemas com estados e IDs de módulo
DECISIONS.md Uma escolha técnica ou de arquitetura Registro de decisões, opções rejeitadas e nível de reversibilidade
PROGRESS.md A primeira transição entre sessões Fase atual, bloqueios, marcos e ponto de retomada

O framework começa com três arquivos e pode crescer até nove. Cada arquivo adicional tem um gatilho concreto.

⚡ Instalação

Estas instruções instalam a edição Full. Para a configuração de três arquivos principais, use o guia de instalação da Lite.

Passe esta instrução ao Claude Code:

Remova os cinco diretórios gerenciados de Skills Full e Lite do escopo de destino e depois instale os três Skills Full a partir de https://github.com/okht/ai-dev-context-framework/tree/main/skills.

🛠️ Instalação manual

Clone o repositório:

git clone --depth=1 https://github.com/okht/ai-dev-context-framework.git

Instale globalmente para o Claude Code e limpe os Skills Lite gerenciados:

bash ai-dev-context-framework/scripts/sync-skills.sh full

Instale no projeto atual e limpe os Skills Lite gerenciados:

mkdir -p .claude/skills
rm -rf .claude/skills/spec-gen .claude/skills/project-init .claude/skills/readme-craft .claude/skills/spec-gen-lite .claude/skills/project-init-lite
cp -r ai-dev-context-framework/skills/* .claude/skills/

Inicie um novo turno do Claude Code após a instalação para atualizar o índice de Skills.

Para desenvolver neste repositório, o script de sincronização incluído copia os diretórios atuais de skills/ para ~/.claude/skills/:

bash scripts/sync-skills.sh full

O script de sincronização remove os cinco diretórios gerenciados de Skills Full e Lite e depois copia a edição Full selecionada. Os outros Skills globais permanecem no lugar. Revise o script e o destino antes de executá-lo.

Outras ferramentas de programação com IA podem usar diretamente as instruções e os modelos Markdown. A descoberta de Skills e a sintaxe de invocação dependem do host.

🚀 Uso

1. Transforme a conversa em um SPEC

/spec-gen

Ou peça com linguagem natural:

Transforme nossa conversa de produto em um SPEC estruturado.

spec-gen grava SPEC.md, cobrindo visão geral do produto, módulos de funcionalidades, requisitos não funcionais, necessidades de dados, restrições técnicas, escopo do MVP e glossário.

2. Inicialize o contexto do projeto

/project-init

project-init verifica se SPEC.md existe, cria os arquivos principais, avalia arquivos condicionais e incorpora regras de manutenção para o desenvolvimento posterior.

3. Crie um guia público do projeto

/readme-craft

Use readme-craft de forma independente quando o repositório precisar de um README público claro baseado em fatos verificados do projeto.

🛡 Princípios de design

Princípio Como o framework o aplica
Estrutura legível por LLM Cabeçalhos estáveis, relações explícitas, tabelas e regras em texto simples
Permissões no nível das instruções Regiões bloqueadas e geradas indicam ao Agent o que o fluxo espera que ele altere
Separação entre processo e decisão O progresso rotineiro pode avançar rapidamente, enquanto mudanças de produto e arquitetura exigem aprovação
Arquivos dimensionados pela complexidade Projetos pequenos permanecem leves; arquivos adicionais surgem de sinais explícitos
Tamanho limitado dos documentos Um SPEC com mais de 300 linhas solicita uma divisão por módulos em docs/spec/
Resumos determinísticos Cabeçalhos de estado são reconstruídos a partir de contagens, módulos, IDs e datas

Zonas bloqueadas e geradas

Os arquivos gerados marcam seus limites com comentários HTML:

<!-- 🔒 START 锁定区：规则 -->
Regras que o Agent deve preservar
<!-- 🔒 END 锁定区：规则 -->

<!-- 🔓 START 生成区：项目内容 -->
Conteúdo específico do projeto que o Agent pode manter
<!-- 🔓 END 生成区：项目内容 -->

As instruções geradas exigem confirmação do usuário antes de mudanças substanciais em SPEC.md, ARCHITECTURE.md, SCHEMA.md, DESIGN.md e DECISIONS.md. Arquivos de processo como TODO.md, ISSUES.md e PROGRESS.md destinam-se à manutenção rotineira pelo Agent. Esses controles são convenções em Markdown e dependem do cumprimento pelo Agent.

Cabeçalhos de triagem rápida

TODO.md, ISSUES.md, PROGRESS.md e DECISIONS.md começam com um bloco de status compacto e derivado mecanicamente.

Arquivo Foco do cabeçalho
TODO.md Contagem de tarefas em andamento, distribuição do backlog, próxima ação e data de atualização
ISSUES.md Módulos ativos, primeiro item relevante, contagens por estado e bloqueios do MVP
PROGRESS.md Fase, progresso do marco, bloqueios e ponto de retomada
DECISIONS.md Decisões irreversíveis, contagem e data de atualização

Cada modelo inclui o algoritmo de reconstrução em uma seção bloqueada. Após alterar o corpo, o Agent recalcula o cabeçalho completo a partir das entradas de origem.

🎬 Exemplo: ChatLens

O diretório examples/ contém um conjunto preenchido para o ChatLens, um produto fictício de análise de conversas B2B.

O que o exemplo mostra Contexto importante
Todos os nove arquivos do projeto Foram gerados juntos intencionalmente para demonstrar todos os modelos
Regiões bloqueadas e geradas O modelo de permissões em documentos realistas
Cabeçalhos de triagem e algoritmos Como os resumos de estado permanecem derivados mecanicamente
Referências entre arquivos Como tarefas, problemas, decisões e progresso se conectam

Projetos reais seguem as regras de gatilho. Um projeto pequeno pode usar apenas SPEC.md, CLAUDE.md e TODO.md.

📂 Estrutura do projeto

ai-dev-context-framework/
├── README.md
├── LICENSE
├── scripts/
│   └── sync-skills.sh
├── skills/
│   ├── spec-gen/
│   │   ├── SKILL.md
│   │   └── templates/SPEC.md.example
│   ├── project-init/
│   │   ├── SKILL.md
│   │   └── templates/*.md.example
│   └── readme-craft/
│       ├── SKILL.md
│       ├── agents/openai.yaml
│       ├── references/
│       │   ├── visual-system.md
│       │   └── verification.md
│       ├── scripts/validate_readme.py
│       └── templates/README.md.example
├── lite/
│   ├── README.md
│   ├── WORKFLOW.md
│   └── skills/
│       ├── spec-gen-lite/SKILL.md
│       └── project-init-lite/SKILL.md
└── examples/
    ├── SPEC.md
    ├── CLAUDE.md
    ├── TODO.md
    ├── ARCHITECTURE.md
    ├── SCHEMA.md
    ├── DESIGN.md
    ├── ISSUES.md
    ├── DECISIONS.md
    └── PROGRESS.md

O repositório armazena Skills, modelos reutilizáveis, um exemplo completo e um utilitário de sincronização para desenvolvimento. Ele não contém runtime de aplicativo.

📌 Notas

  • spec-gen e project-init formam o fluxo principal do projeto.
  • readme-craft é um Skill independente para escrever README.
  • lite/ é a edição de três arquivos principais mantida no mesmo repositório.
  • Instale a edição Full ou Lite em cada ambiente de programação para evitar gatilhos de Skill sobrepostos.
  • project-init espera um SPEC.md existente e completo.
  • O conjunto de nove arquivos do ChatLens é uma demonstração; a saída normal varia conforme a complexidade do projeto.
  • scripts/sync-skills.sh full|lite limpa a outra edição gerenciada antes de copiar os Skills globais selecionados.
  • O repositório atualmente distribui pastas de origem dos Skills e não publica versões .skill empacotadas.

Issues e pull requests são bem-vindos.

Mantenha a intenção do produto, o contexto de implementação e o estado do projeto no mesmo sistema.


Licença MIT © okht