voidea/docs/documentation.md

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

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 для всех публичных классов и методов.

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
    """