Лучшее объяснение вашего кода похоронено в журнале чата

Вы провели сорок пять минут с Claude, проектируя схему повторных попыток. Вы объяснили режимы отказов, отвергли экспоненциальный откат, потому что он скрывает каскадное давление, остановились на token-bucket rate limiting с jitter и сгенерировали работающую реализацию. Объяснение было ясным, рассуждения были обоснованными, и код действительно прошёл тесты.

Затем вы закрыли вкладку.

Две недели спустя коллега спрашивает, почему логика повторных попыток использует jitter вместо экспоненциального отката. Вы открываете новый сеанс Claude и восстанавливаете аргумент по памяти. Новое объяснение близко, но не идентично. Вы создали вторую, немного отличающуюся устную традицию. Ни одна из них не доступна для поиска. Ни одна из них не может быть проверена в pull request. Обе исчезнут, когда вы покинете компанию.

Это не проблема инструментария. Это ошибка категории. Мы рассматриваем диалоги с LLM как личные черновики, тогда как на самом деле они — ближайшее к literate programming, к чему когда-либо приближались большинство инженеров.

Что имел в виду Кнут, и почему LLM случайно реализовали это

Donald Knuth определил literate programming в 1984 году как написание программ как литературных произведений. Код и документация сплетены в единое повествование. Читатель следует за рассуждениями автора, видит рассмотренные альтернативы и понимает, почему существует окончательная форма.

Сорок лет literate programming оставался нишевой практикой. Инструменты вроде WEB и CWEB требовали дисциплины. Большинство разработчиков писали код в один файл, а документацию в другой, и те сразу расходились.

Диалог с LLM — это literate programming случайно. Вы формулируете проблему прозой. Модель задаёт уточняющие вопросы. Вы уточняете constraints. Модель предлагает код. Вы отвергаете предложение и объясняете почему. Модель пересматривает. Конечный артефакт — это не просто блок кода. Это весь тред: отброшенные подходы, trade-offs, доменные допущения.

Проблема в том, что среда эфемерна. Чат-интерфейсы созданы для выполнения задач, а не для сохранения знаний. Как только сеанс заканчивается, повествование застывает в янтаре, недоступно для поиска, не версионируется и принадлежит вендору.

Почему журналы чата превосходят традиционную документацию для сложных решений

Традиционная документация описывает конечное состояние. Она отвечает на вопрос «что». Хороший журнал чата отвечает на «почему», что является более сложным вопросом и тем, который устаревает быстрее всего.

Рассмотрим типичный architecture decision record. В нём может быть написано: «Мы выбрали PostgreSQL вместо DynamoDB для сервиса инвентаризации из-за требований строгой согласованности». Это заключение. Оно ничего не говорит о слишком медленных запросах, приемлемой задержке репликации или vendor lock-in, который обсуждался и был отклонён.

Тред Claude содержит всё это. Он содержит итерации схемы, которые потерпели неудачу, планы запросов, которые вас удивили, и момент, когда вы осознали, что составной индекс должен покрывать фильтр статуса. Это decision record с полным контекстом.

Подвох в том, что контекст заперт в разговорном формате. Прокрутка стотурового треда, чтобы найти единственную идею о проектировании индексов, — это мучение. Знание есть, но оно недоступно.

Три режима отказа Chat-as-Docs

Обращение с сырыми журналами чата как с документацией приводит к предсказуемым сбоям. У каждого режима отказа есть исправление, но нужно действовать намеренно.

Hallucination drift. Claude выдумывает API, цитирует несуществующие статьи и уверенно предлагает дизайны, игнорирующие ваши реальные constraints. Журнал чата, сохранённый как документация, сохраняет галлюцинации вместе с мудростью. Если вы не отметите, какие части были проверены, а какие спекулятивны, следующий читатель воспримет всё как догму.

Narrative sprawl. Хороший разговор блуждает. Вы исследуете тупики, отвлекаетесь на edge cases и возвращаетесь назад. Это блуждание ценно для понимания, но ужасно для справки. Новому инженеру, которому нужна политика повторных попыток, не нужно читать двадцатиминутное отступление о TCP congestion control.

Vendor lock-in. Ваша документация живёт в базе данных Anthropic, за их поисковым интерфейсом, подчиняясь их политике хранения. Если учётная запись истечёт или интерфейс изменится, ваши документы исчезнут. Документация, которую нельзя greppать, — это не документация.

Как извлечь долговечный документ из эфемерного чата

