Создание системы возврата VAT с помощью Claude Code на основе базы данных счетов и расходов

Короткий, бегло читаемый компаньон. Полный обзор объемом около 5000 слов с кодом, подсказками, схемой, пошаговым руководством по HMRC MTD и крайними случаями см. длинная статья.

Ежеквартальный выпуск VAT был худшей частью моего месяца

Ежеквартально малый бизнес в Великобритании должен составлять отчет VAT: девять ячеек с цифрами (продажи, покупки, VAT к оплате, VAT, подлежащий возврату, товары ЕС, если вы находитесь в Северной Ирландии, итоговые суммы, нетто) и отправлять их через HMRC Making Tax Digital (MTD). В течение многих лет моя ситуация выглядела так: открыть таблицу счетов-фактур в Postgres, экспортировать CSV-файл, вставить его в Excel, вручную классифицировать несколько сотен строк, запустить формулы, скопировать девять чисел в сторонний мост MTD, нажать «Отправить», надеюсь.

Это работало, но медленно и с потерями. Квитанции пропали. Изменения ставок в середине квартала нарушили формулы. Опечатка в одной из классификаций VAT может сместиться Box 5 на сотни фунтов. И контрольный след был таким: «Поверьте мне, у меня была электронная таблица».

В этом году я перестроил все это в небольшой проект Claude Code, который считывает мои счета-фактуры + базу данных расходов, классифицирует каждую строку, вычисляет девять блоков, тестирует PDF-файл и только затем отправляет его в HMRC MTD - с возможностью одобрения человеком. Этот блог представляет собой короткую версию. В длинной статье есть подсказки, Python, поток OAuth HMRC и ошибки.

Посмотреть прохождение

Краткое описание конвейера возврата VAT, работающего от начала до конца с реальной (анонимизированной) базой данных счетов и расходов.

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

1. Соединять. Claude Code получает только для чтения Подключение БД к моим счетам и таблицам расходов. Он никогда не имеет доступа на запись к исходным данным. CSV-файлы от Stripe, Wise, Revolut и нескольких банковских каналов добавляются в ./imports/.
2. Нормализовать. Клод генерирует и запускает небольшой скрипт Python, который отображает каждую исходную схему в одно каноническое представление: id, date, supplier_or_customer, gross, net, vat_amount, vat_rate, vat_treatment, country_code, currency, source, run_key. Иностранная валюта конвертируется в GBP по ежемесячному курсу HMRC. Весь период ключируется идемпотентом run_key поэтому повторный запуск безопасен.
3. Классифицировать + согласовать. Клод классифицирует каждую строку по режиму VAT — стандартные 20 %, сниженные 5 %, ноль, освобождение, выход за рамки области применения, обратный сбор, товары ЕС, услуги ЕС, отложенный импорт VAT — используя небольшой vat-rules.md Я храню в репо. Он также сверяет счета с платежами и помечает аномалии (отрицательные чистые суммы, отсутствующие номера поставщиков VAT, несоответствия кодов стран, поставщики, не зарегистрированные в VAT).
4. Вычислить. Чистофункциональный модуль Python — нет LLM в математике - считывает классифицированные строки и создает от Box 1 до Box 9, а также отчет о пробном запуске в Markdown. Схема фиксированной ставки, кассовый учет и ветви годового учета представляют собой явные пути кода, а не подсказки.
5. Представлять на рассмотрение. Только после того, как я (или мой бухгалтер) завершу пробный прогон, конвейер вызывает HMRC MTD API. Токен OAuth2. Заголовки для предотвращения мошенничества. GET obligations найти открытый период. POST returns с finalised: true. Затем GET liabilities чтобы подтвердить, что я должен и когда.

Почему Claude Code вместо Xero/QuickBooks/FreeAgent

Честно говоря, для большинства малых предприятий пакетный бухгалтер SaaS — правильный ответ. У них есть сертификация HMRC, есть группы поддержки, и ваш бухгалтер их уже знает. Так почему я это сделал?

• Я уже использую Claude Code каждый день для работы с ПО. Предельные затраты на его использование для сборки конвейера VAT невелики.
• Мои данные локальные. База данных счетов никогда не покидает мою машину. Классификатор работает по строкам; математика — локальный Python; только последние девять цифр относятся к HMRC. Ни арендатора SaaS, ни третьих лиц.
• Я хотел получить полный контроль над правилами категоризации. Некоторые из моих поставщиков неудобны (услуги ЕС, отложенный импорт VAT, пара крайних случаев с нулевой ставкой). Кодирование этих правил в vat-rules.md + модуль Python для меня быстрее, чем настройка SaaS.
• Аудиторский след принадлежит мне. Каждое приглашение Claude и каждая разница фиксируются в журнале, предназначенном только для добавления, вместе со снимком подписанного периода. Если HMRC когда-нибудь спросит, я могу произвести точные вычисления за считанные секунды.

Если вы еще не используете Claude Code или вам не нравится читать Python в полночь, используйте Xero/QuickBooks/FreeAgent. Это не рекомендация развертывать собственную систему VAT. Это история о том, что возможно, когда вы это делаете.

Где есть LLM, а где нет

Это та часть, о которой я хочу громко заявить. Клода нет в арифметике VAT. Клод классифицирует строки, предлагает сверки, а также генерирует и редактирует детерминированные модули Python, выполняющие математические вычисления. Фактические вычисления от Box 1 до Box 9 представляют собой чистую функцию с модульными тестами. Для подачи HMRC требуется разрешение человека. Отчет о пробном запуске является источником истины для подписания. Если я не могу объяснить, почему число является тем, чем оно является, глядя на код и классифицированные строки, я не отправляю его.

Это жесткое правило, поскольку финансы регулируются, и фраза «это сделал ИИ» не является защитой в рамках MTD. длинная статья более подробно о том, как провести эту линию в вашей собственной реализации.

Чего мне стоило построить и чего мне стоило управлять

Время сборки составило около недели целенаправленных вечеров, в основном потраченных на нормализацию схемы, правила классификатора и написание тестов для движка. Танец HMRC MTD OAuth был самой медленной частью; Сначала бежать против песочницы стоило каждой минуты.

Каждый квартал обходится мне примерно: моя подписка на Claude Code (уже оплаченная за другую работу) плюс несколько копеек за использование токенов для классификатора. Сам HMRC API бесплатен. Механизм VAT и журнал аудита работают локально на моем Mac.

Важная оговорка

Я инженер, а не дипломированный бухгалтер. Эта статья не является налоговой консультацией. Прежде чем выполнять что-либо подобное со своей реальной учетной записью HMRC, попросите зарегистрированного в Великобритании бухгалтера просмотреть ваш первый отчет от начала до конца. Используйте HMRC MTD песочница пока вы и ваш бухгалтер не будете счастливы. Стоимость плохого представления VAT намного выше, чем стоимость часа времени бухгалтера.

Читать длинную версию

Если вам нужна полная картина — точная схема CREATE TABLE, подсказки Claude Code, детерминированный движок Python с модульными тестами, поток HMRC MTD OAuth, заголовки для предотвращения мошенничества и подробный раздел о крайних случаях (протокол Brexit / NI, обратный платеж, частичное освобождение, схема фиксированной ставки, изменения ставок в середине квартала, мультивалютные счета, кредит-ноты, депозиты) — прочтите длинная статья. Это та версия, которую я хотел бы прочитать, прежде чем начать.

Смотреть Прохождение YouTube, подпишитесь на последующие учебные пособия (автоимпорт банковских данных, распознавание текста для квитанций, запланированное cron + утверждение Slack) и помните: это не налоговые консультации, требуется подпись бухгалтера.