Modelos de Documentação

Modelos e diretrizes de estrutura para tipos comuns de documentação.

1. Estrutura do README

Seções Essenciais (Ordem de Prioridade)

Modelo de README

# Project Name

Brief one-line description.

## Quick Start

[Minimum steps to run]

## Features

- Feature 1
- Feature 2

## Configuration

| Variable | Description | Default |
|----------|-------------|---------|
| PORT | Server port | 3000 |

## Documentation

- API Reference
- Architecture

## License

[Link to the actual project license; do not infer MIT]

2. Estrutura da Documentação da API

Modelo por Endpoint

## GET /users/:id

Get a user by ID.

**Parameters:**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| id | string | Yes | User ID |

**Response:**
- 200: User object
- 404: User not found

**Example:**
[Request and response example]

3. Diretrizes de Comentários de Código

Modelo JSDoc/TSDoc

/**
 * Brief description of what the function does.
 * 
 * @param paramName - Description of parameter
 * @returns Description of return value
 * @throws ErrorType - When this error occurs
 * 
 * @example
 * const result = functionName(input);
 */

Quando Comentar

4. Modelo de Changelog (Keep a Changelog)

# Changelog

## [Unreleased]
### Added
- New feature

## [1.0.0] - 2025-01-01
### Added
- Initial release
### Changed
- Updated dependency
### Fixed
- Bug fix

5. Registro de Decisão de Arquitetura (ADR)

# ADR-001: [Title]

## Status
Accepted / Deprecated / Superseded

## Context
Why are we making this decision?

## Decision
What did we decide?

## Consequences
What are the trade-offs?

6. Documentação Amigável para IA (2025)

Modelo llms.txt

Para rastreadores e agentes de IA (os links example.com ilustram a sintaxe; substitua-os por URLs de projetos publicados reais):

# Project Name
> One-line objective.

## Core Files
- [Main entry](https://example.com/project/src/index.ts): Application entry
- [API routes](https://example.com/project/src/api/): Endpoint implementation
- [Documentation](https://example.com/project/docs/): User and contributor guides

## Key Concepts
- Concept 1: Brief explanation
- Concept 2: Brief explanation

Documentação Pronta para MCP

Para indexação RAG:

• Hierarquia clara de H1-H3
• Exemplos JSON/YAML para estruturas de dados
• Diagramas Mermaid para fluxos
• Seções autônomas

7. Princípios de Estrutura

Lembre-se: Modelos são pontos de partida. Adapte-os às necessidades do seu projeto.

Quando Usar

Use quando um projeto real precisar de um README, referência de endpoint, changelog, ADR ou índice legível por agente, e você precisar de uma estrutura adaptada às suas convenções existentes.

Limitações

• Substitua caminhos, comandos, datas e padrões ilustrativos por fatos verificados do projeto. Modelos não são fluxos de trabalho instalados ou evidências de que links e exemplos funcionam.
• Preserve a licença real e o escopo de confidencialidade; não publique endpoints privados nem invente decisões de ADR aceitas.
• Use esta habilidade apenas quando a tarefa corresponder claramente ao escopo descrito acima.
• Não trate a saída como um substituto para validação específica do ambiente, testes ou revisão especializada.
• Pare e peça esclarecimentos se os inputs necessários, permissões, limites de segurança ou critérios de sucesso estiverem ausentes.