Practical notes: Агент текста в SQL производственного уровня с Claude Code
Пошаговое руководство по Practical notes: Агент текста в SQL производственного уровня с Claude Code: контракты, проверки и слоты для кода для команд, использующих эту схему.
Используйте это как переработанную версию идей из «Агента текста-в-SQL производственного уровня с Claude Code, LangGraph, Langfuse, FastAPI и Qdrant», ориентированную на операторов: четкие этапы, упорядоченные блоки кода и записи о восстановлении, сохраняющиеся при передаче задач.
Репозиторий
Репозиторий работает наилучшим образом, когда его рассматривают как измеримую структуру. Сначала зафиксируйте один идеальный пример работы, один случай сбоя и записи о возврате к предыдущему состоянию перед расширением объема работ. Документируйте одновременно успешный и восстановительный сценарии. Повторные попытки, проверки человеком и обработка неработающих сообщений являются частью продукта, а не этапом последующей доработки. Сохраняйте состояние графа простым и типизированным. Вложенные структуры данных скрывают информацию о том, какой узел заполнил тот или иной поле, и мешают возобновлению работы после прерываний.
Технологическая стек
Технологическая стек работает наилучшим образом, когда рассматривается как измеримая структура. Соберите один идеальный пример работы, один случай сбоя и запись о возврате к предыдущему состоянию перед расширением объёма работ. Предпочитайте небольшие, тестируемые единицы кода вместо обширных скриптов. При сбое какого-либо шага причина должна быть связана с конкретной функцией, а не с запутанной цепочкой операций. Сохраняйте структуру графа простой и типизированной. Вложенные структуры данных маскируют информацию о том, какой узел заполнил тот или иной поле, что приводит к нарушению работоспособности после перерывов.
LLM и агент
LLM и агенты работают наилучшим образом, когда с ними обращаются как с измеримыми структурами. Соберите один идеальный пример работы, один случай сбоя и запись о возврате к предыдущему состоянию перед расширением объёма задачи. Рассматривайте этот этап как контракт между входными данными и проверенными результатами. Дайте названия создаваемым элементам, определите критерии успеха и не соглашайтесь на молчаливое частичное выполнение задачи. Установите лимит токенов на каждый ход и на всю сессию. Инструменты агентов активно расширяют контекст; строгие ограничения предотвращают появление неожиданных счетов за использование сервиса.
Эмбеддинги и векторный поиск
Эмбеддинги и векторный поиск работают наилучшим образом, когда их рассматривают как измеримую поверхность. Перед расширением объёма работы соберите один идеальный пример, один случай сбоя и записку о возврате к предыдущему состоянию. Записывайте время выполнения операций, а также стоимость токенов или запросов рядом с функциональными результатами. Отслеживание затрат на раннем этапе предотвращает неожиданные счёты при переходе от демо-среды к общедоступным средам. Разделяйте политику разбиения данных на части и политику поиска. Изменение одной из них не должно приводить к необходимости переписывания другой при изменении показателей качества.
API и бэкенд
API и Backend работают наилучшим образом, когда рассматриваются как измеримые структуры. Соберите один эталонный пример работы, один случай сбоя и записку о возврате к предыдущему состоянию перед расширением объёма работ. Храните конфигурацию вне кода приложения. Файлы среды, хранилища секретов и флаги функций должны находиться в одном месте, чтобы операторы могли их проверять, не читая весь код. Сохраняйте структуру графа простой и типизированной. Вложенные структуры данных маскируют информацию о том, какой узел заполнил тот или иной поле, что приводит к нарушению работоспособности после перерывов. API и Backend работают наилучшим образом, когда рассматриваются как измеримые структуры. Соберите один эталонный пример работы, один случай сбоя и записку о возврате к предыдущему состоянию перед расширением объёма работ. Предпочитайте небольшие, тестируемые единицы кода вместо обширных скриптов. При сбое какого-либо шага причина должна быть связана с конкретной функцией, а не с запутанной цепочкой операций.
Frontend
Для фронтенда необходимо определить входные данные, ответственного за выполнение шага и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Рассматривайте этот этап как контракт между входными данными и проверенными выходными результатами. Дайте названия элементам, определите критерии успеха и не допускайте молчаливого частичного завершения работы. Внедряйте утверждение человека для операций, связанных с тратой денег или изменением производственных данных. Подключение компонентов во время компиляции не гарантирует полноты выполнения бизнес-задач.
Наблюдаемость и отслеживание
Для обеспечения наблюдаемости и отслеживания необходимо заранее определить входные данные, ответственного за выполнение шага и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Рядом с функциональными результатами следует записывать время выполнения и стоимость токенов или запросов. Отображение затрат на раннем этапе предотвращает неожиданные счета при переходе из демо-среды в общедоступные среды. Необходимо ввести человеческое утверждение для операций, связанных с тратой денег или изменением производственных данных. Подключение компонентов во время компиляции не гарантирует полноты реализации бизнес-логики.
Оценка
Для оценки необходимо определить входные данные, ответственного за выполнение шага и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Храните конфигурацию вне кода приложения. Файлы среды, хранилища секретов и флаги функций должны находиться в одном месте, чтобы операторы могли их проверять, не читая весь код. Вводите ручное утверждение для операций, связанных с тратой денег или изменением производственных данных. Подключение компонентов во время компиляции не гарантирует полноты бизнес-логики. Для оценки необходимо определить входные данные, ответственного за выполнение шага и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Предпочитайте небольшие, тестируемые единицы кода большим скриптам. При сбое шага он должен указывать на конкретную причину, а не на сложную структуру обработки данных.
Инфраструктура и конфигурация
При работе над разделом «Инфраструктура и конфигурация» сначала запишите условия соглашения: необходимые входные данные, сигнал о успешном выполнении и действия при частичной неудаче. Такой чек-лист поможет сохранять честность при последующих изменениях кода. Рассматривайте этот этап как соглашение между входными данными и проверенными выходными результатами. Дайте названия создаваемым элементам, определите критерии успешности и не допускайте безответственного частичного выполнения задач. Выполняйте контрольные точки после дорогостоящих операций. Система возобновления работы не должна повторно оплачивать один и тот же вызов большой языковой модели, когда оператор пытается выполнить следующий этап.
Сервер MCP
При работе с MCP Server сначала запишите условия взаимодействия: необходимые параметры входных данных, сигнал о успешном выполнении и последствия частичной неудачи. Такой список помогает сохранять честность при последующих изменениях кода. Рядом с функциональными результатами записывайте время выполнения, стоимость токенов или запросов. Отслеживание затрат с самого начала предотвращает неожиданные расходы при переходе с демо-среды в общедоступные среды. Для каждого вызова фиксируйте название инструмента, хэш аргументов, время задержки и результат. Без такой информации отладка циклов агента занимает много времени.
Тестирование
При работе над тестированием сначала запишите условия работы системы: необходимые входные данные, сигнал о успешном выполнении и последствия частичной неудачи. Такой список помогает сохранять честность последующих изменений в коде. Храните конфигурацию отдельно от кода приложения. Файлы с настройками окружения, хранилища секретов и флаги функций должны находиться в одном месте, чтобы операторы могли их проверять, не читая весь код. Создавайте контрольные точки после дорогостоящих операций. Система возобновления работы не должна снова оплачивать один и тот же вызов большой языковой модели, когда оператор пытается выполнить следующий шаг. При работе над тестированием сначала запишите условия работы системы: необходимые входные данные, сигнал о успешном выполнении и последствия частичной неудачи. Такой список помогает сохранять честность последующих изменений в коде. Предпочитайте небольшие, тестируемые единицы кода большим скриптам. Если какой-то шаг не сработает, причина неудачи должна указывать на конкретную ответственность, а не на запутанную структуру обработки данных.
Инструменты для разработчиков
Инструменты для разработчиков работают наилучшим образом, когда их рассматривают как измеримую систему. Соберите один идеальный пример работы, один случай сбоя и записку о возврате к предыдущему состоянию перед расширением объёма работ. Рассматривайте этот этап как контракт между входными данными и проверенными результатами. Дайте названия создаваемым элементам, определите критерии успеха и не соглашайтесь на молчаливое частичное выполнение задачи. Обеспечьте доступ к инструментам с узкими схемами и чёткими метками о побочных эффектах. У операторов должна быть возможность узнать, какие вызовы изменяют состояние, прежде чем они автоматически одобрят их.
Почему вы создали агента Text-to-SQL с нуля
Причины, по которым создание агента Text-to-SQL с нуля работает наилучшим образом, лучше всего рассматривать как измеримые показатели. Соберите один идеальный пример работы, один случай сбоя и записку о возврате к предыдущему состоянию перед расширением объёма работ. Записывайте время выполнения и стоимость токенов или запросов вместе с функциональными результатами. Отслеживание затрат на раннем этапе предотвращает неожиданные счёты при переходе от демо-среды к общедоступным средам. Сохраняйте структуру графа простой и типизированной; вложенные структуры данных маскируют информацию о том, какой узел заполнил какое поле, и приводят к нарушению целостности данных после перерывов.
1. Набор данных UDogRetail — проектирование реалистичной тестовой среды
- Набор данных UDogRetail — для создания реалистичной среды тестирования лучше всего использовать подход, при котором она рассматривается как измеримая структура. Соберите один эталонный пример работы, один случай сбоя и записку о возврате к предыдущему состоянию перед расширением объёма работ. Храните конфигурацию вне кода приложения. Файлы с настройками, хранилища секретов и флаги функций должны находиться в одном месте, чтобы операторы могли их проверять, не читая весь код. Сохраняйте структуру графа простой и типизированной. Вложенные структуры данных мешают понять, какой узел заполнил тот или иной поле, и приводят к нарушению последовательности выполнения после перерывов.
- Набор данных UDogRetail — для создания реалистичной среды тестирования лучше всего использовать подход, при котором она рассматривается как измеримая структура. Соберите один эталонный пример работы, один случай сбоя и записку о возврате к предыдущему состоянию перед расширением объёма работ. Предпочитайте небольшие, тестируемые единицы кода вместо обширных скриптов. При сбое какого-либо шага причина должна быть связана с конкретной функцией, а не с запутанной цепочкой операций.
2. Обзор архитектуры — как все компоненты взаимосвязаны
При разделе 2. Обзор архитектуры — как все компоненты взаимосвязаны необходимо определить входные данные, ответственного за выполнение шага и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Рассматривайте этот этап как контракт между входными данными и проверенными выходными результатами. Дайте названия результатам работы, определите критерии успеха и не допускайте молчаливого частичного завершения задачи. Внедряйте утверждение человека для операций, связанных с тратой денег или изменением производственных данных. Настройка на этапе компиляции не гарантирует полноты выполнения бизнес-задач.
Выбранный технологический стек и причины его выбора:
Что касается выбранной технологической стек и причин её выбора: перед изменением кода необходимо определить входные данные, ответственного за выполнение шага и критерии завершения. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Рядом с функциональными результатами следует записывать время выполнения и стоимость токенов или запросов. Отображение затрат на раннем этапе предотвращает неожиданные счета при переходе от демо-среды к общедоступным средам. Необходимо ввести человеческое утверждение для тех случаев, когда происходит трата средств или изменение данных в продакшене. Подключение компонентов во время компиляции не гарантирует полноты реализации бизнес-логики.
3. Создание пайплайна RAG — схема + поиск документов
Для пункта 3. Создание конвейера RAG — схема + поиск документов: перед изменением кода необходимо определить входные данные, ответственного за шаг и критерии завершения. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Храните конфигурацию вне кода приложения. Файлы среды, хранилища секретов и флаги функций должны находиться в одном месте, которое операторы могут проверять, не читая весь код. Указывайте те фрагменты текста, которые легли в основу ответа. Без цитат операторы не смогут отличить галлюцинации от пробелов в индексации. Для пункта 3. Создание конвейера RAG — схема + поиск документов: перед изменением кода необходимо определить входные данные, ответственного за шаг и критерии завершения. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Предпочитайте небольшие, тестируемые единицы кода вместо обширных скриптов. При сбое шага он должен указывать на конкретную причину.
одна ответственность, а не запутанная цепочка операций.Индексация схемы
При работе над индексацией схемы сначала запишите условия использования: необходимые входные данные, сигнал о успешном выполнении и последствия частичной неудачи. Такой список помогает сохранять честность при последующих изменениях кода. Рассматривайте этот этап как договор между входными данными и проверенными выходными результатами. Дайте названия элементам, определите критерии успеха и не допускайте безответственного частичного выполнения задачи. Выполняйте контрольные точки после дорогостоящих операций. Механизм возобновления работы не должен повторно запрашивать один и тот же вызов большой языковой модели, когда оператор пытается выполнить следующий этап.
Индексация базы знаний
При работе над индексацией базы знаний сначала запишите условия работы: необходимые входные данные, сигнал о успешном выполнении и последствия частичной неудачи. Такой список помогает сохранять честность при последующих изменениях кода. Рядом с функциональными результатами записывайте время выполнения и стоимость токенов или запросов. Отображение затрат с самого начала предотвращает неожиданные счета при переходе с демо-среды в общедоступные среды. Выполняйте контрольные точки после дорогостоящих шагов. Функция возобновления работы не должна снова взимать плату за один и тот же вызов большой языковой модели, когда оператор пытается выполнить следующий элемент.
Поиск информации
При работе над механизмом поиска сначала запишите контракт: необходимые входные данные, сигнал о успехе и что происходит при частичной неудаче. Такой список помогает сохранять честность последующих изменений в коде. Храните конфигурацию отдельно от кода приложения. Файлы среды, хранилища секретов и флаги функций должны находиться в одном месте, чтобы операторы могли их проверять, не читая весь код. Измеряйте показатель воспроизведения на фиксированном наборе вопросов перед настройкой подсказок. Частая смена подсказок редко помогает улучшить слабый механизм поиска. При работе над механизмом поиска сначала запишите контракт: необходимые входные данные, сигнал о успехе и что происходит при частичной неудаче. Такой список помогает сохранять честность последующих изменений в коде. Предпочитайте небольшие, тестируемые единицы кода большим скриптам. Когда какой-то шаг терпит неудачу, ошибка должна указывать на конкретную ответственность, а не на запутанную цепочку операций.
4. Агент LangGraph — узлы, состояние и самокоррекция
- Агент LangGraph — узлы, состояние и механизм самокоррекции работают наилучшим образом, когда их рассматривают как измеримую структуру. Соберите один идеальный пример работы, один случай сбоя и запись о возврате к предыдущему состоянию перед расширением объёма задачи. Рассматривайте этот этап как контракт между входными данными и проверенными выходными результатами. Дайте названия создаваемым элементам, определите критерии успеха и не соглашайтесь на молчаливое частичное выполнение задачи. Сохраняйте состояние графа простым и типизированным. Вложенные структуры данных скрывают информацию о том, какой узел заполнил тот или иной поле, что приводит к нарушению возобновления работы после перерывов.
class AgentState(TypedDict):
question: str
session_id: str
retrieved_schema: list[str]
retrieved_docs: list[str]
generated_sql: Optional[str]
sql_reasoning: Optional[str]
sql_assumptions: list[str]
sql_confidence: float
validation_error: Optional[str]
execution_result: Optional[ExecutionResult]
execution_error: Optional[str]
retry_count: int
correction_history: list[CorrectionRecord]
needs_clarification: bool
clarification_message: Optional[str]
final_explanation: Optional[str]
langfuse_trace_id: Optional[str]
ГЕНЕРИРОВАТЬ
GENERATE работает наилучшим образом, когда его рассматривают как измеримую поверхность. Сначала зафиксируйте один идеальный пример работы, один случай сбоя и записку о возврате к предыдущему состоянию, прежде чем расширять объем задачи. Записывайте временные показатели, а также стоимость токенов или запросов рядом с функциональными результатами. Отображение стоимости на раннем этапе предотвращает неожиданные счета при переходе от демо-среды к общедоступным средам. Сохраняйте структуру графа простой и типизированной; вложенные структуры скрывают информацию о том, какой узел заполнил тот или иной поле, и могут нарушить возобновление работы после прерываний.
ПРОВЕРКА → РЕАЛИЗАЦИЯ
Подход VALIDATE → EXECUTE работает наилучшим образом, когда его рассматривают как измеримую структуру. Соберите один эталонный пример работы, один случай сбоя и записку о возврате к предыдущему состоянию перед расширением объёма работы. Храните конфигурацию вне кода приложения. Файлы среды, хранилища секретов и флаги функций должны находиться в одном месте, чтобы операторы могли их проверять, не читая весь код. Сохраняйте структуру графа простой и типизированной. Вложенные структуры данных маскируют информацию о том, какой узел заполнил тот или иной поле, что приводит к нарушению возобновления работы после перерывов. Подход VALIDATE → EXECUTE работает наилучшим образом, когда его рассматривают как измеримую структуру. Соберите один эталонный пример работы, один случай сбоя и записку о возврате к предыдущему состоянию перед расширением объёма работы. Предпочитайте небольшие, тестируемые единицы кода большим скриптам. Когда какой-либо шаг срабатывает некорректно, причина сбоя должна указывать на конкретную ответственность, а не на запутанную цепочку операций.
FORBIDDEN_KEYWORDS = frozenset({
"INSERT", "UPDATE", "DELETE", "DROP",
"TRUNCATE", "ALTER", "CREATE", "GRANT", "REVOKE"
})
Цикл самокоррекции
Для цикла самокоррекции необходимо заранее определить входные данные, ответственного за выполнение шага и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Рассматривайте этот этап как контракт между входными данными и проверенными выходными результатами. Дайте названия результатам работы, определите критерии успеха и не допускайте молчаливого частичного завершения задачи. Внедряйте утверждение человека для операций, связанных с тратой денег или изменением производственных данных. Подключение компонентов во время компиляции не гарантирует полноты реализации функционала в бизнес-среде.
def route_after_execute(state: AgentState) -> str:
if state["execution_error"] is None:
return "explain"
if state["retry_count"] >= settings.max_retries:
return "clarify"
return "correct"
5. Подготовка к использованию в производстве — FastAPI, Docker, Terraform
5. Подготовка к использованию в производстве — FastAPI, Docker, Terraform: определите входные данные, ответственного за шаг и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Записывайте время выполнения и стоимость токенов или запросов рядом с функциональными результатами. Отображение затрат на раннем этапе предотвращает неожиданные счета при переходе с демо-среды в общедоступные среды. Внедряйте человеческое утверждение для операций, связанных с тратами денег или изменением производственных данных. Подключение компонентов во время компиляции не гарантирует полноты бизнес-функционала.
API
Для API необходимо определить входные данные, ответственного за выполнение шага и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Храните конфигурацию вне кода приложения. Файлы среды, хранилища секретов и флаги функций должны находиться в одном месте, чтобы операторы могли их проверять, не читая весь алгоритм. Вводите человеческое утверждение для операций, связанных с тратой денег или изменением производственных данных. Подключение компонентов во время компиляции не гарантирует полноты бизнес-логики. Для API необходимо определить входные данные, ответственного за выполнение шага и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Предпочитайте небольшие, тестируемые единицы кода вместо обширных скриптов. При сбое шага он должен указывать на конкретную причину, а не на сложную структуру обработки данных.
Docker
При работе с Docker сначала запишите условия использования: необходимые входные данные, сигнал о успешном выполнении и последствия частичной неудачи. Такой список поможет сохранять честность при последующих изменениях кода. Рассматривайте этот этап как договор между входными данными и проверенными результатами. Дайте названия создаваемым файлам, определите критерии успешности и не допускайте молчаливого частичного выполнения задачи. Создавайте контрольные точки после дорогостоящих операций. Функция возобновления выполнения не должна повторно запускать ту же операцию с использованием того же ИИ-моделя, когда оператор пытается выполнить следующий этап.
#!/bin/bash
# backend/start.sh
set -e
echo "==> Running Alembic migrations…"
cd /app/backend && alembic upgrade head
echo "==> Starting uvicorn…"
exec uvicorn app.main:app - host 0.0.0.0 - port 8000
Конфигурация
При работе над конфигурацией сначала запишите условия работы: необходимые входные данные, сигнал о успешном выполнении и действия при частичной неудаче. Такой список поможет избежать ошибок при последующих изменениях кода. Рядом с функциональными результатами записывайте время выполнения и стоимость токенов или запросов. Отслеживание затрат с самого начала предотвращает неожиданные счета при переходе с демо-среды в общедоступные среды. Выполняйте контрольные точки после дорогостоящих операций. Функция возобновления работы не должна снова взимать плату за один и тот же вызов большой языковой модели, если оператор попытается выполнить последующий шаг.
class Settings(BaseSettings):
anthropic_api_key: SecretStr
voyage_api_key: SecretStr
postgres_password: SecretStr
langfuse_secret_key: SecretStr
6. Возможности отслеживания в Langfuse — трекинг каждой работы агента
При работе над разделом 6. «Наблюдаемость с Langfuse — отслеживание каждой запуская агента», сначала опишите контракт: необходимые входные данные, сигнал успешного выполнения и последствия частичной неудачи. Такой чек-лист поможет сохранять честность последующих изменений в коде. Храните конфигурацию отдельно от кода приложения. Файлы среды, хранилища секретов и флаги функций должны находиться в одном месте, чтобы операторы могли их проверять, не читая весь граф. Создавайте точки контроля после дорогостоящих операций. Функция возобновления не должна снова взимать плату за один и тот же вызов LLM при повторной попытке обработки последующего узла. При работе над разделом 6. «Наблюдаемость с Langfuse — отслеживание каждой запуская агента», сначала опишите контракт: необходимые входные данные, сигнал успешного выполнения и последствия частичной неудачи. Такой чек-лист поможет сохранять честность последующих изменений в коде. Предпочитайте небольшие, тестируемые единицы кода большим скриптам. При сбое какого-либо шага причина неудачи должна указывать на конкретную ответственность, а не на запутанную цепочку операций.
.@observe(name="generate", as_type="generation")
def generate(state: AgentState) -> AgentState:
# Claude call happens here
# Langfuse auto-captures input, output, latency
lf = get_lf_client()
lf.update_current_observation(
model="claude-sonnet-4–6",
usage={"input": input_tokens, "output": output_tokens},
)
7. Тестирование — модульные тесты и интеграционные тесты
- Тестирование — модульные тесты и интеграционные тесты дают наилучшие результаты, когда их рассматривают как измеримую величину. Сначала зафиксируйте один идеальный пример работы, один случай сбоя и записку о возврате к предыдущему состоянию, прежде чем расширять объём тестирования. Рассматривайте этот этап как контракт между входными данными и проверенными выходными результатами. Дайте названия всем элементам, определите критерии успеха и не допускайте молчаливого частичного выполнения задач. Сохраняйте структуру графа простой и типизированной. Вложенные структуры скрывают информацию о том, какой узел заполнил тот или иной поле, что приводит к нарушению возобновления работы после перерывов.
Модульные тесты
Юнит-тесты работают наилучшим образом, когда их рассматривают как измеримую поверхность. Запишите один идеальный пример работы, один случай сбоя и записку о возврате к предыдущему состоянию перед расширением объёма тестирования. Зафиксируйте время выполнения, а также стоимость токенов или запросов рядом с функциональными результатами. Отображение стоимости на раннем этапе предотвращает неожиданные счёты при переходе от демо-среды к общедоступным средам. Сохраняйте структуру графа простой и типизированной; вложенные структуры скрывают информацию о том, какой узел заполнил какое поле, и могут нарушить возобновление работы после прерываний.
@pytest.mark.parametrize("keyword", sorted(FORBIDDEN_KEYWORDS))
def test_forbidden_keyword_rejected(keyword: str) -> None:
sql = f"{keyword} INTO orders VALUES ('x')"
result = validate_sql(sql)
assert not result.is_valid
assert keyword in result.error_message
def test_forbidden_keyword_in_cte_still_rejected() -> None:
sql = "WITH x AS (DELETE FROM orders RETURNING id) SELECT * FROM x"
result = validate_sql(sql)
assert not result.is_valid
pytest tests/unit/ -v
Интеграционные тесты
Интеграционные тесты работают наилучшим образом, когда их рассматривают как измеримую структуру. Сохраняйте один эталонный протокол, один случай сбоя и записку о возврате к предыдущему состоянию перед расширением объёма тестирования. Храните конфигурацию вне кода приложения. Файлы среды, хранилища секретов и флаги функций должны находиться в одном месте, чтобы операторы могли их проверять, не читая весь код. Сохраняйте состояние структуры простым и типизированным. Вложенные объекты скрывают информацию о том, какой узел заполнил тот или иной поле, и мешают возобновлению работы после прерываний. Интеграционные тесты работают наилучшим образом, когда их рассматривают как измеримую структуру. Сохраняйте один эталонный протокол, один случай сбоя и записку о возврате к предыдущему состоянию перед расширением объёма тестирования. Предпочитайте небольшие, тестируемые единицы кода вместо обширных скриптов. Когда какой-то шаг теста сбивается, причина сбоя должна указывать на конкретную ответственность, а не на запутанную цепочку операций.
pytest tests/integration/ -v
8. Оценка агента с помощью GEval
8. Оценка агента с помощью GEval: перед изменением кода необходимо определить входные данные, ответственного за выполнение шага и критерии завершения. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Рассматривайте этот этап как контракт между входными данными и проверенными результатами. Укажите названия результатов работы, определите критерии успеха и не допускайте молчаливого частичного завершения задачи. Внедряйте утверждение человека для операций, связанных с тратой денег или изменением производственных данных. Подключение на этапе компиляции не гарантирует полноты выполнения бизнес-задач.
prompt = f"""
Score from 0.0 to 1.0 whether this explanation is faithful to the results.
Results: {json.dumps(rows[:5])}
Explanation: {explanation}
Return only JSON: {{"score": float, "reasoning": str}}
"""
python -m evaluation.harness --complexity simple
python -m evaluation.harness --limit 10
9. Сервер MCP — превращение его в компонент Claude Code
Для пункта 9. Сервер MCP — чтобы сделать его частью Claude Code, необходимо определить входные данные, ответственного за выполнение шага и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Рядом с функциональными результатами следует записывать время выполнения и стоимость токена или запроса. Отображение затрат заранее предотвращает неожиданные счета при переходе с демо-среды в общедоступные среды. Аутентификация происходит на шлюзе, а повторная авторизация — на уровне данных. Один только токен-носитель не является границей аренды.
mcp = FastMCP(name="udogretail-text2sql")
@mcp.tool()
def query_tool(question: str, session_id: str = "") -> str:
"""Run a natural-language question through the Text-to-SQL agent."""
…
@mcp.tool()
def schema_tool(keyword: str) -> str:
"""Look up tables and columns matching a keyword."""
…
@mcp.tool()
def history_tool(limit: int = 5) -> str:
"""Fetch the last N query runs from agent history."""
…
{
"mcpServers": {
"udogretail-text2sql": {
"type": "stdio",
"command": ".venv/bin/python",
"args": ["mcp_server/server.py"],
"env": {"API_BASE_URL": "http://localhost:8000"}
}
}
}
10. Результаты, уроки и что бы вы сделали иначе
Для раздела 10. Результаты, уроки и что бы вы сделали иначе необходимо заранее определить входные данные, ответственного за шаг и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Храните конфигурацию вне кода приложения. Файлы среды, хранилища секретов и флаги функций должны находиться в одном месте, которое операторы могут проверять, не читая весь код. Вводите человеческое утверждение для операций, связанных с тратой денег или изменением производственных данных. Подключение на этапе компиляции не гарантирует полноты бизнес-логики. Для раздела 10. Результаты, уроки и что бы вы сделали иначе необходимо заранее определить входные данные, ответственного за шаг и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Предпочитайте небольшие, тестируемые единицы кода большим скриптам. При сбое шага он должен указывать на конкретную причину для устранения.
ответственность, а не запутанная цепочка операций.Что бы вы сделали иначе:
При рассмотрении пункта «Что бы вы сделали иначе» сначала запишите условия контракта: необходимые входные данные, сигнал о успешном выполнении и последствия частичной неудачи. Такой чек-лист поможет сохранять честность при последующих изменениях кода. Рассматривайте этот этап как контракт между входными данными и проверенными выходными результатами. Дайте названия элементам, определите критерии успеха и не допускайте безответственного частичного выполнения задачи. Устанавливайте контрольные точки после дорогостоящих шагов. Система возобновления работы не должна снова взимать плату за один и тот же вызов большой языковой модели, когда оператор пытается выполнить следующий этап.
Что меня удивило:
При работе над разделом «Что меня удивило?» сначала запишите условия работы: необходимые входные данные, сигнал о успешном выполнении и действия при частичной неудаче. Такой чек-лист помогает сохранять честность при последующих изменениях кода.
Чек-лист операционной работы
При работе с чек-листом операционной работы сначала запишите условия работы: необходимые входные данные, сигнал о успешном выполнении и действия при частичной неудаче. Такой чек-лист помогает сохранять честность при последующих изменениях кода.
Задокументируйте как успешный сценарий работы, так и сценарий восстановления. Повторные попытки, проверки человеком и обработка неработающих сообщений являются частью продукта, а не элементами последующей доработки.
Пункт контроля после дорогостоящих шагов. Функция возобновления не должна снова взимать плату за один и тот же вызов LLM при повторной попытке оператора обработки последующего узла.
Закрепите версии зависимостей и запишите хэш изображения, с использованием которого выполнялась демонстрация. Воспроизводимость важнее коллективного опыта.
Предпочитайте небольшие, тестируемые единицы кода вместо обширных скриптов. При сбое какого-либо шага причина должна быть связана с конкретной функцией, а не с запутанной цепочкой операций.
Пункт контроля после дорогостоящих шагов. Функция возобновления не должна снова взимать плату за один и тот же вызов LLM при повторной попытке оператора обработки последующего узла.
Перед повышением уровня стека заморозьте версии, сохраните эталонный отчет для критического пути выполнения и убедитесь в наличии шагов для возврата к предыдущему состоянию. В совместных средах необходимы ограничения на частоту запросов, проверки принадлежности ресурсов и четко определенный ответственный за обновление секретов. Лучше надежность, несмотря на ее простоту, чем красивые, но единоразовые демонстрации.
Примечание к пакету 91a3d7beec49: не храните ключи поставщиков в репозитории, установите лимит токенов на сессию и сохраняйте транскрипции рядом с фиксами для оценки, чтобы последующие замены моделей оставались сопоставимыми.