# الأتمتة و CI/CD

يدعم Claude Code وضعًا بلا واجهة يمكنك استخدامه في النصوص البرمجية وخطوط أنابيب CI/CD وسير العمل الآلي دون أي تفاعل بشري. تغطي هذه المقالة مرجع الخيارات الكامل وعدة سيناريوهات واقعية.

---

## 1. الاستخدام الأساسي

### تنفيذ لمرة واحدة (وضع -p)

```bash
# Basic run
claude -p "Analyse this project's architecture"

# JSON output
claude -p "List every TODO comment" --output-format json

# Cap the number of turns
claude -p "Write unit tests for UserService" --max-turns 5

# Pick a model (claude-sonnet-5 for everyday work; 4.x is still on sale)
claude -p "Review the code for security issues" --model claude-opus-5
```

### تقييد الأدوات المتاحة

```bash
# Read-only analysis (no writes, no command execution)
claude -p "Analyse code quality" --permission-mode dontAsk --allowedTools Read,Glob,Grep

# Read and write (no command execution)
claude -p "Refactor this file" --permission-mode dontAsk --allowedTools Read,Write,Edit,Glob,Grep

# All tools (controlled environment)
claude -p "Fix the lint errors" --permission-mode dontAsk --allowedTools Read,Write,Edit,Bash,Glob,Grep
```

> يعني `--allowedTools` أن «هذه الأدوات تعمل دون سؤال»؛ وهو وحده **لا** يقيّد أي أداة أخرى.
> لا تعرض الأمثلة أعلاه سوى الأدوات المدرجة لأنها تقترن بـ `--permission-mode dontAsk`، الذي يرفض
> كل ما ليس مدرجًا. لإخفاء الأدوات المدمجة الأخرى عن Claude بالكامل، استخدم `--tools`، مثل `--tools "Read,Edit,Bash"` (لا تُعرض سوى هذه الأدوات المدمجة الثلاث).

### اضبط وضع الأذونات صراحةً (لا تعتمد على الوضع الافتراضي)

بدءًا من Claude Code 2.1.285، **يبدأ `claude -p` و Agent SDK في `auto` عند عدم ضبط وضع أذونات** في الجلسات
التي لا تستطيع جلب أعلام الميزات: يراجع مصنّف الإجراءات التي تحتاج إلى موافقة، وتُحتسب طلبات المصنّف (النموذج
`claude-sonnet-5`) ضمن استخدامك. ولا يمنح الاتصال بـ QCode باستخدام `ANTHROPIC_AUTH_TOKEN` Claude Code أي
بيانات اعتماد لجلبها (وينطبق الأمر نفسه على حاويات CI التي تبدأ من جديد في كل تشغيل)، لذا فهذا هو الوضع الافتراضي في CI لديك.
لسلوك CI ثابت وقابل لإعادة الإنتاج، اضبط الوضع صراحةً:

```bash
# only allow-listed tools run; everything else is denied without asking
claude -p "Fix the lint errors" --permission-mode dontAsk --allowedTools "Read,Edit,Bash(npm run lint:*)"
```

راجع [إتاحة الميزات](/docs/reference/feature-availability) لمعرفة كيف يتصرف الوضع auto عبر QCode.

### تخطي مطالبات الأذونات

```bash
# Only in a safe, isolated environment!
claude -p "Fix every lint error and commit" --dangerously-skip-permissions
```

> **تحذير أمني**: يتخطى `--dangerously-skip-permissions` كل تأكيدات الأذونات. **استخدمه فقط داخل حاوية Docker أو بيئة CI معزولة.**

---
## 2. مرجع الخيارات الكامل

### التحكم في التنفيذ

| الخيار | ما يفعله | مثال |
|------|------|------|
| `-p "prompt"` | وضع بلا واجهة، تشغيل مهمة واحدة | `claude -p "analyse the architecture"` |
| `--bare` | الوضع الأدنى، يتجاوز الخطافات وبروتوكول خادم اللغة والإضافات | `claude --bare -p "..."` |
| `--max-turns N` | تحديد الحد الأقصى لعدد دورات التفاعل | `--max-turns 5` |
| `--model MODEL` | اختيار النموذج | `--model claude-opus-5` |
| `--permission-mode MODE` | تعيين وضع الأذونات (`default` / `acceptEdits` / `plan` / `auto` / `dontAsk` / `bypassPermissions`) | `--permission-mode dontAsk` |
| `--dangerously-skip-permissions` | تجاوز كل تأكيدات الأذونات | في البيئات المعزولة فقط |

