Урок 2: Агентный режим и мультифайловые изменения

Чему вы научитесь

• Как работает агентный режим с TUI (Terminal User Interface)
• Три режима безопасности: suggest, auto-edit, full-auto
• Как Codex читает, редактирует и создает файлы
• Как запускать команды, тесты и линтеры через агента
• Как использовать git-интеграцию для безопасных изменений

Введение: Агентный режим как расширение для разработчика

В первом уроке мы использовали Codex в режиме “спроси” — просто печатаем команду и получаем ответ. Но реальная мощь Codex раскрывается в агентном режиме, где он может:

• Самостоятельно читать файлы вашего проекта
• Анализировать структуру и зависимости
• Предлагать и применять изменения
• Запускать команды (тесты, линтеры, сборка)
• Создавать новые файлы
• Работать с Git (создавать ветки, коммиты)

Это похоже на то, как если бы вы наняли опытного разработчика, который может самостоятельно рефакторить ваш код, но всегда просит вашего одобрения перед серьезными действиями.

Три режима безопасности: выберите уровень риска

Codex имеет три режима работы. Выбираем в зависимости от уровня доверия и задачи:

flowchart TD
    A["Три режима sandbox"] --> B["suggest\nПоказывает дифф\nЖдёт y/n"]
    A --> C["auto-edit\nРедактирует файлы сам\nСпрашивает для опасных команд"]
    A --> D["full-auto\nВыполняет всё сам\nБез подтверждений"]
    B --> E["Риск: минимальный\nДля: первые дни,\nкритичный код"]
    C --> F["Риск: средний\nДля: основная\nразработка"]
    D --> G["Риск: высокий\nДля: только с Git-бэкапом\nи проверенным AGENTS.md"]

Режим 1: SUGGEST (самый безопасный)

codex config set sandbox_mode suggest

Поведение: Codex только предлагает изменения, не применяет их. Вы видите дифф и решаете, применять ли.

Анализирую структуру...

Предложение #1: Переместить утилитарные функции
src/utils.py (новый файл)

def format_date(date): return date.strftime(“%Y-%m-%d”)

Применить? (y/n)

Когда использовать: первые дни работы с Codex, критичные части кода, когда вы не доверяете агенту

Режим 2: AUTO-EDIT (баланс)

codex config set sandbox_mode auto-edit

Поведение: Codex самостоятельно редактирует файлы, но просит подтверждение перед выполнением команд (особенно опасных: delete, drop БД и т.п.)

[+] Создал src/utils.py
[+] Обновил src/main.py (добавлены импорты)
Запустить тесты для проверки? (y/n)

Когда использовать: основной режим для разработки, когда вы уже привыкли к Codex и доверяете его изменениям

Режим 3: FULL-AUTO (полная автономия)

codex config set sandbox_mode full-auto

Поведение: Codex выполняет все действия самостоятельно, включая опасные команды. Максимальная скорость, минимальный контроль.

[!] Внимание: используйте только если:

• Проект в Git и регулярно коммитится
• Вы уверены в инструкциях (AGENTS.md хорошо написан)
• Есть резервная копия

# Рискованный пример
codex "удали все старые файлы конфигурации" # В режиме full-auto это опасно!

Terminal User Interface (TUI): красивый интерфейс агента

При запуске в агентном режиме Codex открывает интерактивный интерфейс:

┌─────────────────────────────────────────────────────────┐
│ Codex Agent [project: my-app]                    [Exit] │
├─────────────────────────────────────────────────────────┤
│ Current Task: Refactor utilities module              │
│                                                         │
│ Analyzing files...                                   │
│    - src/utils.py (127 lines)                           │
│    - src/main.py (89 lines)                             │
│    - tests/test_utils.py (45 lines)                     │
│                                                         │
│ Plan:                                                │
│  1. Extract formatting functions → format_utils.py     │
│  2. Extract validation functions → validate_utils.py   │
│  3. Update imports in main.py                           │
│  4. Run tests to verify                                 │
│                                                         │
├─────────────────────────────────────────────────────────┤
│ ▶ Press SPACE to continue, Q to exit                    │
└─────────────────────────────────────────────────────────┘

Горячие клавиши в TUI:

Работа с файлами: чтение, создание, редактирование

Пример 1: Простое создание файла

# Запросить создание файла
codex "создай файл config.py с классом Config для управления конфигурацией"

Codex:

1. Проанализирует проект
2. Предложит структуру файла
3. В режиме suggest покажет содержимое
4. В режиме auto-edit создаст и спросит подтверждение

Результат:

[+] Created: config.py

class Config:
    """Управление конфигурацией приложения."""

    def __init__(self, env: str = "dev"):
        self.env = env
        self.debug = env == "dev"

    def get(self, key: str) -> str:
        return os.getenv(key)

Пример 2: Редактирование существующего файла

# Запросить улучшение функции
codex "улучши функцию calculate_sum в utils.py: добавь type hints и docstring"

Дифф (что Codex собирается изменить):

  def calculate_sum(numbers):
-     total = 0
-     for n in numbers:
-         total = total + n
-     return total

+ def calculate_sum(numbers: List[int]) -> int:
+     """Вычислить сумму списка чисел.
+
+     Args:
+         numbers: Список целых чисел
+
+     Returns:
+         Сумма всех чисел
+     """
+     return sum(numbers)

Пример 3: Мультифайловые изменения

# Самое мощное: рефакторинг модуля
codex "перенеси все функции работы с датами из utils.py в отдельный модуль date_utils.py"

Что произойдет:

1. Codex проанализирует utils.py полностью
2. Найдет все функции с датами
3. Создаст новый файл date_utils.py
4. Обновит импорты везде, где используются эти функции
5. Запустит тесты, чтобы убедиться, что ничего не сломалось

[+] Created: date_utils.py (6 functions moved)
[+] Updated: utils.py (removed 6 functions, updated imports)
[+] Updated: main.py (1 import added)
[+] Updated: handlers.py (2 imports added)
Running tests...
   [+] 45/45 tests passed

Запуск команд: тесты, линтеры, сборка

Codex может запускать команды в вашем проекте для проверки изменений.

Конфигурирование команд в AGENTS.md

# Инструкции для Codex

## Команды для тестирования

### Перед любыми изменениями
- `make lint` - проверить стиль кода
- `mypy src/` - проверить типы

### После изменений
- `pytest tests/ -v` - запустить все тесты
- `black --check src/` - проверить форматирование

### Исправление кода
- `black src/ && isort src/` - автоформатировать
- `pylint src/ --fail-under=8.0` - проверить качество

## Команды НЕ запускать без подтверждения
- `rm -rf` - удаление
- `git push` - отправка в репозиторий
- `pip uninstall` - удаление пакетов

Пример: Codex запускает тесты

# Попросить улучшить код И проверить тесты
codex "добавь логирование к функции process_data, затем запусти тесты"

Вывод:

Adding logging to process_data...
[+] Updated: src/core.py

Running tests...
> pytest tests/ -v

tests/test_core.py::test_process_data PASSED
tests/test_core.py::test_process_data_empty PASSED
tests/test_core.py::test_process_data_invalid PASSED

[+] All 3 tests passed in 2.1s

Git-интеграция: безопасные изменения

Codex имеет встроенную интеграцию с Git, что делает его очень безопасным.

Как это работает

# Перед работой Codex создает новую ветку
git checkout -b codex/refactor-utils

# Применяет изменения
# ... файлы редактируются ...

# Показывает дифф перед коммитом
git diff

# Если вы согласны, коммитит автоматически
git commit -am "refactor: move utility functions to separate modules"

# Ветка готова для создания Pull Request

Настройка git-интеграции

{
  "git_integration": true,
  "auto_commit": false,
  "create_pr": false,
  "branch_prefix": "codex/"
}

Пример: Полный workflow рефакторинга

# Начало: проект на main ветке
git status
# On branch main

# Запустить Codex в агентном режиме
codex "полностью рефакторь модуль src/api/ используя async/await"

# Вывод:
# 1. Creating branch codex/refactor-api...
# 2. Analyzing src/api/...
# 3. Creating plan...
#    - Convert 5 functions to async
#    - Update dependencies in routes.py
#    - Update tests to use asyncio
# 4. Applying changes...
# 5. Running tests... [+] 12/12 passed
# 6. Creating commit: refactor: convert API to async/await

# После завершения — ветка готова
git branch
#   codex/refactor-api
# * main

# Смотрим изменения перед merge
git log --oneline main..codex/refactor-api
# abc1234 refactor: convert API to async/await

# Можем создать PR
gh pr create --base main --head codex/refactor-api \
  --title "refactor: async API" \
  --body "Automated refactoring by Codex"

Диаграмма: Цикл агентного режима