Решение — рассматривать чат как первый черновик, а не конечный артефакт. Вы извлекаете, проверяете и публикуете. Рабочий процесс прост и занимает около десяти минут на каждое значимое решение.

Шаг один: пометьте turns. Во время разговора отмечайте ключевые решения. Я использую простое соглашение. Когда Claude выдаёт блок кода, который я собираюсь сохранить, я отвечаю KEEP: <причина в одну строку>. Когда он предлагает что-то, что я отвергаю, я отвечаю REJECT: <причина>. Эти теги делают извлечение тривиальным.

Шаг два: извлечь в markdown. После сеанса скопируйте тред в файл markdown и удалите шум. Уберите приветствия, вставки «дайте подумать» и turns, где вы оба были растеряны. Сохраните постановку задачи, рассмотренные альтернативы, окончательное решение и проверенный код. Результат должен читаться как техническая заметка, а не как стенограмма.

Вот скрипт, который автоматизирует извлечение, если вы используете API Claude или экспортируете разговор в JSON:

#!/usr/bin/env python3
"""
Extract a readable technical note from a Claude conversation export.
Expects Anthropic's conversation JSON format.
"""

import json
import argparse
from pathlib import Path


def extract_note(conversation_path: Path, output_path: Path) -> None:
    with open(conversation_path) as f:
        data = json.load(f)

    turns = data.get("chat_messages", [])
    lines = []

    for turn in turns:
        sender = turn.get("sender", "unknown")
        text = turn.get("text", "").strip()

        if not text:
            continue

        # Skip pleasantries and meta-turns
        if any(phrase in text.lower() for phrase in [
            "hello", "how can i help", "you're welcome", "glad i could help"
        ]):
            continue

        if sender == "human":
            lines.append(f"**Q:** {text}\n")
        else:
            lines.append(f"**A:** {text}\n")

    with open(output_path, "w") as f:
        f.write("# Technical Note: Extracted from Claude Session\n\n")
        f.write("\n".join(lines))


if __name__ == "__main__":
    parser = argparse.ArgumentParser()
    parser.add_argument("--input", type=Path, required=True)
    parser.add_argument("--output", type=Path, required=True)
    args = parser.parse_args()
    extract_note(args.input, args.output)

Шаг три: проверьте каждый блок кода. Запустите извлечённый код. Если он не компилируется или не проходит тесты, исправьте в markdown и зафиксируйте исправление. Извлечённый документ должен быть единственным источником истины, а не стенограммой разговора, который мог содержать ошибки.

Шаг четыре: закоммитьте в репозиторий. Храните markdown в docs/decisions/ или docs/notes/ рядом с кодом, который он описывает. Дайте ему значимое имя файла: retry-circuit-jitter-over-exponential.md, а не claude-chat-july-19.md. Добавьте его в тот же pull request, что и изменение кода, или сразу откройте follow-up PR. Если документы не под контролем версий, они не существуют.

Когда это работает, а когда нет

Этот подход превосходен для сложных, неоднозначных решений, где рассуждения важны не меньше результата. Проектирование схем, стратегии миграции схем, политики API versioning и trade-offs производительности — все хорошие кандидаты.

Это не работает для справочной документации. Журнал чата о том, как пройти аутентификацию во внутреннем API, — ужасная замена структурированной спецификации OpenAPI и примеру cURL. Используйте подходящий инструмент для работы.

Это также не работает без кураторства. Сбрасывать сырые журналы чата в вики — это не документация. Это накопительство. Десять минут на извлечение и редактирование нельзя игнорировать. Если вы пропустите их, вы произведёте доступный для поиска мусор.

Практическая отправная точка

Вам не нужен новый инструмент. Вам нужна привычка.

В следующий раз, когда у вас будет долгий и продуктивный сеанс с Claude о нетривиальном проектном решении, экспортируйте тред, прежде чем закрыть вкладку. Потратьте десять минут на редактирование его в заметку markdown, которая отвечает на три вопроса: Какую проблему мы решали? Какие альтернативы мы рассмотрели и отвергли? На чём мы остановились и почему?

Закоммитьте эту заметку в свой репозиторий. Ссылайтесь на неё из комментария к коду над функцией, которую она описывает. Следующий инженер, который коснётся этого кода, поблагодарит вас, и ему не придётся открывать Claude, чтобы восстановить ваши рассуждения.

Ваш чат с Claude может стать документацией. Ему просто нужно, чтобы вы относились к нему как к коду: извлечённому, проверенному, версионированному и поддерживаемому.