نخستین گردش‌کار عامل برنامه‌نویسی: توضیح، اصلاح، آزمون و بازبینی

اتصال موفق API فقط نقطه شروع است. این تمرین کوچک نشان می‌دهد توسعه‌دهنده، دانشجو یا تیم استارتاپ چگونه کاری دقیق به عامل بدهد، برنامه آن را بررسی کند و نتیجه را مستقل بیازماید.

پس از تأیید چت ساده، از Hermes، OpenCode یا Aider استفاده کنید. 9Router درگاه است، نه عامل برنامه‌نویسی؛ در صورت نیاز میان ابزار شما و AvalAI قرار می‌گیرد.

۱. دو فایل آزمایشی بسازید

از پوشه‌ای تازه و خالی بیرون مخزن واقعی خود استفاده کنید. به Python نسخه ۳٫۱۰ یا جدیدتر نیاز دارید، اما هیچ بسته جانبی لازم نیست. داده مشتری یا فایل متغیرهای محیطی را ضمیمه نکنید.

پیاده‌سازی عمداً ناقص زیر را ذخیره کنید:

def total_cents(prices):
    return sum(prices)

آزمون‌های پذیرش مستقل را ذخیره کنید:

import unittest
from totals import total_cents


class TotalsTests(unittest.TestCase):
    def test_empty(self):
        self.assertEqual(total_cents([]), 0)

    def test_integer_cents(self):
        self.assertEqual(total_cents([125, 250]), 375)

    def test_negative_rejected(self):
        with self.assertRaises(ValueError):
            total_cents([125, -1])

    def test_fraction_rejected(self):
        with self.assertRaises(ValueError):
            total_cents([1.5])

    def test_boolean_rejected(self):
        with self.assertRaises(ValueError):
            total_cents([True])


if __name__ == "__main__":
    unittest.main()

این تابع آموزشی مقادیر صحیح سِنت را جمع می‌کند؛ سامانه حسابداری عملیاتی نیست. رفتار ناقص آن اعتبارسنجی ورودی است.

۲. وضعیت اولیه را خودتان بررسی کنید

python3 -m unittest -v test_totals.py

نتیجه مورد انتظار در ابتدا: پنج آزمون اجرا و سه آزمون رد می‌شوند، چون مقادیر منفی، کسری و بولی پذیرفته می‌شوند. آزمون فهرست خالی و جمع معمول موفق‌اند.

شکست اولیه شاهد مفیدی است. اجازه ندهید عامل صرفاً برای قبولی نتیجه، آزمون‌ها را ضعیف کند.

۳. برنامه‌ای فقط‌خواندنی بخواهید

عامل پیکربندی‌شده را در همین پوشه آزمایشی باز کنید و درخواست زیر را بدهید:

Read only totals.py and test_totals.py.
Explain why the tests fail. Propose the smallest fix, but do not edit yet.
The contract is: integer cents only, no negative values, no booleans,
empty input returns 0, invalid input raises ValueError.
Do not install packages, read secrets, access the network, or change tests.

فقط خواندن همین دو فایل را تأیید کنید. بررسی کنید پیشنهاد عامل رابطه bool با عدد صحیح در Python را در نظر می‌گیرد و جمع مقادیر صحیح معتبر را حفظ می‌کند.

در Aider با تنظیم --chat-mode ask راهنما شروع کنید و به‌جای README.md این دو فایل را اضافه کنید. در OpenCode درخواست تأیید را نگه دارید. در Hermes مجوزهای فعال ابزار را بررسی کنید. کنترل ابزارها متفاوت است؛ دستور متنی به‌تنهایی محیط ایزوله نیست.

۴. یک ویرایش محدود را تأیید کنید

وقتی برنامه با قرارداد مورد انتظار سازگار بود، ویرایش را صریحاً مجاز کنید:

Approved: edit only totals.py to satisfy that contract.
Do not change test_totals.py or other files.
Stop after the patch and report what changed.
Do not commit, push, deploy, or claim tests ran unless you actually ran them.