graph LR
    A["1. Задача<br/>codex 'рефакторь...'"] --> B["2. Анализ<br/>Чтение файлов<br/>Построение плана"]
    B --> C["3. Режим?<br/>suggest/auto-edit/<br/>full-auto"]
    C -->|suggest| D["4. Показ дифф<br/>Ждет y/n"]
    C -->|auto-edit| E["4. Применение<br/>Спрашивает<br/>для опасных"]
    C -->|full-auto| F["4. Выполнение<br/>Без подтверждения"]
    D --> G["5. Применение<br/>изменений"]
    E --> G
    F --> G
    G --> H["6. Запуск команд<br/>тесты, линтеры"]
    H --> I["7. Git коммит<br/>ветка codex/..."]
    I --> J["[+] Готово<br/>для PR/merge"]

Попробуйте сами: задание на рефакторинг

Подготовка: создайте Python проект для теста

mkdir -p codex-training
cd codex-training

# Создать структуру
mkdir -p src tests

# Файл 1: основной модуль (плохой код)
cat > src/main.py << 'EOF'
def calculate_total(items):
    total = 0
    for item in items:
        price = item['price']
        quantity = item['qty']
        total = total + (price * quantity)
    return total

def format_output(result):
    return "TOTAL: " + str(result)

def process(data):
    t = calculate_total(data)
    f = format_output(t)
    return f
EOF

# Файл 2: тесты
cat > tests/test_main.py << 'EOF'
import pytest
from src.main import calculate_total, format_output

def test_calculate_total():
    items = [
        {'price': 10, 'qty': 2},
        {'price': 5, 'qty': 3}
    ]
    assert calculate_total(items) == 35

def test_format_output():
    assert format_output(100) == "TOTAL: 100"
EOF

# Инициализировать Git
git init
git add .
git commit -m "initial: test project"

Задание 1: Простой рефакторинг (автоматический)

# Переключиться в режим auto-edit
codex config set sandbox_mode auto-edit

# Запустить Codex
codex "улучши качество кода в src/main.py: добавь type hints, docstrings и используй более питоничный стиль"

Ожидаемое поведение:

• Codex покажет план: какие файлы изменит
• Применит изменения
• Запросит подтверждение для запуска тестов
• Запустит pytest и покажет результаты

Проверить результаты:

# Посмотреть, что изменилось
git diff

# Убедиться, что тесты прошли
pytest tests/ -v

Задание 2: Мультифайловый рефакторинг

# Создайте еще один файл
cat > src/utils.py << 'EOF'
def validate_price(price):
    if price < 0:
        return False
    return True

def apply_discount(price, discount_percent):
    return price * (1 - discount_percent / 100)
EOF

# Запросить извлечение логики
codex "создай модуль src/calculator.py и перенеси в него функции расчета из main.py и utils.py"

Ожидаемый результат:

• Новый файл calculator.py с логикой расчета
• Обновлены импорты в main.py и utils.py
• Тесты все еще проходят

Задание 3: Проверка TUI интерфейса

# Запустить в режиме suggest для интерактивной работы
codex config set sandbox_mode suggest

# Запросить серьезное улучшение
codex "добавь кэширование результатов и логирование к функции calculate_total"

# В TUI интерфейсе:
# 1. Нажмите SPACE чтобы увидеть план
# 2. Нажмите 'd' чтобы увидеть дифф
# 3. Нажмите 'y' чтобы применить

Точка контроля: все тесты должны пройти после каждого задания. Если не прошли, запросите у Codex: "исправь ошибки в коде, чтобы пройти все тесты"

Ключевые выводы

1. Три режима безопасности позволяют выбрать баланс между скоростью и контролем:

   • suggest — для критичного кода
   • auto-edit — стандартный режим для разработки
   • full-auto — только с хорошей подготовкой и Git бэкапом

2. TUI интерфейс делает работу с Codex удобной и визуальной, с горячими клавишами для управления

3. Мультифайловые изменения — самая мощная фишка: Codex может одновременно рефакторить несколько файлов и обновлять все импорты

4. Git-интеграция делает все изменения безопасными: каждая сессия в отдельной ветке, каждый шаг можно откатить

5. Команды для проверки (тесты, линтеры) встроены в workflow, так что Codex сразу верифицирует свои изменения

Следующий урок

Урок 3: GitHub Action и CI/CD интеграция

В следующем уроке вы узнаете, как автоматизировать рефакторинг прямо в CI/CD pipeline: GitHub Issue с label → автоматическое исправление → готовый PR.