خلاصه سریع آموزش Claude Code: برای برنامه نویسی با یک ایجنت هوش مصنوعی در ترمینال، کلید API Anthropic را تنظیم کنید و یک اسکریپت پایتون بسازید که به مدل Claude دسترسی دارد و از طریق ابزارهای «خواندن/نوشتن فایل» و «اجرای دستورات» روی پوشه پروژه شما کار می‌کند. در ادامه یک ایجنت ترمینالی سبک می‌سازیم که تغییرات را قابل بررسی نگه می‌دارد، تست‌ها را اجرا می‌کند و قدم‌به‌قدم کد شما را اصلاح می‌کند.

پیش نیازها و نصب سریع

برای اجرای ایجنت ترمینالی این موارد را آماده کنید:

  • Python 3.10 یا جدیدتر
  • pip و Git نصب‌شده
  • یک کلید API از Anthropic و قرار دادن آن در متغیر محیطی ANTHROPIC_API_KEY
  1. یک پوشه کاری انتخاب کنید (ریپو فعلی یا یک فولدر آزمایشی).
  2. پکیج‌های لازم را نصب کنید:
    pip install anthropic rich python-dotenv
  3. کلید را به صورت محیطی ست کنید:
    # Linux/macOS
    export ANTHROPIC_API_KEY="sk-ant-..."
    
    # Windows (PowerShell)
    setx ANTHROPIC_API_KEY "sk-ant-..."

نکته: اگر به ابزار ترمینالی رسمی Anthropic دسترسی دارید، مراحل نصب را از مستندات رسمی دنبال کنید. در این راهنما یک ایجنت سفارشی می‌سازیم تا کنترل کامل و شفافیت بیشتری روی دستورات و تغییر فایل‌ها داشته باشید.

ساخت یک ایجنت ترمینالی با Claude Code

کد زیر یک ایجنت ساده می‌سازد که:

  • فقط داخل پوشه مشخص‌شده کار می‌کند (Sandbox نسبی).
  • می‌تواند فایل‌ها را بخواند/بنویسد و دستورات محدودی را اجرا کند.
  • خروجی دستورات و تغییرات را بازگردانی می‌کند تا بتوانید بررسی کنید.

فایل را با نام claude_code_agent.py ذخیره کنید و مسیر پروژه را به آن بدهید.

import os
import sys
import json
import shlex
import argparse
import subprocess
from pathlib import Path
from typing import Dict, Any, List

from anthropic import Anthropic

# ---------- تنظیمات ----------
DEFAULT_MODEL = "claude-3-5-sonnet-latest"  # در صورت نیاز نام مدل را تغییر دهید
MAX_COMMAND_OUTPUT = 8000  # محدودسازی خروجی‌ها برای جلوگیری از تورم کانتکست

# ---------- ابزارهای فایل و شل ----------
def resolve_safe_path(base: Path, rel: str) -> Path:
    p = (base / rel).resolve()
    if not str(p).startswith(str(base.resolve())):
        raise ValueError("مسیر خارج از پوشه کاری است.")
    return p

def read_file(base: Path, path: str) -> str:
    p = resolve_safe_path(base, path)
    if not p.exists() or not p.is_file():
        return f"فایل یافت نشد: {path}"
    try:
        return p.read_text(encoding="utf-8")
    except UnicodeDecodeError:
        return "این فایل متنی نیست یا با utf-8 قابل خواندن نیست."

def write_file(base: Path, path: str, content: str) -> str:
    p = resolve_safe_path(base, path)
    p.parent.mkdir(parents=True, exist_ok=True)
    p.write_text(content, encoding="utf-8")
    return f"نوشتن انجام شد: {path} (طول محتوا: {len(content)})"

def list_dir(base: Path, path: str = ".") -> str:
    p = resolve_safe_path(base, path)
    if not p.exists():
        return f"مسیر یافت نشد: {path}"
    items = []
    for item in sorted(p.iterdir()):
        kind = "DIR" if item.is_dir() else "FILE"
        items.append(f"{kind}\t{item.name}")
    return "\n".join(items)