### صيغ الإخراج

| الخيار | ما يفعله | متى يُستخدم |
|------|------|---------|
| `--output-format text` | نص عادي (افتراضي) | للبشر |
| `--output-format json` | JSON منظّم | للسكربتات |
| `--output-format stream-json` | JSON متدفق | المعالجة الفورية |

### قيود الأدوات

| الخيار | ما يفعله |
|------|------|
| `--allowedTools Tool1,Tool2` | موافقة مسبقة: تعمل الأدوات المدرجة من دون سؤال (لا تُقيَّد الأدوات الأخرى) |
| `--permission-mode dontAsk` | رفض كل ما لم تتم الموافقة عليه مسبقًا، من دون سؤال؛ وعند اقترانه بـ `--allowedTools` يعمل كقائمة سماح |
| `--tools Tool1,Tool2` | لا يتيح لـ Claude سوى الأدوات المدمجة المدرجة (قيد فعلي) |
| `--disallowedTools Tool1` | إزالة الأدوات المدرجة من الأدوات المتاحة |

**أسماء الأدوات المتاحة**: `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 — مراجعة الشيفرة بالذكاء الاصطناعي

```yaml
name: AI Code Review
on: [pull_request]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0  # full history, needed for the 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: |
          # Collect the files changed in this PR
          FILES=$(git diff --name-only origin/${{ github.base_ref }}...HEAD)

          claude -p "Review the code changes in the following files, focusing on:
          1. Security vulnerabilities (SQL injection, XSS, leaked secrets)
          2. Performance problems (N+1 queries, memory leaks)
          3. Logic errors
          4. Code style issues

          Changed files:
          $FILES" \
            --output-format json \
            --max-turns 3 \
            --model claude-sonnet-5 \
            --permission-mode dontAsk \
            --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 "Look at the .ts files under src/ and write unit tests for the ones that have none.
          Use Vitest + Testing Library.
          Name test files xxx.test.ts and put them next to the source file.
          Target 80%+ coverage." \
            --max-turns 10 \
            --permission-mode dontAsk \
            --allowedTools Read,Write,Glob,Grep,Bash

      - 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 "Analyse code quality and output JSON:
          {
            \"score\": 0-100,
            \"issues\": [{\"severity\": \"high|medium|low\", \"file\": \"...\", \"description\": \"...\"}],
            \"summary\": \"one-line summary\"
          }

          Scoring:
          - Type safety (20 points)
          - Error handling (20 points)
          - Test coverage (20 points)
          - Readability (20 points)
          - Security (20 points)" \
            --output-format json \
            --max-turns 3 \
            --model claude-sonnet-5 \
            --permission-mode dontAsk \
            --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: توليد سجل التغييرات

```bash
#!/bin/bash
# generate-changelog.sh — build a changelog from git commits

export ANTHROPIC_BASE_URL="https://api.qcode.cc/api"
export ANTHROPIC_AUTH_TOKEN="cr_your_api_key"

# Commits since the last tag
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 "Produce a structured changelog from these git commits:

$COMMITS

Format:
## [version] - $(date +%Y-%m-%d)
### Added
### Fixed
### Changed
### Breaking changes (if any)

Write in English, concise and professional." \
  --output-format text \
  --max-turns 2 \
  --model claude-sonnet-5 \
  --permission-mode dontAsk \
  --allowedTools Read,Glob,Grep
```

### الوصفة 5: إبقاء الوثائق محدثة

```bash
#!/bin/bash
# update-docs.sh — refresh the API docs after code changes

export ANTHROPIC_BASE_URL="https://api.qcode.cc/api"
export ANTHROPIC_AUTH_TOKEN="cr_your_api_key"

claude -p "Look at the route files under src/api/ and compare them with the documentation in docs/api.md.
Find API descriptions that are missing or out of date and update docs/api.md.
Keep the existing document format and style." \
  --max-turns 8 \
  --permission-mode dontAsk \
  --allowedTools Read,Write,Edit,Glob,Grep
```

---
## 4. العزل باستخدام Docker

عند استخدام `--dangerously-skip-permissions` في CI/CD، نوصي بشدة بالتشغيل داخل حاوية Docker:

```dockerfile
FROM node:22-slim

# Install Claude Code
RUN npm install -g @anthropic-ai/claude-code

# Install project dependencies
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .

# QCode.cc environment
ENV ANTHROPIC_BASE_URL=https://api.qcode.cc/api
# ANTHROPIC_AUTH_TOKEN is injected at runtime

# Run as a non-root user
RUN useradd -m claude
USER claude

CMD ["claude", "-p", "Run a code review", "--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
# Step 1: analyse
claude -p "Analyse the project architecture" \
  --session-id "pipeline-42" \
  --output-format json \
  --max-turns 3 \
  --permission-mode dontAsk \
  --allowedTools Read,Glob,Grep

# Step 2: build a plan from that analysis
claude -p "Based on the previous analysis, draft a refactoring plan" \
  --resume --session-id "pipeline-42" \
  --max-turns 3

# Step 3: execute the plan
claude -p "Carry out the first step of the refactoring plan" \
  --resume --session-id "pipeline-42" \
  --max-turns 10 \
  --permission-mode dontAsk \
  --allowedTools Read,Write,Edit,Bash,Glob,Grep
```

---

## 6. التحكم في التكلفة

### الاستراتيجية 1: تحديد عدد الدورات

```bash
# Three turns is enough for a simple task
claude -p "Quick analysis" --max-turns 3

# Ten at most for a complex one
claude -p "Full refactor" --max-turns 10
```

### الاستراتيجية 2: اختيار النموذج المناسب

| السيناريو | الموصى به | السبب |
|------|---------|------|
| مراجعة الكود | Sonnet | جيد بما يكفي وغير مكلف |
| فحص الأمان | Opus | يتطلب تحليلًا معمقًا |
| التنسيق بالجملة | Haiku | الأقل تكلفة |
| توليد الاختبارات | Sonnet | أفضل قيمة |

```bash
claude -p "Format the code" --model claude-haiku-5-5 --max-turns 3
```

### الاستراتيجية 3: تقييد الأدوات لتقليل استخدام token

```bash
# Read-only analysis → no repeated write/test cycles to pay for
claude -p "Analyse the code" --permission-mode dontAsk --allowedTools Read,Glob,Grep --max-turns 3
```

---

## 7. المقارنة مع Codex Headless

| | Claude Code -p | Codex headless |
|------|---------------|----------------|
| الخيار | `-p "prompt"` | `codex -q "prompt"` |
| بيئة العزل | يتطلب العزل باستخدام Docker | بيئة عزل مدمجة على مستوى النواة |
| صيغ الإخراج | text/json/stream-json | text/json |
| استئناف الجلسة | `--resume --session-id` | غير مدعوم |
| تقييد الأدوات | `--tools` / `--permission-mode dontAsk` + `--allowedTools` | `--approval-mode` |
| التنفيذ المتوازي | غير مدعوم | `codex cloud exec` |

**استخدمهما معًا**: Claude Code للتحليل والتخطيط (للقراءة فقط)، وCodex للتنفيذ (تلقائي بالكامل).

> خطة QCode.cc تتشارك حصتها، لذا فإن التبديل بين الأداتين في CI لا يترتب عليه أي تكلفة.

---

## 8. قائمة التحقق بأفضل الممارسات

1. **حدّد عدد الدورات دائمًا**: استخدم `--max-turns` في CI لمنع التنفيذ الجامح
2. **قيّد الأدوات**: اسمح فقط بما تحتاجه المهمة عبر `--permission-mode dontAsk` + `--allowedTools` (أو حدّد الأدوات المتاحة بـ `--tools`)
3. **اعزل باستخدام Docker**: يجب تشغيل `--dangerously-skip-permissions` داخل حاوية
4. **إخراج JSON**: فضّل `--output-format json` في الأتمتة ليكون تحليل النتائج سهلًا
5. **تحكّم في التكلفة**: Sonnet للتحليل وHaiku للمهام البسيطة
6. **عدم التأثر بالتكرار**: تأكد من أن التشغيل المتكرر لا يترك آثارًا جانبية
7. **المهلات**: اضبط مهلة للمهمة في خط المعالجة (10 دقائق مثلًا)
8. **إدارة الأسرار**: احتفظ بمفتاح API في أسرار CI، ولا تضمّنه في الكود أبدًا

---

## الخطوات التالية

- [نظام Hooks](/docs/advanced/hooks) — تشغيل الإجراءات تلقائيًا
- [نصائح CLI](/docs/usage/cli-tips) — مزيد من استخدام سطر الأوامر
- [تحسين التكلفة](/docs/usage/cost-optimization) — تقنيات للتحكم في الإنفاق
- [دليل Claude Code الكامل](/docs/getting-started/claude-code-tutorial) — من الصفر إلى الإتقان