AI-ассистенты в разработке: Claude Code и Codex на практике

Автодополнение предлагает следующую строку в редакторе, и человек принимает решение на каждом шаге. Агентный инструмент получает задачу целиком: сам находит нужные файлы, планирует, правит несколько файлов, запускает тесты и команды терминала, читает ошибки и исправляет их. Так работают Claude Code от Anthropic и Codex от OpenAI — в терминале, в расширениях IDE, в десктопных приложениях и в облаке.

Вместе с возможностями растёт и цена ошибки. Неудачная подсказка автодополнения — это одна строка, которую вы видите. Агент может изменить двадцать файлов, установить пакет, выполнить миграцию или прочитать файл с ключами. Поэтому работа с агентом держится на трёх опорах: инструкции проекта, технические ограничения и проверяемый результат.

Оба инструмента ставятся одной командой. Для Claude Code документация рекомендует нативный установщик; есть также Homebrew, WinGet и npm-пакет — ему нужен Node.js 22 или новее. Codex CLI ставится установщиком с chatgpt.com, через npm или Homebrew. Нужен и аккаунт: Claude Code при первом запуске просит войти с подпиской Claude или аккаунтом Anthropic Console, Codex — через ChatGPT или другим доступным способом входа.

# Claude Code: native installer (macOS, Linux, WSL)
curl -fsSL https://claude.ai/install.sh | bash

# Codex CLI: standalone installer (macOS, Linux)
curl -fsSL https://chatgpt.com/codex/install.sh | sh

# Alternative for both: global npm packages
npm install -g @anthropic-ai/claude-code
npm install -g @openai/codex

$ claude --version
2.1.296 (Claude Code)
$ codex --version
codex-cli 0.162.1

Запускайте агента из корня репозитория командой claude или codex. От рабочей папки зависят и файлы инструкций, которые он прочитает, и граница, внутри которой ему разрешено писать. Перед задачей закоммитьте текущее состояние или создайте ветку: документация Codex советует ставить Git-чекпоинты до и после задачи, чтобы изменения можно было откатить.

Каждая сессия агента начинается с чистого контекста. То, что вы иначе объясняли бы каждый раз, записывают в файл инструкций проекта. Codex читает AGENTS.md: сначала глобальный из ~/.codex, затем файлы от корня проекта вниз до текущей папки; ближний к рабочей папке читается последним и уточняет общие правила. Суммарный объём по умолчанию ограничен 32 КиБ (project_doc_max_bytes). AGENTS.md — открытый формат, его поддерживают и другие агенты; описание опубликовано на agents.md.

Claude Code читает CLAUDE.md в проекте, ~/.claude/CLAUDE.md с личными правилами и CLAUDE.local.md с настройками, которые не попадают в git. Если в проекте есть только AGENTS.md, свежие версии Claude Code читают его напрямую, но при наличии CLAUDE.md — только его. Надёжный способ держать один источник правил для обоих инструментов — общий AGENTS.md и короткий CLAUDE.md, который импортирует его строкой @AGENTS.md. Черновик можно получить командой /init: Claude Code разберёт проект и предложит команды и соглашения.

# AGENTS.md

## Project

- Online booking for a beauty salon: Next.js (App Router), TypeScript,
  PostgreSQL via Prisma.
- Application code is in `src/`, tests are in `tests/`,
  migrations are in `prisma/migrations/`.

## Commands

- Install dependencies: `npm ci`
- Type check: `npm run typecheck`
- Lint: `npm run lint`
- All tests: `npm test`
- One test file: `npm test -- tests/bookings.test.ts`

## Conventions

- TypeScript strict mode; no `any` in new code.
- Validate every external input with `zod` at the boundary
  (`src/schemas/`).
- Database access only through `src/db/`;
  never build SQL by string concatenation.
- New UI strings go to both `messages/ru.json` and `messages/en.json`.

## Workflow

- For changes that touch more than one file, propose a plan first
  and wait for confirmation.
- After changes, run type check, lint and the related tests,
  and show the output.
- Keep the diff limited to the task: no unrelated refactoring or reformatting.
- Ask before adding a production dependency.

## Security

- Never read, print or commit `.env` files, keys or tokens.
  If a new variable is needed, name it in the summary
  and leave the value to a human.
- Do not edit applied migrations in `prisma/migrations/`;
  create a new migration instead.
- Never run `git push`, deployments or commands
  against production databases.

## Definition of done

- Type check, lint and tests pass.
- New behavior is covered by a test.
- The summary lists what changed, how it was verified
  and what is still uncertain.

# CLAUDE.md

@AGENTS.md

## Claude Code

- Use plan mode for any change under `src/payments/`.
- Before reporting a task as done, review the diff
  against the acceptance criteria of the task.

Держите файл коротким. Документация Claude Code рекомендует меньше 200 строк на файл и для каждой строки спрашивать себя, ошибётся ли агент без неё: длинный файл расходует контекст, и важные правила в нём теряются. Повод дописать строку — агент дважды повторил одну ошибку или ревью нашло то, что он должен был знать. Правила для части кода выносят во вложенный AGENTS.md (Codex) или в .claude/rules/ с привязкой к путям (Claude Code).

