goldenprofile Docs Generator — документация, которую читают
Генератор и аудитор документации для Python-проектов (Django / FastAPI / aiogram). Ключевая идея: документация — это страховка «будущего тебя» и топливо для агентов, а не бюрократия. Минимум воды, документируем «почему», помечаем устаревшее. Чем меньше команда, тем важнее первое: через полгода единственный носитель контекста — текст в репозитории.
Когда применять
Новый проект без README; пришёл к старому проекту и не помнишь, как он устроен; принял важное
архитектурное решение (нужен ADR); публичный/переиспользуемый код без docstrings; CLAUDE.md и
AGENTS.md разъехались. Работает в двух режимах — генерация (создать недостающее) и аудит
(найти отсутствующее/устаревшее). Незнакомый проект сперва разбери через codebase-recon.
Принципы
- Документируй «почему», а не «что». Код уже говорит, что он делает. Док объясняет почему так, какие были альтернативы и ограничения — это не вытащить из кода.
- Минимум воды. Никакой маркетинговой прозы. Каждая строка либо экономит время будущего тебя, либо нужна агенту. Не дублируй очевидное (тип уже в hint — не повторяй его словами).
- Устаревший док хуже отсутствующего. Он врёт. Помечай (
> [!WARNING] устарело: …) или удаляй. - Близко к коду. Docstrings — в коде; README — в корне; ADR — в
docs/adr/. Не плоди вики. - Для агентов. CLAUDE.md/AGENTS.md — кратко и проверяемо; README даёт агенту быстрый старт.
Процесс
- Разведка. Что уже есть (README,
docs/,docs/adr/, CLAUDE.md, AGENTS.md, docstrings), класс проекта (Django-веб / FastAPI-API / aiogram-бот / automation-скрипт), точки входа. - Аудит. Прогони по чеклисту (ниже): что отсутствует, что устарело (док противоречит коду), что лишнее. Классифицируй по приоритету.
- Генерация. Создай/обнови по шаблонам из справочников. Спрашивай только то, чего нет в коде (мотивацию решений для ADR/README); техническое (env, команды запуска) вытаскивай из репозитория.
- Вывод. Отчёт по references/output-format.md; правки — по согласованию.
Уровни приоритета (для аудита)
- CRITICAL — документация врёт: README/CLAUDE.md противоречит коду (неверная команда запуска, несуществующая env-переменная, удалённый модуль) → агент или будущий ты сломает прод.
- HIGH — нет того, без чего проект не запустить: README без quick start / списка env, CLAUDE.md и AGENTS.md рассинхронизированы, нет ADR для уже принятого нетривиального решения.
- MEDIUM — публичный API/сервис без docstrings, нет деплой-заметки (systemd/nginx), ADR без раздела «последствия», README без ссылки на архитектуру.
- LOW — стиль, формулировки, docstring дублирует type hint, мелкие неточности.
Быстрый чеклист
- README: есть назначение, quick start, полный список env, команда запуска, деплой-заметка?
- Все команды/env в README и CLAUDE.md реально существуют в коде (не устарели)?
- CLAUDE.md и AGENTS.md синхронизированы (или AGENTS.md — символьная ссылка/копия)?
- Принятые нетривиальные решения (выбор БД, async vs sync, отказ от Celery) зафиксированы в ADR?
- Публичные функции/классы/сервисы имеют docstring, объясняющий «почему», а не тип аргументов?
- Нет устаревших доков, противоречащих текущему коду (помечены
устарелоили удалены)?
Связь с библиотекой навыков
harness-engineering— canonical docs (ARCHITECTURE.md, WORKFLOW.md), глубокая настройка CLAUDE.md/AGENTS.md (DoD, tooling). docs-generator пишет «человеческие» доки; harness — обвязку для агентов. См. references/agent-docs.md.codebase-recon— запусти ПЕРЕД документированием незнакомого проекта (восстановить архитектуру, точки входа, бизнес-цель), иначе будешь документировать вслепую.python-project-audit— аудит качества кода; docs-generator — аудит и генерация доков к нему.
Справочники
- references/readme.md — структура README (назначение, quick start, env, запуск, деплой-заметка systemd/nginx), что включать и чего не писать.
- references/adr.md — лёгкий ADR (MADR): когда писать, нумерация,
docs/adr/, шаблон (контекст/решение/последствия), статусы и superseded. - references/docstrings.md — Google-style docstrings, что документировать (модуль/класс/функция), связь с type hints, что НЕ писать, примеры (Django/FastAPI/async).
- references/agent-docs.md — CLAUDE.md/AGENTS.md: что писать (кратко, проверяемо), синхронизация двух файлов, граница с harness-engineering.
- references/output-format.md — формат отчёта аудита/генерации.