Полный маршрут изменения Markdown-библиотеки

Мы подготовили контракт, карту файлов, пакет контекста, реестр URL, функцию отбора и документы ревью. Теперь соберём их в полный маршрут изменения небольшой Markdown-библиотеки. Результатом урока будет воспроизводимая передача локального состояния: другой человек понимает входы, видит код и знает, какие действия ещё не выполнялись. Автоматической публикации или вызова AI в этом маршруте нет.

Архив серии содержит четырнадцать самостоятельных папок lesson-NN. Каждая отражает состояние определённого шага и включает необходимые данные. Выбирать нужно целую папку, а не смешивать финальную программу с ранними документами. Такая форма помогает проследить развитие проекта и одновременно даёт завершённый пакет последнего урока. Она не заменяет реальную историю Git, но пригодна для учебного сопоставления причин и результатов.

Сначала выбрать основу

В финальном состоянии прочитайте TASK.md и RULES.md. Задача остаётся той же: рекомендуемые публичные записи, устойчивый порядок, точный лимит, прежние URL. Затем откройте манифест и программу. Так вы увидите, что документы относятся к фактическим полям и функциям. Не начинайте с общего сообщения «всё готово»: оно не объясняет, какие исходные данные лежат в папке и какое поведение является новым.

Путь к корпусу в программе связан с местом файла. Это помогает передать выбранную папку без зависимости от каталога терминала. Но пакет не содержит сам Python и не устанавливает окружение. В README указан профиль 3.13 и отсутствие сторонних зависимостей. Читатель должен самостоятельно выбрать совместимую среду. Во время подготовки программы не запускались, поэтому архив не подтверждает поведение на конкретной версии вашей операционной системы.

Далее сопоставьте url-baseline.json с манифестом. Он описывает исходное соответствие идентификаторов и адресов. Функция формирования результата передаёт эти адреса напрямую. Если вы решите изменить набор документов для своего проекта, обновление основы должно быть явным действием, а не попыткой заставить старое описание совпасть с новой библиотекой. Реестр имеет смысл только в отношении определённого состояния и определённой договорённости о сохранении URL.

Маршрут кандидата

Кандидат функции находится в catalog.py. Его читают по тому же порядку, что использовался при написании: проверка лимита, публичность, редакционная рекомендация, сортировка и ограничение. Код не делает сетевых запросов и не пишет входные данные. Это оставляет узкую область результата, которую удобно объяснить владельцу сайта. При дальнейшем подключении шаблона нужно отдельно проверить потребителя, чтобы он действительно использовал поля краткого объекта.

Карточка REVIEW.md показывает, какие свойства следует сопоставить. DIAGNOSIS.md объясняет учебный дефект isinstance и точную границу boolean. Эти файлы не являются результатами выполненного тестового набора. Они помогают читателю понять механизм и самостоятельно выбрать наблюдения позднее. Если вы выполните программу, сохраняйте фактический вывод отдельно и указывайте состояние, к которому он относится. Не переписывайте авторское ожидание в утверждение о состоявшемся запуске.

pack.py позволяет подготовить небольшой контекст для будущей работы с выбранным AI-инструментом. Он читает явный список файлов, ограничивает размер и записывает отпечатки. Передача такого пакета во внешний сервис остаётся самостоятельным действием читателя и зависит от его правил данных. Архив не содержит настроенного подключения, ключей или скрытого вызова. Поэтому серия пригодна для понимания процесса без создания аккаунта и отправки собственного проекта.

Кто принимает следующий шаг

Карточка разрешений описывает область текущей задачи. Она не даёт финальному состоянию право размещать себя на хостинге. Если владелец захочет включить функцию в настоящий сайт, понадобится конкретная интеграция: куда подключается результат, как сохраняется обход старых уроков и что увидит посетитель. Этот следующий шаг может использовать наш контракт, но имеет собственные файлы и наблюдения. Нельзя считать его завершённым только из-за наличия рабочего по замыслу Python-примера.

Передача HANDOFF.md фиксирует принятые решения и невыполненное. EVIDENCE.json связывает утверждения с основанием. Вместе они дают полезную форму завершения локальной задачи: мы можем назвать, что написано, почему ожидается определённый результат и где уверенность пока ограничена чтением. Такое описание лучше переносится между людьми и инструментами, чем длинный ответ агента, который смешивает итог, планы и предположения о проверках.