Настоящая граница проходит здесь. Режим разрешений Claude Code задаёт, что агент делает без вопроса. С версии 2.1.283 интерактивные сессии в терминале и VS Code по умолчанию стартуют в режиме auto: действия проверяет отдельная модель-классификатор и блокирует рискованные. Режим меняется флагом --permission-mode, клавишами Shift+Tab в сессии или ключом permissions.defaultMode в настройках.

Поверх режима работают правила allow, ask и deny в .claude/settings.json. Порядок проверки — deny, затем ask, затем allow: широкий запрет не обходится узким разрешением, а правила deny действуют в любом режиме. Файл проекта коммитят, чтобы правила получила вся команда; личные исключения кладут в .claude/settings.local.json.

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "Bash(npm run typecheck)",
      "Bash(npm run lint)",
      "Bash(npm test *)"
    ],
    "ask": [
      "Bash(git push *)",
      "Bash(npm install *)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Bash(npx prisma migrate deploy *)"
    ],
    "disableBypassPermissionsMode": "disable"
  }
}

Важная оговорка из документации: правила Read и Bash — не абсолютная защита. Запрет Read(./.env) срабатывает для встроенных инструментов и распознанных команд вроде cat, но не для скрипта на Node.js или Python, который сам откроет файл; правило Bash(curl *) не остановит sh -c 'curl …'. Ограничение на уровне ОС даёт песочница (/sandbox), а надёжнее всего — не держать боевые секреты в рабочей копии вовсе.

Codex разделяет два слоя. Режим песочницы sandbox_mode задаёт, что агент может технически: read-only, workspace-write или danger-full-access. Политика подтверждений approval_policy — когда он должен спросить: on-request или never. В пресете Auto (workspace-write и on-request) Codex пишет только в рабочей папке, сеть для команд выключена, папки .git и .codex защищены от записи, а для выхода за эти границы он спрашивает. Флаг --dangerously-bypass-approvals-and-sandbox (он же --yolo) отключает и песочницу, и вопросы — документация оставляет его для окружений, изолированных снаружи.

# Project config: Codex loads it only after you mark the project as trusted
sandbox_mode = "workspace-write"
approval_policy = "on-request"

[sandbox_workspace_write]
network_access = false

Убедитесь, что настройки поняты так, как вы задумали. У обеих утилит есть команда doctor: она разбирает конфигурацию без запуска сессии и без обращения к модели.

$ codex doctor
  ✓ config       loaded
      config.toml parse        ok
  ✓ sandbox      restricted fs + restricted network · approval OnRequest

$ claude doctor
Invalid settings
- .claude/settings.json › permissions.defaultMode: Invalid value. Expected one of: "acceptEdits", "auto", "bypassPermissions", "default", "dontAsk", "plan"

Агент останавливается, когда работа «выглядит готовой». Если в задаче нет проверки, которую он может запустить сам, проверкой становитесь вы. Хорошая задача отвечает на четыре вопроса: где искать (файлы, модули, связанная задача), что должно получиться (поведение, а не «улучши»), как это проверить (тест, команда, ожидаемый ответ) и чего не трогать.

# Task: limit booking attempts per phone number

## Context

- The booking handler is `src/app/api/bookings/route.ts`.
- A rate limit helper already exists in `src/lib/rate-limit.ts`; reuse it.
- Tests for bookings are in `tests/bookings.test.ts`.

## Goal

Reject more than 3 booking requests from the same phone number
within 10 minutes.

## Acceptance criteria

- [ ] The 4th request for the same phone within 10 minutes returns HTTP 429
  with the body `{ "error": "too_many_requests" }`.
- [ ] Requests for other phone numbers are not affected.
- [ ] The limit resets after 10 minutes; the test uses fake timers,
  not real waiting.
- [ ] No new dependencies and no changes outside `src/app/api/bookings/`,
  `src/lib/` and `tests/`.

## Verification

Run `npm run typecheck`, `npm run lint`
and `npm test -- tests/bookings.test.ts`, then show the output.

## Out of scope

- UI changes.
- Database schema changes.

## How to work

1. Read the files above and propose a plan. Wait for my confirmation.
2. Write a failing test first, then the implementation.
3. Summarize the diff and list anything you were unsure about.

• Критерии формулируйте как проверяемые факты — код ответа, тело, граничный случай, — а не «работает корректно».
• Называйте существующий код для переиспользования, иначе агент может написать собственную копию.
• Ограничивайте область: список папок и раздел «вне задачи» защищают от попутного рефакторинга.
• Просите показать вывод проверок, а не фразу «тесты прошли»: по выводу ревью идёт быстрее.
• Одна сессия — одна задача. Документация Claude Code советует очищать контекст командой /clear между несвязанными задачами, а после двух неудачных исправлений — начать заново с уточнённым запросом.

Сгенерированный код выглядит уверенно независимо от того, верен ли он. Читайте весь дифф, а не только итоговый отчёт агента: отчёт описывает намерение, дифф — результат.

В архитектуре и незнакомом домене проблема не в синтаксисе, а в недостающем контексте: агент не знает договорённостей, которых нет в коде, и не спросит о них, если вы не попросили. Если вы сами не можете оценить результат, агент не снимает с вас ответственность за проверку. Документация Claude Code формулирует это прямо: то, что нельзя проверить, нельзя выпускать.