﻿---
title: "16. Documentation Writer: README и docstrings"
description: LangChain-агент извлекает структуру модуля и пишет README или docstrings в стиле Google.
---

Агентская документация работает, когда сначала извлекается структура кода, а потом
пишется текст. Пример показывает именно такой порядок.

## Задача

По Python-модулю получить README с обзором и примерами или docstrings для функций.
Граница: агент описывает то, что видит в коде, и не знает замысла.

## Архитектура

```mermaid
flowchart LR
  C["Модуль"] --> X["extract_structure"]
  X -->|"функции, классы, сигнатуры"| G["Генерация"]
  G -->|"--format"| R["README / docstrings"]
```

## Поток

1. `extract_structure` вытаскивает AST-подобное описание: модуль, классы, функции,
   сигнатуры.
2. В зависимости от `--format` вызывается генератор README или docstrings.
3. Результат печатается.

## Что в коде

Два генератора — `generate_readme` и `add_docstrings` — используют одно и то же
извлечённое представление.

## Чему учит

- **Сначала структура, потом текст.** Модель получает сигнатуры, а не весь файл, и
  меньше придумывает.
- **Один вход — два формата.** Извлечение отделено от генерации, поэтому форматы
  не дублируют логику.
- **Google-style docstrings** — конкретный целевой формат, а не «напиши
  документацию».

## Где сломается

- **Описание неверного поведения.** Docstring гласит одно, код делает другое.
- **Придуманные примеры.** В README появляется вызов с несуществующими
  параметрами.
- **Нет проверки.** Сгенерированные примеры не запускаются.
- **Устаревание.** Документация не обновляется при изменении кода.

## Как улучшить

- Запускать примеры из README и сверять docstrings с тестами.
- Обновлять документацию в CI при изменении публичных сигнатур.
- Хранить docstrings рядом с кодом и проверять линтером на наличие и формат.
- Для README — генерировать каркас и заполнять смысловые разделы вручную.

## Связь с другими разделами

- [Разработка](https://wpcraft.ru/aia/use-cases/software-development.md) — домен.
- [Структурированный вывод](https://wpcraft.ru/aia/patterns/structured-output.md) — извлечение структуры.
- [LangChain](https://wpcraft.ru/aia/frameworks/langchain.md) — фреймворк.

## Материалы и источники

- [LangChain documentation](https://python.langchain.com) — модели и работа с текстом кода.