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

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

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

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

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

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

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

Песочница и подтверждения — это разные вещи

Имена sandbox не менялись: read-only / workspace-write / danger-full-access. Их задаёте в ~/.codex/config.toml или флагом --sandbox. Это куда агенту можно писать.

Отдельно — подтверждения перед действием (suggest / auto-edit / full-auto). Не путайте: sandbox_mode suggest — ошибка, такого значения sandbox нет.

Модель по умолчанию: gpt-5.6-sol / gpt-5.6. В домашнее задание номер релиза CLI не ставьте.

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

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

flowchart TD
    A["Три режима подтверждений"] --> 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 --approval-mode suggest
# или в config.toml: approval_mode = "suggest"

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

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

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

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

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

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

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

codex --approval-mode auto-edit
# или в config.toml: approval_mode = "auto-edit"

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

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

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

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

codex --approval-mode full-auto --trusted-workspace
# или настройка permission profiles (см. документацию OpenAI)

Поведение: 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: Простой рефакторинг (автоматический)

# Запустить Codex в режиме auto-edit
codex --approval-mode auto-edit "улучши качество кода в 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 workspace-write

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

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

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

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

1. Песочница — read-only / workspace-write / danger-full-access. Подтверждения — отдельно: suggest / auto-edit / full-auto. Не смешивайте имена.

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

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

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

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

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

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

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