Журнал расходов также остаётся учебным. Его тариф вымышленный, записи не получены из реальных вызовов. Для выбранного провайдера нужно будет заменить исходные ставки и счётчики, включая особые категории оплаты, если они существуют. Не превращайте демонстрационный калькулятор в обещание стоимости всей миграции. Его результат показывает механизм учёта; фактический бюджет зависит от числа задач, размера контекста, повторов и правил выбранного сервиса.

Расширение библиотеки

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

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

Архив как учебная передача

Архив собирает исходники и документы, но не превращает их в установленный проект. После распаковки выберите один lesson-NN и прочитайте README. Не переносите скрытые папки с реальными секретами, если используете формат для собственного проекта. В нашей серии таких данных нет; usage, заметки и сообщения явно авторские. Именно это позволяет поделиться примером и обсуждать механизм без обращения к настоящему аккаунту.

Если вы добавите реальные результаты самостоятельного запуска, сохраняйте их отдельно от исходных уроков. Команда, версия среды и наблюдаемый вывод полезны для повторения. Однако они будут относиться к вашей копии и времени исследования. Старое имя архива не удостоверяет, что файлы после распаковки оставались неизменными. При передаче следующему человеку можно дополнительно записать отпечатки актуальных исходников и существенных данных.

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

Ожидаемый финальный результат — библиотека, где рекомендуемые материалы выбираются без изменения манифеста и URL, а документы объясняют границы результата. Примеры, AI-вызовы, тесты и деплой не выполнялись. Полные исходники доступны в архиве; читатель может открыть выбранное состояние и пройти маршрут самостоятельно. Так завершается локальная авторская подготовка и остаётся ясная основа для будущей интеграции, расширения и отдельного решения о публикации.

Полный файл catalog.py из состояния lesson-14. Полное самостоятельное состояние находится в архиве серии; фрагмент не заменяет остальные определения.

from pathlib import Path
import json

ROOT = Path(__file__).resolve().parent

def load_pages():
    rows = json.loads((ROOT / "manifest.json").read_text(encoding="utf-8"))
    seen_ids, seen_urls = set(), set()
    for row in rows:
        if row["id"] in seen_ids or row["url"] in seen_urls:
            raise ValueError("duplicate identity")
        seen_ids.add(row["id"])
        seen_urls.add(row["url"])
        source = (ROOT / "corpus" / row["file"]).resolve()
        if source.parent != (ROOT / "corpus").resolve() or source.suffix != ".md":
            raise ValueError("outside corpus")
        row["text"] = source.read_text(encoding="utf-8")
    return rows

def public_pages(rows):
    return [row for row in rows if row["public"] is True]

def featured_pages(rows, limit=2):
    if type(limit) is not int or not 1 <= limit <= 5:
        raise ValueError("limit must be an integer from 1 to 5")
    return sorted(
        (row for row in public_pages(rows) if row.get("featured") is True),
        key=lambda row: row["id"],
    )[:limit]

if __name__ == "__main__":
    rows = load_pages()
    selected = featured_pages(rows)
    print(json.dumps([{"id": r["id"], "title": r["title"], "url": r["url"]} for r in selected], ensure_ascii=False, indent=2))

Полный файл README.md из состояния lesson-14. Полное самостоятельное состояние находится в архиве серии; фрагмент не заменяет остальные определения.

# AI workflow, состояние 14

Полный маршрут изменения Markdown-библиотеки. Полное состояние небольшой авторской библиотеки.
Python 3.13, только стандартная библиотека. Выберите целую папку lesson-NN.
Самостоятельный ожидаемый сценарий: из её папки выполнить `python3 catalog.py`.
Не запускается во время подготовки. Пример не вызывает AI и не меняет ProfessorWeb.
Учебные TASK/REVIEW/usage не выдаются за результаты реальных агентов.

Статус примера: not_run. При подготовке не выполнялись учебные программы, тесты, вызовы AI или деплой. Описанные эффекты ожидаемые.

Оглавление серии · Полные исходники

Первичные документы: Источник 1.