Capstone Project: Extending a TODO App
📚 Навигация по серии: Предыдущая статья 〔33 Особенности работы на Windows〕 разобрала специфику путей, переводов строк и песочниц в среде Windows. В этой главе мы не будем изучать новые функции, а займемся сборкой: объединим все полученные ранее знания о Codex в единый рабочий процесс на базе реального проекта. В следующей статье 〔35 Шпаргалка по командам и конфигурациям〕 мы соберем все параметры в краткую справочную таблицу.
Друзья, сегодня у нас практическое занятие — мы создадим и доработаем небольшое приложение.
В качестве основы возьмем простой консольный скрипт на Python — todo.py, который умеет только добавлять задачи и выводить их список. У него есть существенный недостаток: выполненные задачи нельзя удалить, из-за чего список постоянно растет. В этой главе мы с помощью Codex с нуля разработаем функцию удаления задач: от постановки требований и настройки песочницы до запуска тестов и отправки изменений в Git.
Предыдущие главы описывали работу отдельных компонентов: правил AGENTS.md, промптов, уровней песочницы и интеграции с Git. Пришло время увидеть, как эти детали работают вместе в рамках одного проекта. Эта статья — ваш чек-лист по сборке.
Мы не предполагаем, что этот проект уже есть на вашем компьютере. В разделе 01 мы создадим его за пару минут, после чего вы сможете пошагово воспроизводить все описываемые действия. Это практическое руководство, которое нужно выполнить самостоятельно у себя на компьютере.
Прочитав эту статью, вы получите:
- Пошаговый рабочий процесс разработки от создания проекта до фиксации изменений, который закрепится на уровне мышечной памяти
- Шаблон файла
AGENTS.md, готовую формулу промпта для ИИ и примеры консольных команд - Навыки настройки автопроверок кода силами самого Codex
- Опыт безопасного коммита изменений с контролем результатов работы ИИ
- Итоговую таблицу соответствия шагов разработки разделам нашего курса для применения в реальных проектах
⚠️ Команды, флаги и настройки в этой главе соответствуют официальной документации Codex. Конкретные имена моделей и интерфейсы утилит могут меняться от версии к версии, ориентируйтесь на вывод справки
codex --help.
01 Подготовка окружения: создаем TODO-приложение за две минуты
Для начала подготовим объект разработки, с которым будем работать.
Аналогия: подготовка квартиры перед ремонтом. Без стен вы не сможете начать отделку. Наш скрипт todo.py — это черновой каркас, содержащий базовые функции (хранение данных, интерфейс ввода), к которому мы добавим новый модуль (удаление задач).
Создайте в чистой папке файл todo.py с кодом (подходит для любых ОС с установленным Python 3):
# todo.py
import sys
TODOS = []
def add(item):
TODOS.append(item)
print(f"已添加：{item}")
def list_todos():
if not TODOS:
print("（暂无待办）")
return
for i, item in enumerate(TODOS, 1):
print(f"{i}. {item}")
def main():
if len(sys.argv) < 2:
print("用法：python todo.py [add <内容> | list]")
return
cmd = sys.argv[1]
if cmd == "add":
add(" ".join(sys.argv[2:]))
elif cmd == "list":
list_todos()
else:
print(f"未知命令：{cmd}")
if __name__ == "__main__":
main()Проверьте работоспособность скрипта в терминале:
python todo.py add Купить кофе
python todo.py listОжидаемый вывод:
已添加：Купить кофе
（暂无待办）Обратите внимание на особенность архитектуры: поскольку список задач TODOS хранится только в оперативной памяти процесса, после завершения работы скрипта данные теряются, поэтому команда list показывает пустой список. Это нормальное поведение для нашего тестового стенда, учтите его при проверках в разделе 05.
Инициализируйте репозиторий Git и сделайте первый коммит:
git init
git add todo.py
git commit -m "init: initial version of TODO app"💡 Резюме в одном предложении: Создайте файл
todo.pyс базовым кодом хранения задач в памяти и инициализируйте репозиторий Git для фиксации изменений.
02 Шаг 1: Описываем правила проекта в AGENTS.md
При запуске в новой папке Codex не знает правил сборки и стандартов кодирования вашего проекта. Первым шагом подготовим чек-лист требований. Это концепция из 11-й статьи про AGENTS.md.
Аналогия: памятка для приходящего мастера. Каким бы профессионалом он ни был, без вашей памятки он не узнает, где находится счетчик, какие материалы можно использовать и как перекрыть воду в случае аварии. Файл AGENTS.md — это такая памятка на входе в проект.
Создайте в корневой папке файл AGENTS.md со следующим текстом:
# TODO CLI Tool
Простой консольный инструмент для управления задачами на Python 3 без внешних зависимостей.
## Запуск
- Добавление: `python todo.py add <содержимое>`
- Список: `python todo.py list`
## Правила разработки
- Использовать только стандартную библиотеку Python.
- Сохранять существующий консольный интерфейс (`python todo.py <команда> <аргументы>`).
- Код должен запускаться без ошибок указанными выше командами.
## Тестирование
- При создании тестов использовать встроенный модуль `unittest`, имя файла — `test_todo.py`.
- Команда запуска тестов: `python -m unittest`.Помните правило из 11-й статьи: не перегружайте правила водой. Опустите информацию об истории создания утилиты и планах компании — пишите только технические требования. Наш файл уложился в 20 строк.
💡 Резюме в одном предложении: Подготовьте лаконичный файл
AGENTS.mdс описанием правил запуска, тестирования и ограничений разработки проекта.
03 Шаг 2: Постановка задачи по формуле
Качество работы ИИ напрямую зависит от точности постановки задачи. Использование четырехкомпонентной формулы исключит ошибки толкования требований. Это концепция из 13-й статьи о написании промптов.
Аналогия: составление бланка заказа. Вы описываете, что нужно сделать (цель), какие части здания можно менять (область изменений), какие материалы использовать (ограничения) и как вы будете принимать работу (критерии готовности).
Запустите интерактивную сессию Codex:
codexОтправьте ИИ следующее детальное техническое задание (скопируйте текст):
Добавь функцию удаления задач в todo.py.
Цель: Реализовать команду `python todo.py done <номер>`, которая удаляет задачу по её порядковому номеру из списка.
Область изменений: Внести правки в todo.py, создать или обновить тесты. Сохранять консольный стиль утилиты. Не подключать внешние библиотеки.
Ограничения: Нумерация задач начинается с 1. При вводе некорректного номера (не число или выход за границы списка) выводить понятное сообщение об ошибке вместо падения скрипта.
Критерии готовности: Покрыть тестами unittest сценарии успешного удаления, выхода за границы и ввода не-числа. Все тесты по команде `python -m unittest` должны проходить успешно.Сравнение подходов:
| ❌ Размытый промпт | ✅ Структурированный промпт |
|---|---|
| «Сделай удаление задач» | Задана точная команда done <номер> |
| Не указаны границы изменений | Ограничена область: только todo.py и тесты |
| Не описано поведение при ошибках | Задано поведение при некорректном вводе номера |
| Непонятно, как сдавать работу | Критерием готовности объявлены проходящие тесты unittest |
Постановка точных критериев готовности экономит ваше время. В противном случае ИИ может забыть обработать пустые значения ввода, и вам придется просить его исправить баги в следующих раундах диалога.
💡 Резюме в одном предложении: Опишите задачу по формуле «Цель + Область + Ограничения + Готовность» для минимизации циклов переделки кода.
04 Шаг 3: Настройка параметров песочницы
Перед началом изменений настройте границы безопасности для Codex. Это тема 15-й статьи про уровни доступа песочницы.
Аналогия: выдача ключей сотруднику. Вы даете доступ только в те помещения, где он должен работать, блокируя проход в закрытые зоны.
Для нашей задачи оптимален режим «запись в рабочую папку с запросом подтверждений» — ИИ сможет менять файлы проекта и запускать тесты, но при попытке сетевых запросов или изменения системных файлов процесс будет остановлен для подтверждения.
Запуск сессии с указанием параметров безопасности:
codex --sandbox workspace-write --ask-for-approval on-requestИли настройка в глобальном файле ~/.codex/config.toml:
# ~/.codex/config.toml
sandbox_mode = "workspace-write"
approval_policy = "on-request"Помните о правилах работы песочницы в режиме workspace-write:
| Параметр | Поведение по умолчанию |
|---|---|
| Сетевой доступ | Заблокирован (требуется явное включение) |
| Папка метаданных Git | Защищена от изменения (только чтение) |
| Границы изменений | Ограничены каталогом проекта |
Не используйте режим danger-full-access без явной необходимости. При работе в пустых или временных папках без Git-репозитория Codex автоматически принудительно переключится в безопасный режим read-only для предотвращения повреждения системных файлов.
💡 Резюме в одном предложении: Запустите Codex в режиме
workspace-writeс подтверждениямиon-requestдля баланса удобства разработки и безопасности системы.
05 Шаг 4: Автоматическая проверка кода силами ИИ
Не проверяйте результаты работы ИИ глазами. Поручите Codex самостоятельно запустить тесты и подтвердить корректность изменений.
Аналогия: самопроверка мастера перед сдачей объекта. Вы просите его проверить работу сантехники под давлением до того, как он пригласит вас на приемку.
Поскольку мы указали правила тестирования в AGENTS.md и промпте, Codex должен сам создать файл тестов test_todo.py и запустить проверку. На экране консоли вы увидите вывод тестов:
...
----------------------------------------------------------------------
Ran 3 tests in 0.003s
OKЕсли ИИ не запустил тесты автоматически, отправьте команду в чате:
Запусти тесты командой python -m unittest и покажи результат. При наличии ошибок исправь код до полного прохождения проверок.Как мы упоминали в разделе 01, из-за хранения данных в памяти ручная проверка в консоли по цепочке команд add-done-list не сработает. Только автоматические тесты в рамках одного процесса Python могут корректно провалидировать логику работы с памятью.
💡 Резюме в одном предложении: Обяжите Codex запустить тесты
unittestи добиться статусаOKперед тем, как переходить к оценке результатов изменений.
06 Использование дополнительных инструментов (MCP и под-агентов)
Для текущего небольшого проекта одного файла дополнительные инструменты не требуются. Но важно уметь определять границы их применимости.
Аналогия: вызов бригады рабочих. Для покраски одной стены достаточно одного маляра (основной агент). Но если нужно покрасить все комнаты в доме одновременно, вы нанимаете бригаду подсобных рабочих (под-агенты). А если нужно заказать редкую краску со склада — подключаете службу снабжения (коннекторы MCP).
Правила выбора инструментов:
- Множество параллельных задач — используйте под-агентов (Subagents). Например, для пакетной замены устаревших функций в 20 файлах проекта (тема 21-й статьи).
- Доступ к внешним базам данных и службам — подключайте коннекторы протокола MCP (тема 20-й статьи).
| Сценарий | Выбор инструмента | Обоснование |
|---|---|---|
| Разработка функции удаления в одном файле | ❌ Только главный агент | Задача проста, параллелизм не требуется |
| Массовое обновление импортов во всем проекте | ✅ Под-агенты | Позволяет ускорить выполнение за счет параллельного запуска |
| Проверка статуса заказа в CRM перед удалением | ✅ MCP-коннектор | Codex требует связи со сторонним API компании |
💡 Резюме в одном предложении: Не усложняйте проект вызовом под-агентов или MCP-коннекторов для простых задач в одном файле.
07 Шаг 5: Фиксация изменений в Git
После прохождения тестов перейдите к этапу коммита изменений. Это тема 26-й статьи об интеграции с Git.
Аналогия: подписание акта приемки. ИИ подготовил документы и отчеты, а вы проверяете их и ставите свою подпись.
Отправьте команду в чат:
Подготовь коммит: изучи git status и git diff, составь краткое описание изменений на русском языке с префиксом feat: и покажи мне перед коммитом.Codex выполнит следующие действия:
- Проверит измененные файлы через
git status. - Изучит внесенные правки через
git diff. - Подготовит текст коммита (например,
feat: добавлена функция удаления задач и юнит-тесты).
Обратите внимание: автоматический запуск git commit силами ИИ требует включения экспериментального флага codex_git_commit в настройках. Рекомендуется проверять diff изменений лично и запускать команду git commit вручную в консоли, чтобы исключить попадание временных файлов в историю Git.
Проверьте лог изменений в терминале:
git log --oneline -1Вывод команды должен содержать хэш и текст вашего коммита:
a1b2c3d feat: добавлена функция удаления задач и юнит-тесты💡 Резюме в одном предложении: Поручите Codex проанализировать изменения и составить текст коммита, но финальное выполнение команды
git commitпроизводите вручную для контроля целостности репозитория.
08 Карта прохождения шагов проекта
Мы собрали все этапы разработки в единый рабочий процесс. Ниже приведена таблица соответствия шагов разделам нашего курса:
| Этап разработки | Действие пользователя | Раздел курса |
|---|---|---|
| 1. Инициализация | Создание файлов проекта, Git init | Глава 03 (Установка) |
| 2. Инструктаж | Написание файла правил AGENTS.md | Глава 11 (AGENTS.md) |
| 3. Постановка задачи | Запрос по формуле с указанием тестов | Глава 13 (Промпты) |
| 4. Безопасность | Запуск сессии в режиме workspace-write | Глава 15 (Песочница) |
| 5. Проверка | Контроль тестов unittest силами ИИ | Глава 13 (Самопроверка) |
| 6. Фиксация | Анализ diff и коммит изменений | Глава 26 (Интеграция с Git) |
Для этого проекта мы использовали стандартную модель gpt-5.5 с уровнем рассуждений по умолчанию (medium), чего достаточно для большинства задач.
💡 Резюме в одном предложении: Интеграция шагов «AGENTS.md → промпт по формуле → песочница → автотесты → ручной коммит» формирует надежный цикл разработки с ИИ, применимый к любым проектам.
Итоги
Мы завершили комплексный практический проект разработки функционала с использованием инструментов Codex.
Главные выводы занятия:
- Подготовка — всегда начинайте работу с описания правил проекта в файле
AGENTS.md. - Точность промпта — подробно описывайте критерии готовности, включая команды запуска тестов.
- Безопасность — ограничивайте доступ ИИ к файлам на уровне песочницы
workspace-write. - Автотесты — заставляйте ИИ самостоятельно проверять код тестами до сдачи работы.
- Git — доверяйте ИИ написание коммитов, но фиксируйте изменения вручную.
Применение этой цепочки шагов на практике позволит вам разрабатывать качественный и безопасный код при поддержке искусственного интеллекта.
В следующей статье 35 · Шпаргалка по командам и конфигурациям мы соберем все полезные команды, горячие клавиши и параметры конфигурационного файла config.toml в одну краткую справочную таблицу.