16. Documentation Writer: README и docstrings
Агентская документация работает, когда сначала извлекается структура кода, а потом пишется текст. Пример показывает именно такой порядок.
По Python-модулю получить README с обзором и примерами или docstrings для функций. Граница: агент описывает то, что видит в коде, и не знает замысла.
Архитектура
Заголовок раздела «Архитектура»flowchart LR C["Модуль"] --> X["extract_structure"] X -->|"функции, классы, сигнатуры"| G["Генерация"] G -->|"--format"| R["README / docstrings"]
extract_structureвытаскивает AST-подобное описание: модуль, классы, функции, сигнатуры.- В зависимости от
--formatвызывается генератор README или docstrings. - Результат печатается.
Что в коде
Заголовок раздела «Что в коде»Два генератора — generate_readme и add_docstrings — используют одно и то же
извлечённое представление.
Чему учит
Заголовок раздела «Чему учит»- Сначала структура, потом текст. Модель получает сигнатуры, а не весь файл, и меньше придумывает.
- Один вход — два формата. Извлечение отделено от генерации, поэтому форматы не дублируют логику.
- Google-style docstrings — конкретный целевой формат, а не «напиши документацию».
Где сломается
Заголовок раздела «Где сломается»- Описание неверного поведения. Docstring гласит одно, код делает другое.
- Придуманные примеры. В README появляется вызов с несуществующими параметрами.
- Нет проверки. Сгенерированные примеры не запускаются.
- Устаревание. Документация не обновляется при изменении кода.
Как улучшить
Заголовок раздела «Как улучшить»- Запускать примеры из README и сверять docstrings с тестами.
- Обновлять документацию в CI при изменении публичных сигнатур.
- Хранить docstrings рядом с кодом и проверять линтером на наличие и формат.
- Для README — генерировать каркас и заполнять смысловые разделы вручную.
Связь с другими разделами
Заголовок раздела «Связь с другими разделами»- Разработка — домен.
- Структурированный вывод — извлечение структуры.
- LangChain — фреймворк.
Материалы и источники
Заголовок раздела «Материалы и источники»- LangChain documentation — модели и работа с текстом кода.