DANGEROUS_TOKENS = {"rm -rf", "sudo", ":>", ">>", "mkfs", "shutdown", "reboot", ":(){ :|:& };:"}
ALLOWED_BINARIES = {"ls", "cat", "python", "pytest", "pip", "npm", "pnpm", "node", "go", "cargo", "git", "bash", "sh"}

def is_safe_command(cmd: str) -> bool:
    lower = cmd.strip().lower()
    for token in DANGEROUS_TOKENS:
        if token in lower:
            return False
    # بررسی باینری اول
    try:
        parts = shlex.split(cmd)
        if not parts:
            return False
        binary = Path(parts[0]).name
        if binary not in ALLOWED_BINARIES:
            return False
    except Exception:
        return False
    return True

def run_command(base: Path, command: str, timeout: int = 120) -> str:
    if not is_safe_command(command):
        return f"اجرا لغو شد: دستور ناامن یا مجاز نیست: {command}"

    try:
        proc = subprocess.run(
            command,
            cwd=str(base),
            shell=True,
            capture_output=True,
            text=True,
            timeout=timeout,
            encoding="utf-8"
        )
        out = (proc.stdout or "") + (proc.stderr or "")
        if len(out) > MAX_COMMAND_OUTPUT:
            out = out[:MAX_COMMAND_OUTPUT] + "\n... [خروجی طولانی‌تر کوتاه شد] ..."
        return f"کد خروج: {proc.returncode}\n--- خروجی ---\n{out}"
    except subprocess.TimeoutExpired:
        return f"زمان اجرای دستور گذشت (timeout): {command}"
    except Exception as e:
        return f"خطای اجرای دستور: {e}"

# ---------- تعریف ابزارها برای مدل ----------
def tool_schemas() -> List[Dict[str, Any]]:
    return [
        {
            "name": "read_file",
            "description": "خواندن محتوای فایل متنی از پوشه کاری.",
            "input_schema": {
                "type": "object",
                "properties": {
                    "path": {"type": "string", "description": "مسیر نسبی فایل"}
                },
                "required": ["path"]
            }
        },
        {
            "name": "write_file",
            "description": "نوشتن یا بازنویسی یک فایل متنی در پوشه کاری.",
            "input_schema": {
                "type": "object",
                "properties": {
                    "path": {"type": "string", "description": "مسیر نسبی فایل"},
                    "content": {"type": "string", "description": "متن کامل فایل"}
                },
                "required": ["path", "content"]
            }
        },
        {
            "name": "list_dir",
            "description": "فهرست‌گیری از یک مسیر داخل پوشه کاری.",
            "input_schema": {
                "type": "object",
                "properties": {
                    "path": {"type": "string", "description": "مسیر نسبی پوشه"}
                },
                "required": []
            }
        },
        {
            "name": "run_command",
            "description": "اجرای یک دستور شل امن در پوشه کاری (لیست سفید). برای نصب پکیج، اجرای تست یا اسکریپت‌ها.",
            "input_schema": {
                "type": "object",
                "properties": {
                    "command": {"type": "string", "description": "متن کامل دستور"}
                },
                "required": ["command"]
            }
        }
    ]

def dispatch_tool(base: Path, name: str, tool_input: Dict[str, Any]) -> str:
    try:
        if name == "read_file":
            return read_file(base, tool_input.get("path", ""))
        if name == "write_file":
            return write_file(base, tool_input.get("path", ""), tool_input.get("content", ""))
        if name == "list_dir":
            return list_dir(base, tool_input.get("path", "."))
        if name == "run_command":
            return run_command(base, tool_input.get("command", ""))
        return f"ابزار ناشناخته: {name}"
    except Exception as e:
        return f"خطای ابزار {name}: {e}"