در Aider برای همین مرحله تأییدشده با /chat-mode code وارد حالت کدنویسی شوید و ثبت خودکار تغییرات در Git را خاموش نگه دارید. در عامل‌های دیگر فقط ویرایش فایل مرتبط را تأیید کنید. برای یک اصلاح کوچک، دسترسی گسترده پوسته یا شبکه ندهید.

۵. مستقل راستی‌آزمایی کنید

همان فرمان را خودتان اجرا کنید:

python3 -m unittest -v test_totals.py

نتیجه مورد انتظار پس از اصلاح درست: هر پنج آزمون موفق‌اند. هر دو فایل را ببینید و مطمئن شوید آزمون‌ها تغییر نکرده‌اند. اگر بعداً در مخزن Git کار کردید، git diff و git status --short را نیز بررسی کنید.

نمونه گزارش بازبینی مفید:

Scope: totals.py only
Behavior: accepts nonnegative integer cents; rejects negatives, fractions, booleans
Evidence: python3 -m unittest -v test_totals.py
Result: 5 tests passed
Unchanged: test_totals.py
Not done: commit, push, deploy

این گزارش را به‌عنوان شاهد کپی نکنید؛ آن را از فرمان‌ها و تفاوت فایل‌هایی که واقعاً بررسی کرده‌اید پر کنید. اگر آزمونی هنوز رد می‌شود، فقط خطای لازم را بفرستید و برنامه اصلاح‌شده بخواهید. همه متغیرهای محیطی یا فایل‌های خصوصی نامرتبط را نفرستید.

۶. الگو را در کار واقعی به کار ببرید

مخاطب	نخستین کار کوچک	شاهد پذیرش
توسعه‌دهنده	رفع یک خطای اعتبارسنجی	آزمون بازتولید، تفاوت محدود، مجموعه آزمون مرتبط
استارتاپ	افزودن یک قاعده ورود CSV	ردیف‌های ساختگی معتبر و نامعتبر، بدون داده مشتری
دانشجو	توضیح تابع و سپس تلاش برای اصلاح شخصی	توضیح و آزمون‌های خودتان با رعایت قواعد درس
تیم شرکت	بازبینی یک بخش بدون ویرایش	شواهد فایل و خط، محدودیت‌ها، تصمیم انسانی

پیش از شروع، دامنه، آزمون‌ها، شرط توقف و مجوزها را تعیین کنید. برای هر کار سقف تعداد درخواست و زمان بگذارید؛ مصرف AvalAI را ببینید، چون حلقه عامل و تلاش دوباره هزینه اضافه دارند. فرض نکنید گزینه بودجه دلاری یک SDK در همه ابزارهای متصل به AvalAI کار می‌کند.

برای کار طولانی‌تر، یادداشتی کوتاه از فایل‌های جاری، تصمیم‌ها، شواهد و پرسش‌های باقی‌مانده نگه دارید. وقتی زمینه شلوغ شد نشستی تازه شروع کنید. ادامه نشست قبلی راستی‌آزمایی مستقل نیست؛ بررسی‌ها را روی فایل‌های جاری تکرار کنید.

منابع و محدودیت‌ها

در ۱۴۰۵-۰۶-۱۷ / (2026-09-08) بررسی شده است. این تمرین از OpenAI Cookbook رسمی و مخزن openai/openai-cookbook، به‌ویژه بهبود گردش‌کار توسعه، و بازبین مخزن در Claude Cookbooks اقتباس شده است.

این بازنویسی خواندن محدود، تأیید صریح و شواهد را حفظ می‌کند. Claude Agent SDK نصب نمی‌کند، بازبین زمان‌بندی‌شده اجرا نمی‌کند و قابلیت‌های عامل میزبانی‌شده را APIهای AvalAI نمی‌نامد. رفتار Python مثال را می‌توان آفلاین آزمود؛ برای این انتشار نشست زنده عامل یا درخواست پولی اجرا نشده است.