# Автоматизация и CI/CD

Claude Code поддерживает headless-режим: его можно использовать в скриптах, конвейерах CI/CD и автоматизированных процессах без участия человека. В статье собран полный справочник параметров и несколько реальных сценариев.

---

## 1. Базовое использование

### Однократный запуск (режим -p)

```bash
# Обычный запуск
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
```

### Ограничение доступных инструментов

```bash
# Только чтение (без записи и выполнения команд)
claude -p "Проанализируй качество кода" --allowedTools Read,Glob,Grep

# Чтение и запись (без выполнения команд)
claude -p "Отрефактори этот файл" --allowedTools Read,Write,Edit,Glob,Grep

# Все инструменты (в контролируемом окружении)
claude -p "Исправь ошибки линтера" --allowedTools Read,Write,Edit,Bash,Glob,Grep
```

### Пропуск запросов на подтверждение

```bash
# Только в безопасном изолированном окружении!
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-ревью кода

```yaml
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: автоматическая генерация тестов

```yaml
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: контроль качества кода

```yaml
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

```bash
#!/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: автоматическое обновление документации

```bash
#!/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:

```dockerfile
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"]
```

Запуск:

```bash
docker build -t claude-ci .
docker run --rm -e ANTHROPIC_AUTH_TOKEN=cr_your_key claude-ci
```

---

## 5. Восстановление сессии и многошаговые конвейеры

### Многошаговые задачи

```bash
# Шаг 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: ограничивайте число ходов

```bash
# Для простой задачи хватит трёх ходов
claude -p "Быстрый анализ" --max-turns 3

# Для сложной — не больше десяти
claude -p "Полный рефакторинг" --max-turns 10
```

### Стратегия 2: выбирайте подходящую модель

| Сценарий | Рекомендуемая модель | Почему |
|------|---------|------|
| Ревью кода | Sonnet | Достаточно и дёшево |
| Сканирование безопасности | Opus | Нужен глубокий анализ |
| Массовое форматирование | Haiku | Самая дешёвая |
| Генерация тестов | Sonnet | Лучшее соотношение цены и качества |

```bash
claude -p "Отформатируй код" --model claude-haiku-4-5 --max-turns 3
```

### Стратегия 3: ограничивайте инструменты, чтобы тратить меньше токенов

```bash
# Анализ только на чтение → не будет циклов записи и тестов
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. Чек-лист лучших практик

1. **Всегда ограничивайте число ходов**: в CI используйте `--max-turns`, чтобы избежать бесконечного выполнения
2. **Ограничивайте инструменты**: через `--allowedTools` открывайте только необходимое
3. **Изолируйте через Docker**: `--dangerously-skip-permissions` допустим только в контейнере
4. **Вывод в JSON**: в автоматизации удобнее `--output-format json`
5. **Контроль расходов**: анализ — на Sonnet, простые задачи — на Haiku
6. **Идемпотентность**: повторный запуск не должен давать побочных эффектов
7. **Таймауты**: задайте job timeout в конвейере (например, 10 минут)
8. **Управление ключами**: API-ключ храните в secrets CI, не зашивайте в код

---

## Следующие шаги

- [Система Hooks](/docs/advanced/hooks) — автоматический запуск действий
- [Приёмы работы в CLI](/docs/usage/cli-tips) — больше способов работы из командной строки
- [Оптимизация расходов](/docs/usage/cost-optimization) — приёмы контроля затрат
- [Полное руководство по Claude Code](/docs/getting-started/claude-code-tutorial) — с нуля до уверенного владения