# Стандарты документации

## Docs-as-code

Вся документация — в репозитории, в Markdown. Пишется параллельно с кодом.

## Где что хранить

| Тип | Расположение | Формат |
|-----|-------------|--------|
| Архитектура | `docs/architecture.md` | MD |
| ADR | `docs/adr/NNN-title.md` | MD (YAML frontmatter) |
| Decision Log | `docs/decision-log.md` | MD |
| Чеклисты | `docs/checklists/NN-name.md` | MD |
| Runbook | `docs/runbook/NN-name.md` | MD |
| Спеки агентов | `docs/specs/agents/<role>.md` | MD |
| Промпты | `docs/agent_prompts.yaml` + `docs/specs/agents/` | YAML + MD |
| Changelog | `CHANGELOG/v*.md`, `CHANGELOG/agents/*.md` | MD |
| Дизайн-система | `docs/design-system/` | MD + JSON |

## Когда что писать

- **ADR**: когда выбираем технологию или меняем архитектуру
- **Decision Log**: каждое решение, у которого есть альтернативы
- **Runbook**: когда делаем что-то вручную больше одного раза
- **Чеклист**: когда забыли что-то проверить
- **Спека агента**: когда создаём нового агента

## Docstrings

Google-style для всех публичных классов и методов.

```python
def calculate_roi(investment: float, return_value: float, years: int = 1) -> float:
    """Calculate Return on Investment.

    Args:
        investment: Initial investment amount
        return_value: Total return after period
        years: Investment period in years (default: 1)

    Returns:
        ROI as a percentage

    Raises:
        ValueError: If investment is zero or negative
    """
```