Автоматизация и CI/CD
Полное освоение headless-режима Claude Code — справочник параметров, пять примеров CI/CD, изоляция в Docker, восстановление сессии и сравнение с Codex
Содержание
Claude Code поддерживает headless-режим: его можно использовать в скриптах, конвейерах CI/CD и автоматизированных процессах без участия человека. В статье собран полный справочник параметров и несколько реальных сценариев.
1. Базовое использование¶
Однократный запуск (режим -p)¶
# Обычный запуск
claude -p "Проанализируй архитектуру этого проекта"
# Вывод в формате JSON
claude -p "Перечисли все комментарии TODO" --output-format json
# Ограничить число ходов
claude -p "Напиши модульные тесты для UserService" --max-turns 5
# Указать модель (для повседневных задач подойдёт claude-sonnet-5; 4.x тоже в продаже)
claude -p "Проверь код на проблемы безопасности" --model claude-opus-5
Ограничение доступных инструментов¶
# Только чтение (без записи и выполнения команд)
claude -p "Проанализируй качество кода" --allowedTools Read,Glob,Grep
# Чтение и запись (без выполнения команд)
claude -p "Отрефактори этот файл" --allowedTools Read,Write,Edit,Glob,Grep
# Все инструменты (в контролируемом окружении)
claude -p "Исправь ошибки линтера" --allowedTools Read,Write,Edit,Bash,Glob,Grep
Пропуск запросов на подтверждение¶
# Только в безопасном изолированном окружении!
claude -p "Исправь все ошибки линтера и закоммить" --dangerously-skip-permissions
Предупреждение о безопасности:
--dangerously-skip-permissionsпропускает все подтверждения прав. Используйте его только в контейнере Docker или изолированном окружении CI.
2. Полный справочник параметров¶
Управление выполнением¶
| Параметр | Описание | Пример |
|---|---|---|
-p "prompt" |
Headless-режим, одна задача | claude -p "проанализируй архитектуру" |
--bare |
Минимальный режим, без hooks/LSP/plugins | claude --bare -p "..." |
--max-turns N |
Ограничение числа ходов | --max-turns 5 |
--model MODEL |
Выбор модели | --model claude-opus-5 |
--dangerously-skip-permissions |
Пропустить все подтверждения | Только изолированное окружение |
Форматы вывода¶
| Параметр | Описание | Когда применять |
|---|---|---|
--output-format text |
Простой текст (по умолчанию) | Для чтения человеком |
--output-format json |
Структурированный JSON | Для скриптов |
--output-format stream-json |
Потоковый JSON | Обработка в реальном времени |
Ограничение инструментов¶
| Параметр | Описание |
|---|---|
--allowedTools Tool1,Tool2 |
Разрешить только перечисленные инструменты |
Доступные имена инструментов: Read, Write, Edit, Bash, Glob, Grep, WebFetch, WebSearch, Agent, NotebookEdit
Управление сессиями¶
| Параметр | Описание |
|---|---|
--session-id ID |
Задать идентификатор сессии |
--resume |
Возобновить предыдущую сессию |
Переменные окружения¶
| Переменная | Описание |
|---|---|
ANTHROPIC_BASE_URL |
Эндпоинт API (QCode.cc: https://api.qcode.cc/api) |
ANTHROPIC_AUTH_TOKEN |
API-ключ (начинается с cr_) |
CLAUDE_CODE_MAX_TURNS |
Число ходов по умолчанию |
CLAUDE_CODE_OUTPUT_FORMAT |
Формат вывода по умолчанию |
CLAUDE_MODEL |
Модель по умолчанию |
3. Практика CI/CD¶
Пример 1: GitHub Actions — AI-ревью кода¶
name: AI Code Review
on: [pull_request]
jobs:
review:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0 # полная история, нужна для diff
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: '22'
- name: Install Claude Code
run: npm install -g @anthropic-ai/claude-code
- name: AI Code Review
env:
ANTHROPIC_BASE_URL: "https://api.qcode.cc/api"
ANTHROPIC_AUTH_TOKEN: ${{ secrets.QCODE_API_KEY }}
run: |
# Получаем файлы, изменённые в PR
FILES=$(git diff --name-only origin/${{ github.base_ref }}...HEAD)
claude -p "Проверь изменения кода в следующих файлах, обрати внимание на:
1. Уязвимости безопасности (SQL-инъекции, XSS, утечки секретов)
2. Проблемы производительности (N+1 запросы, утечки памяти)
3. Логические ошибки
4. Проблемы стиля кода
Изменённые файлы:
$FILES" \
--output-format json \
--max-turns 3 \
--model claude-sonnet-5 \
--allowedTools Read,Glob,Grep \
> review.json
echo "Review completed"
cat review.json | jq -r '.result' || cat review.json
Пример 2: автоматическая генерация тестов¶
name: Auto Generate Tests
on:
push:
paths: ['src/**/*.ts', '!src/**/*.test.ts']
jobs:
generate-tests:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: '22'
- name: Install dependencies
run: |
npm ci
npm install -g @anthropic-ai/claude-code
- name: Generate missing tests
env:
ANTHROPIC_BASE_URL: "https://api.qcode.cc/api"
ANTHROPIC_AUTH_TOKEN: ${{ secrets.QCODE_API_KEY }}
run: |
claude -p "Просмотри файлы .ts в src/ и напиши модульные тесты для тех, у которых их нет.
Используй Vitest + Testing Library.
Файлы тестов называй xxx.test.ts и клади рядом с исходником.
Целевое покрытие — от 80%." \
--max-turns 10 \
--allowedTools Read,Write,Glob,Grep,Bash \
--dangerously-skip-permissions
- name: Run tests
run: npx vitest --run
- name: Create PR with tests
if: success()
run: |
git config user.name "claude-bot"
git config user.email "bot@qcode.cc"
git checkout -b auto-tests-$(date +%s)
git add '*.test.ts'
git commit -m "test: auto-generated unit tests" || exit 0
git push origin HEAD
Пример 3: контроль качества кода¶
name: Code Quality Gate
on: [pull_request]
jobs:
quality:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: '22'
- run: npm install -g @anthropic-ai/claude-code
- name: Quality Analysis
env:
ANTHROPIC_BASE_URL: "https://api.qcode.cc/api"
ANTHROPIC_AUTH_TOKEN: ${{ secrets.QCODE_API_KEY }}
run: |
claude -p "Проанализируй качество кода и выведи JSON:
{
\"score\": 0-100,
\"issues\": [{\"severity\": \"high|medium|low\", \"file\": \"...\", \"description\": \"...\"}],
\"summary\": \"итог одной строкой\"
}
Критерии оценки:
- Типобезопасность (20 баллов)
- Обработка ошибок (20 баллов)
- Покрытие тестами (20 баллов)
- Читаемость (20 баллов)
- Безопасность (20 баллов)" \
--output-format json \
--max-turns 3 \
--model claude-sonnet-5 \
--allowedTools Read,Glob,Grep \
> quality.json
- name: Check score
run: |
SCORE=$(cat quality.json | jq -r '.result' | jq -r '.score // 0')
echo "Quality score: $SCORE"
if [ "$SCORE" -lt 60 ]; then
echo "Quality gate failed: score $SCORE < 60"
exit 1
fi
Пример 4: автогенерация Changelog¶
#!/bin/bash
# generate-changelog.sh — собрать changelog из коммитов git
export ANTHROPIC_BASE_URL="https://api.qcode.cc/api"
export ANTHROPIC_AUTH_TOKEN="cr_your_api_key"
# Коммиты с момента последнего тега
LAST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo "")
if [ -z "$LAST_TAG" ]; then
COMMITS=$(git log --oneline -20)
else
COMMITS=$(git log --oneline ${LAST_TAG}..HEAD)
fi
claude -p "Составь структурированный changelog по этим коммитам git:
$COMMITS
Формат:
## [версия] - $(date +%Y-%m-%d)
### Новое
### Исправления
### Улучшения
### Ломающие изменения (если есть)
Пиши по-русски, кратко и профессионально." \
--output-format text \
--max-turns 2 \
--model claude-sonnet-5 \
--allowedTools Read,Glob,Grep
Пример 5: автоматическое обновление документации¶
#!/bin/bash
# update-docs.sh — обновить документацию API после изменений кода
export ANTHROPIC_BASE_URL="https://api.qcode.cc/api"
export ANTHROPIC_AUTH_TOKEN="cr_your_api_key"
claude -p "Просмотри файлы маршрутов в src/api/ и сравни их с документацией в docs/api.md.
Найди описания API, которых не хватает или которые устарели, и обнови docs/api.md.
Сохрани текущий формат и стиль документа." \
--max-turns 8 \
--allowedTools Read,Write,Edit,Glob,Grep
4. Изоляция через Docker¶
Если вы используете --dangerously-skip-permissions в CI/CD, настоятельно рекомендуем запускать всё в контейнере Docker:
FROM node:22-slim
# Устанавливаем Claude Code
RUN npm install -g @anthropic-ai/claude-code
# Устанавливаем зависимости проекта
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
# Переменные окружения QCode.cc
ENV ANTHROPIC_BASE_URL=https://api.qcode.cc/api
# ANTHROPIC_AUTH_TOKEN передаётся во время запуска
# Запуск от непривилегированного пользователя
RUN useradd -m claude
USER claude
CMD ["claude", "-p", "Выполни ревью кода", "--dangerously-skip-permissions", "--max-turns", "5"]
Запуск:
docker build -t claude-ci .
docker run --rm -e ANTHROPIC_AUTH_TOKEN=cr_your_key claude-ci
5. Восстановление сессии и многошаговые конвейеры¶
Многошаговые задачи¶
# Шаг 1: анализ
claude -p "Проанализируй архитектуру проекта" \
--session-id "pipeline-42" \
--output-format json \
--max-turns 3 \
--allowedTools Read,Glob,Grep
# Шаг 2: на основе анализа составить план
claude -p "На основе предыдущего анализа составь план рефакторинга" \
--resume --session-id "pipeline-42" \
--max-turns 3
# Шаг 3: выполнить план
claude -p "Выполни первый шаг плана рефакторинга" \
--resume --session-id "pipeline-42" \
--max-turns 10 \
--allowedTools Read,Write,Edit,Bash,Glob,Grep
6. Контроль расходов¶
Стратегия 1: ограничивайте число ходов¶
# Для простой задачи хватит трёх ходов
claude -p "Быстрый анализ" --max-turns 3
# Для сложной — не больше десяти
claude -p "Полный рефакторинг" --max-turns 10
Стратегия 2: выбирайте подходящую модель¶
| Сценарий | Рекомендуемая модель | Почему |
|---|---|---|
| Ревью кода | Sonnet | Достаточно и дёшево |
| Сканирование безопасности | Opus | Нужен глубокий анализ |
| Массовое форматирование | Haiku | Самая дешёвая |
| Генерация тестов | Sonnet | Лучшее соотношение цены и качества |
claude -p "Отформатируй код" --model claude-haiku-4-5 --max-turns 3
Стратегия 3: ограничивайте инструменты, чтобы тратить меньше токенов¶
# Анализ только на чтение → не будет циклов записи и тестов
claude -p "Проанализируй код" --allowedTools Read,Glob,Grep --max-turns 3
7. Сравнение с headless-режимом Codex¶
| Параметр | Claude Code -p | Codex headless |
|---|---|---|
| Параметр запуска | -p "prompt" |
codex -q "prompt" |
| Песочница | Нужна изоляция через Docker | Встроенная песочница уровня ядра |
| Форматы вывода | text/json/stream-json | text/json |
| Восстановление сессии | --resume --session-id |
Не поддерживается |
| Ограничение инструментов | --allowedTools |
--approval-mode |
| Параллельное выполнение | Не поддерживается | codex cloud exec |
Как сочетать: Claude Code — для анализа и планирования (только чтение), Codex — для выполнения (полностью автоматически).
Тариф QCode.cc делит квоту между инструментами, поэтому переключение между ними в CI ничего не стоит.
8. Чек-лист лучших практик¶
- Всегда ограничивайте число ходов: в CI используйте
--max-turns, чтобы избежать бесконечного выполнения - Ограничивайте инструменты: через
--allowedToolsоткрывайте только необходимое - Изолируйте через Docker:
--dangerously-skip-permissionsдопустим только в контейнере - Вывод в JSON: в автоматизации удобнее
--output-format json - Контроль расходов: анализ — на Sonnet, простые задачи — на Haiku
- Идемпотентность: повторный запуск не должен давать побочных эффектов
- Таймауты: задайте job timeout в конвейере (например, 10 минут)
- Управление ключами: API-ключ храните в secrets CI, не зашивайте в код
Следующие шаги¶
- Система Hooks — автоматический запуск действий
- Приёмы работы в CLI — больше способов работы из командной строки
- Оптимизация расходов — приёмы контроля затрат
- Полное руководство по Claude Code — с нуля до уверенного владения