49 lines
1.8 KiB
Markdown
49 lines
1.8 KiB
Markdown
# Стандарты документации
|
|
|
|
## 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
|
|
"""
|
|
```
|