# ---------- حلقه گفتگو ----------
SYSTEM_PROMPT_TEMPLATE = (
    "You are Claude Code, a careful coding agent working ONLY inside this workspace: {ws}. "
    "Use the provided tools to: inspect files, propose minimal diffs, write complete files (not patches), "
    "run tests/linters, and explain what you changed. Never execute dangerous commands. "
    "Prefer deterministic, small steps and keep outputs concise."
)

def main():
    parser = argparse.ArgumentParser(description="Claude Code – ترمینال ایجنت کدنویسی")
    parser.add_argument("--dir", default=".", help="پوشه کاری پروژه")
    parser.add_argument("--model", default=DEFAULT_MODEL, help="نام مدل Claude")
    args = parser.parse_args()

    api_key = os.getenv("ANTHROPIC_API_KEY")
    if not api_key:
        print("خطا: متغیر ANTHROPIC_API_KEY تنظیم نشده است.")
        sys.exit(1)

    base = Path(args.dir).resolve()
    if not base.exists():
        print(f"خطا: پوشه کاری وجود ندارد: {base}")
        sys.exit(1)

    client = Anthropic(api_key=api_key)
    tools = tool_schemas()
    system_prompt = SYSTEM_PROMPT_TEMPLATE.format(ws=str(base))

    print(f"✅ ایجنت آماده است. پوشه کاری: {base}")
    print("برای خروج :q را وارد کنید.")

    chat: List[Dict[str, Any]] = []

    while True:
        user_input = input("\nسوال/دستور شما: ").strip()
        if not user_input:
            continue
        if user_input in {":q", ":quit", ":exit"}:
            print("خروج...")
            break

        # افزودن پیام کاربر
        chat.append({"role": "user", "content": user_input})

        # حلقه ابزار تا زمان اتمام استفاده از ابزار
        while True:
            resp = client.messages.create(
                model=args.model,
                system=system_prompt,
                max_tokens=1200,
                temperature=0,
                tools=tools,
                messages=chat
            )

            # نمایش متن پاسخ
            assistant_texts = []
            tool_uses = []
            for block in resp.content:
                if block.type == "text":
                    assistant_texts.append(block.text)
                elif block.type == "tool_use":
                    tool_uses.append(block)

            if assistant_texts:
                print("\n--- پاسخ ایجنت ---")
                print("\n".join(assistant_texts))

            if not tool_uses:
                # پاسخ نهایی بدون ابزار
                chat.append({"role": "assistant", "content": resp.content})
                break

            # اجرای ابزارها و اضافه کردن نتایج
            chat.append({"role": "assistant", "content": resp.content})

            tool_results = []
            for tu in tool_uses:
                result = dispatch_tool(base, tu.name, tu.input)
                tool_results.append({
                    "type": "tool_result",
                    "tool_use_id": tu.id,
                    "content": result
                })

            chat.append({"role": "user", "content": tool_results})

if __name__ == "__main__":
    main()

اجرا:

python claude_code_agent.py --dir . --model claude-3-5-sonnet-latest

در اولین اجرا، از دستورهای ساده شروع کنید: «ساختار پروژه را فهرست کن»، «برای فایل main.py یک تست pytest بنویس»، «با اجرای pytest خطاها را ببین و آن را برطرف کن».

مثال عملی: افزودن تست و رفع خطا

سناریو: یک تابع ساده در فایل app/math_utils.py دارید که احتمالا باگ دارد. از ایجنت بخواهید تست بنویسد و با اجرای تست، خطا را پیدا و حل کند.

  1. از ایجنت بپرسید:
    برای فایل app/math_utils.py یک تست pytest بنویس. سپس تست را اجرا کن و اگر شکست خورد کد را اصلاح کن.
  2. ایجنت باید مراحل زیر را انجام دهد:
    • list_dir برای کشف ساختار.
    • read_file برای دیدن محتوای math_utils.py.
    • write_file برای ساختن tests/test_math_utils.py.
    • run_command برای اجرای pytest.
    • در صورت شکست، بازنویسی فایل و تکرار اجرا.
  3. پس از پایان، از ایجنت بخواهید خلاصه تغییرات را توضیح دهد و دلیل هر اصلاح را بیان کند.

