раздел 05

Шпаргалка

Всё главное про лёгкие форматы коротко.

Что
Markdown, CSV и TXT - текстовые форматы, которые агент читает как есть: без распаковки, конвертации и догадок о структуре.
Зачем
Меньше токенов на ту же задачу, точнее цитаты и таблицы, агент читает папку целиком, правки видны в git построчно.
Как
Исходники в _source/, рабочие копии в md и csv рядом, правило в AGENTS.md / CLAUDE.md, Word и Excel собираются из md в конце.

Формат - для чего - как получить

ФорматДля чегоКак получить
Markdown (.md)Письма, КП, инструкции, регламенты, планы, протоколы, заметки, правила для агентаpandoc file.docx -t gfm -o file.md, Google Docs «Скачать - Markdown», или сразу писать в md
CSV (.csv)Выгрузки, реестры, прайсы, списки участников, любые плоские таблицыExcel «Сохранить как - CSV UTF-8», Google Sheets «Скачать - CSV», один лист - один файл
TXT (.txt)Транскрипты, логи, дампы, сырой текст из PDFpdftotext -layout file.pdf file.txt, экспорт транскрипта, OCR для сканов

Обратно, для выдачи: pandoc file.md -o out/file.docx (с --reference-doc= для фирменного оформления), для xlsx - скрипт на openpyxl.

Перед тем как отдать файл агенту

  • Файл в лёгком формате, а не docx, xlsx или pdf. Если нет - сначала конвертация.
  • Кодировка UTF-8. Кириллица читается, кракозябр нет.
  • Заголовки на месте: разделы через ##, а не жирным текстом.
  • Таблицы целые: число строк совпадает с исходником, объединённых ячеек нет.
  • Картинки вынесены в папку, ссылки рабочие или удалены.
  • Из PDF вычищены колонтитулы и номера страниц.
  • Исходник лежит в _source/, рабочая копия - рядом с понятным именем.
  • В AGENTS.md / CLAUDE.md есть правило про форматы.

Быстрые команды

# docx -> md с таблицами через | и картинками в images/
pandoc report.docx -t gfm --extract-media=images -o report.md

# вся папка _source/ разом
for f in _source/*.docx; do pandoc "$f" -t gfm -o "$(basename "${f%.docx}").md"; done

# pdf -> txt с сохранением расположения
pdftotext -layout contract.pdf contract.txt

# md -> docx для выдачи
pandoc proposal.md --reference-doc=templates/reference.docx -o out/proposal.docx

Глоссарий

  • Markdown - текстовый формат с простой разметкой: # заголовок, - список, | таблица, **жирный**. Читается и человеком без рендера, и агентом.
  • CSV - comma-separated values, таблица текстом: строка - запись, значения через запятую, первая строка - шапка. Один файл - один лист.
  • TXT - голый текст без разметки. Для транскриптов, логов и всего, где структура не нужна.
  • pandoc - консольный конвертер документов: docx, md, html, epub, pdf в обе стороны. Основной инструмент перевода в лёгкие форматы и обратно.
  • Кодировка UTF-8 - способ записи символов, при котором кириллица читается везде. Excel на Windows по умолчанию сохраняет в другой кодировке, нужно выбирать UTF-8 явно.
  • Токен - единица, которой модель считает текст и за которую берут деньги. Разметка docx и мусор из PDF - тоже токены.
  • _source/ - папка с исходниками как пришли. Не редактировать, не переименовывать.
  • Источник правды - файл, в котором живёт актуальная версия. В этом процессе всегда md или csv, а docx - снимок с него.

Куда дальше