بررسی صحت: خودتان هم دستورات زیر را بزنید تا خروجی ایجنت را تایید کنید.

git diff -- . 
pytest -q

نحوه بررسی نتیجه و کنترل تغییرات

  • گام کوچک: مسئله را به وظایف کوچک تبدیل کنید (یک تست، یک باگ، یک فایل).
  • Git در کنار ایجنت: قبل از هر مرحله commit بگیرید تا diff هر تغییر واضح باشد:
    git add -A && git commit -m "checkpoint: قبل از اجرای ایجنت"
  • کنترل دستورات: متن هر دستور run_command چاپ می‌شود. اگر خروجی مشکوک بود، دوباره دستور را خودتان دستی اجرا کنید.
  • محدودسازی خروجی: برای جلوگیری از پرشدن کانتکست، خروجی طولانی کوتاه می‌شود. اگر لازم بود بخشی را مجدد بخوانید.

خطاها و محدودیت های رایج

  • کلید API تنظیم نشده: پیام «متغیر ANTHROPIC_API_KEY تنظیم نشده است» را می‌بینید؛ کلید را ست کنید و شل را دوباره باز کنید.
  • نام مدل یا دسترسی: اگر مدل در حساب شما فعال نباشد، خطای دسترسی می‌گیرید. از یک مدل در دسترس استفاده کنید.
  • تفاوت محیط: برخی دستورات در Windows و Linux متفاوت است. در صورت نیاز از bash/sh استفاده کنید و پروژه را قابل حمل نگه دارید.
  • خروجی طولانی/توکن: لاگ‌های بسیار طولانی بی‌اثر هستند. تست‌ها را گزینشی اجرا کنید و خروجی را کوتاه نگه دارید.
  • دستورات خطرناک: این نمونه یک لیست سفید ساده دارد و برخی دستورات را مسدود می‌کند. بسته به نیاز خودتان این لیست را سختگیرانه‌تر کنید.
  • توهم ابزار یا مسیر: اگر مدل مسیری را اشتباه حدس زد، از آن بخواهید ساختار را با list_dir دوباره بررسی کند.

نکات ایمنی و حریم خصوصی هنگام اجرای ایجنت

  • هرگز Secrets را داخل فایل‌های پروژه نگذارید یا به مدل ارسال نکنید. از فایل‌های محلی امن یا متغیرهای محیطی استفاده کنید.
  • ایجنت فقط باید داخل پوشه کاری کار کند. ارسال مسیرهای سراسری یا mount کردن دایرکتوری‌های حساس را مجاز نکنید.
  • قبل از اجرای دستورات نصب یا build در CI/CD، نتایج را محلی بازبینی کنید.
  • کد تولیدی را مانند کد یک همکار جدید بازبینی کنید: سبک، امنیت، کارایی و پوشش تست.

گام بعدی

اگر می‌خواهید ساخت ایجنت‌ها را در گردش‌کارهای واقعی توسعه نرم‌افزار ادامه دهید، راهنمای آموزش ساخت ایجنت هوش مصنوعی با n8n برای پاسخ گویی خودکار دید خوبی از اتوماسیون Agentic به شما می‌دهد. برای یک مسیر منسجم و پروژه‌محور در ابزارهای AI، دوره آموزش جامع ابزارهای هوش مصنوعی (Ai Master) گزینه مناسبی برای یادگیری عمیق‌تر است.

اگر با مفاهیم فنی هوش مصنوعی در سطح توسعه‌دهندگان نیاز به مرور دارید، مقاله AI Concepts for Developers؛ ۱۰ مفهوم مهم هوش مصنوعی می‌تواند پیش‌زمینه خوبی قبل از کار با ایجنت‌ها باشد.