> ## Content Index
> Fetch the complete content index at: https://arabroot.io/llms.txt
> Use this file to discover other available public pages before exploring further.

# فريق وكلاء Multi-agent يبني منصة: ماذا نجح وماذا فشل؟
- URL: https://arabroot.io/articles/فريق-وكلاء-multi-agent-يبني-منصة-ماذا-نجح-وماذا-فشل/
- Published: 2026-11-21T01:30:12.000Z
- Updated: 2026-11-21T02:29:06.000Z
- Description: تجربة كاملة: مخطط وثلاثة مبرمجين ومراجع بنماذج محلية يبنون خدمة لاختصار الروابط من مواصفة، ثم نحكم عليها باختبارات قبول مخفية ونقارن بعقد كتبه إنسان وبوكيل واحد.
- Author: فريق عرب رووت
- Tags: الأدلة التقنية, التطوير مع وكلاء الذكاء الاصطناعي

العروض التوضيحية Demos التي تنتشر عن فرق الوكلاء تبدأ عادة بجملة واحدة، مثل «ابن لي خدمة لاختصار الروابط»، ثم ترى مخططاً يقسم العمل، ومبرمجين يكتبون الملفات بالتوازي، ومراجعاً يرجع الأخطاء، وفي النهاية خدمة تعمل. وقد شرحنا في [مقال تعدد الوكلاء](https://arabroot.io/articles/%D8%AA%D8%B9%D8%AF%D8%AF-%D8%A7%D9%84%D9%88%D9%83%D9%84%D8%A7%D8%A1-multi-agent-%D8%A7%D9%84%D9%85%D8%AE%D8%B7%D8%B7-%D9%88%D8%A7%D9%84%D9%85%D9%86%D9%81%D8%B0-%D9%88%D8%A7%D9%84%D9%85%D8%B1%D8%A7%D8%AC%D8%B9/) الأدوار الثلاثة وأنماط التنسيق، ورأينا في مختبره أن المخطط يختصر المهمة فيسقط الشرط الذي يهم، وحسبنا في [مقال التكلفة](https://arabroot.io/articles/%D9%85%D8%AA%D9%89-%D9%8A%D8%B5%D8%A8%D8%AD-%D8%AA%D8%B9%D8%AF%D8%AF-%D8%A7%D9%84%D9%88%D9%83%D9%84%D8%A7%D8%A1-multi-agent-%D8%A7%D8%BA%D9%84%D9%89-%D9%88%D8%A7%D8%A8%D8%B7%D8%A7-%D9%85%D9%86-%D9%88%D9%83%D9%8A%D9%84-%D9%88%D8%A7%D8%AD%D8%AF/) متى يصبح الفريق أغلى وأبطأ من وكيل واحد. ولكن المهمة في ذلك المختبر كانت أربع دوال مستقلة لا تعرف إحداها الأخرى، أي أفضل حال ممكن لتعدد الوكلاء. أما المنصة الحقيقية، حتى أصغرها، فأجزاؤها تتكلم مع بعضها: طبقة HTTP تستدعي طبقة التخزين، وطبقة التخزين تستدعي دالة توليد الرموز، وأي اختلاف في اسم دالة أو نوع قيمة بين ملفين يجعل كل ملف صحيحاً وحده والمنصة كلها لا تعمل.

ولذلك أجرينا في هذا المقال تجربة واحدة كاملة ونقلنا ما حدث فيها كما حدث: فريق من الوكلاء بنموذجين محليين صغيرين يبني من الصفر خدمة لاختصار الروابط URL Shortener بثلاثة ملفات، من مواصفة كتبها إنسان، ثم نحكم على الخدمة باختبارات قبول Acceptance Tests لم يرها أحد من الفريق. ثم أعدنا التجربة بتغيير واحد، وهو أن يكتب إنسان العقد Contract بين الملفات بدل المخطط، لنرى أين يقع الخطأ فعلاً.

في هذا المقال سوف نتناول:

- المهمة: مواصفة خدمة صغيرة بثلاثة ملفات، واختبارات دخان Smoke Tests يراها الفريق، واختبارات قبول مخفية.
- الفريق: مخطط يكتب العقد، ومبرمج لكل ملف، ومختبر Tester دون نموذج، ومراجع يوزع الملاحظات.
- التشغيل الأول من البداية إلى النهاية: ما الذي كتبه كل وكيل، وأين توقفت المنصة عن العمل.
- التشغيل الثاني بعقد كتبه إنسان، وما الذي تغير.
- الوقت والتوكنات لكل دور، وما الذي يقوله ذلك عن تكلفة الفريق.
- ما الذي نجح، وما الذي فشل، وكيف تستفيد من الفكرة في عمل حقيقي.

## المهمة: خدمة لاختصار الروابط في ثلاثة ملفات

اخترنا خدمة اختصار الروابط لأنها صغيرة بما يكفي لنموذج على معالج عادي CPU، ولكن فيها ما يجعل المنصات الحقيقية صعبة: ثلاث طبقات تعتمد على بعضها، وقرارات صغيرة يجب أن يتفق عليها الجميع، مثل هل الرمز Code نص أم رقم، وهل الرابط نفسه إذا أرسل مرتين يأخذ الرمز نفسه، وماذا ترجع الطبقة عندما لا تجد الرمز. وهذه هي المواصفة كاملة كما كتبناها، وهي كل ما يعرفه الفريق عن المطلوب:

```markdown
# Link shortener service (Python 3.13, standard library only)

A small internal service that turns long URLs into short codes. Package name: `shortener`.

## Behaviour
1. `POST /links` with a JSON body `{"url": "https://..."}` creates a short link.
   - The URL must start with `http://` or `https://` and be at most 2000 characters, otherwise reply `400` with `{"error": "invalid url"}`.
   - A body that is not valid JSON, or has no `url`, also gets `400` with `{"error": "invalid url"}`.
   - On success reply `201` with `{"code": "<code>", "short_url": "http://sho.rt/<code>"}`.
   - The same URL posted twice gets the same code (no duplicate rows).
2. `GET /<code>` replies `302` with the header `Location: <the long url>` and adds 1 to the hit counter of that link.
   Unknown code: `404` with `{"error": "not found"}`.
3. `GET /links/<code>/stats` replies `200` with `{"code": ..., "url": ..., "hits": <int>}`. Unknown code: `404`.
4. Codes are base62 (`0-9a-zA-Z`) encodings of the row id, so the first link gets code `"1"`, the 62nd gets `"10"`.
5. All JSON replies use the header `Content-Type: application/json`.

## Structure (three files)
- `shortener/codes.py`: `encode(n: int) -> str` (base62, n >= 1, raises ValueError for n < 1).
- `shortener/store.py`: class `LinkStore(path)` on SQLite (`":memory:"` allowed) with
  `add(url) -> str` (returns the code, reuses the code of an existing url), `get(code) -> str | None`,
  `hit(code) -> None`, `stats(code) -> dict | None` (`{"code", "url", "hits"}`).
- `shortener/app.py`: `make_app(store) -> WSGI application` implementing the HTTP behaviour above.
```

والشكل التالي يبين الطبقات الثلاث وما يمر بينها:

![ثلاثة صناديق: app.py يستقبل طلبات HTTP مثل POST /links وGET /code، ويستدعي store.py بالدوال add وget وhit وstats، وstore.py يحفظ في SQLite ويستدعي codes.py بالدالة encode لتحويل رقم الصف إلى رمز base62. وفوق كل سهم بين صندوقين علامة استفهام: ما اسم الدالة، وما نوع القيمة](https://arabroot.io/content/images/2026/11/agent-team-builds-platform-01-platform.webp)

كل ملف يكتبه وكيل مختلف، وكل سهم بين ملفين قرار يجب أن يتفقا عليه.

ولكي نحكم على النتيجة بعدل، كتبنا بأنفسنا حلاً مرجعياً من ثلاثة ملفات، و11 اختبار قبول مخفياً من المواصفة نفسها، واختبارين للدخان يراهما الفريق ويشغلهما، وتأكدنا أن الحل المرجعي ينجح في الاختبارات الثلاثة عشر كلها:

```text
Ran 13 tests in 0.005s

OK
```

واختبارا الدخان يفحصان شيئين فقط: أن `encode(1)` يرجع `"1"`، وأن إنشاء رابط ثم طلبه يرجع تحويلاً Redirect بالرمز 302 إلى الرابط الأصلي. أي أنهما يقولان للفريق هل تعمل المنصة أصلاً، ولا يقولان هل تعمل كما تطلب المواصفة، وهذا هو الوضع الطبيعي في أي مشروع جديد.

وقد يتساءل البعض: لماذا لا نعطي الفريق اختبارات القبول كلها ما دامت موجودة؟ والإجابة أن الفريق عندها يكتب الكود ليرضي الاختبارات لا ليحقق المواصفة، كما رأينا في مقال TDD مع الوكلاء عندما عدل الوكيل الاختبار نفسه، وأن الاختبارات المخفية هي الطريقة الوحيدة لنعرف هل فهم الفريق المواصفة أم حفظ الأمثلة. وفي مشروع حقيقي يقابل ذلك أن يكتب صاحب المنتج معايير القبول، وأن تبقى عند المراجع البشري لا عند الوكلاء.

## الفريق: أربعة أدوار، واحد منها دون نموذج

السكربت `team.py` يدير الفريق كله، وكل استدعاء للنموذج يسجل في الملف `calls.jsonl` بدوره وعدد التوكنات والزمن. والأدوار كما يلي:

- **المخطط Planner:** qwen3:4b-instruct، يقرأ المواصفة ويكتب العقد بصيغة JSON مقيدة بمخطط: لكل ملف وظيفته، وواجهته العامة Interface بالتواقيع Signatures، وما يستعمله من الملفات الأخرى، ثم قواعد مشتركة على الجميع.
- **المبرمجون Coders:** qwen2.5-coder:3b، واحد لكل ملف، يرى المواصفة كاملة والعقد كاملاً، ويكتب ملفه فقط. واخترنا أن يرى كل مبرمج المواصفة كاملة، لا ما لخصه المخطط فقط، لأن مختبر مقال تعدد الوكلاء بين أن الملخص يسقط الشروط.
- **المختبر Tester:** ليس نموذجاً، وإنما كود يشغل اختبارات الدخان ويجمع المخرج.
- **المراجع Reviewer:** qwen3:4b-instruct، يقرأ العقد ومخرج الاختبارات والملفات الثلاثة، ويقرر أي ملف يجب أن يتغير، ويكتب ملاحظة قصيرة لصاحب كل ملف، ثم يعيد كل مبرمج كتابة ملفه بالملاحظة، حتى ثلاث جولات.

والمبرمجون يعملون واحداً بعد الآخر وليس بالتوازي، والسبب أن Ollama على المعالج يخدم طلباً واحداً في كل مرة، فالتوازي هنا لا يوفر وقتاً، وإنما يخلط ذاكرة التخزين المؤقت للمحادثات. وهذا هو السكربت كاملاً:

```python
# A team of agents builds the link shortener from SPEC.md:
#   planner  (qwen3:4b-instruct)  reads the spec and writes the contract: files, functions, shared rules
#   coders   (qwen2.5-coder:3b)   one per file, each writes its file from the spec and the contract
#   tester   (no model)           imports the package and runs the smoke tests
#   reviewer (qwen3:4b-instruct)  reads the failures and sends one note to the owner of each file to fix
# Every model call is logged with its role, tokens and seconds in calls.jsonl.
#   python team.py <out-dir> [--contract human|planner] [--rounds 3]
import argparse, json, os, re, shutil, subprocess, sys, time, urllib.request
from pathlib import Path

OLLAMA = os.environ.get("OLLAMA", "http://adb-ollama:11434")
LAB = Path(__file__).parent
SPEC = (LAB / "spec" / "SPEC.md").read_text()
PLANNER = REVIEWER = "qwen3:4b-instruct"
CODER = "qwen2.5-coder:3b"

CONTRACT_SCHEMA = {"type": "object", "properties": {
    "files": {"type": "array", "items": {"type": "object", "properties": {
        "path": {"type": "string"}, "purpose": {"type": "string"},
        "interface": {"type": "array", "items": {"type": "string"}},
        "uses": {"type": "array", "items": {"type": "string"}}},
        "required": ["path", "purpose", "interface", "uses"]}},
    "shared_rules": {"type": "array", "items": {"type": "string"}}}, "required": ["files", "shared_rules"]}
REVIEW_SCHEMA = {"type": "object", "properties": {"fixes": {"type": "array", "items": {"type": "object", "properties": {
    "path": {"type": "string"}, "note": {"type": "string"}}, "required": ["path", "note"]}}}, "required": ["fixes"]}

# The contract a person would write from the "Structure" section of the spec (--contract human).
HUMAN_CONTRACT = {"files": [
    {"path": "shortener/codes.py", "purpose": "base62 codes", "uses": [],
     "interface": ["ALPHABET = '0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ'",
                   "def encode(n: int) -> str  # n >= 1, else ValueError; encode(1) == '1', encode(62) == '10'"]},
    {"path": "shortener/store.py", "purpose": "SQLite storage of links", "uses": ["shortener.codes.encode"],
     "interface": ["class LinkStore:", "def __init__(self, path: str)  # sqlite3.connect(path), creates the table",
                   "def add(self, url: str) -> str  # insert, code = encode(row id); same url returns the existing code",
                   "def get(self, code: str) -> str | None", "def hit(self, code: str) -> None  # hits + 1",
                   "def stats(self, code: str) -> dict | None  # {'code': ..., 'url': ..., 'hits': int}"]},
    {"path": "shortener/app.py", "purpose": "WSGI HTTP API", "uses": ["LinkStore methods add/get/hit/stats"],
     "interface": ["def make_app(store) -> callable  # returns app(environ, start_response)",
                   "POST /links -> 201 {code, short_url} | 400 {error: 'invalid url'}",
                   "GET /<code> -> 302 Location | 404 {error: 'not found'}",
                   "GET /links/<code>/stats -> 200 stats | 404"]}],
    "shared_rules": ["standard library only", "every JSON reply has Content-Type: application/json",
                     "codes are strings, the first link is '1'", "read the body with int(environ['CONTENT_LENGTH'])"]}

log = None

def chat(role, model, messages, fmt=None, num_predict=1500):
    body = {"model": model, "messages": messages, "stream": False, "keep_alive": "30m",
            "options": {"temperature": 0, "seed": 7, "num_ctx": 8192, "num_predict": num_predict}}
    if fmt:
        body["format"] = fmt
    t0 = time.time()
    req = urllib.request.Request(OLLAMA + "/api/chat", json.dumps(body).encode(), {"Content-Type": "application/json"})
    r = json.load(urllib.request.urlopen(req, timeout=1800))
    rec = {"role": role, "model": model, "in": r.get("prompt_eval_count", 0), "out": r.get("eval_count", 0),
           "secs": round(time.time() - t0, 1)}
    log.write(json.dumps(rec) + "\n"); log.flush()
    print("    %-22s %5d in %5d out %6.0f s" % (role, rec["in"], rec["out"], rec["secs"]))
    return r["message"]["content"]

def code_block(text):
    m = re.findall(r"```(?:python)?\n(.*?)```", text, re.S)
    return (max(m, key=len) if m else text).strip() + "\n"

def write_file(repo, entry, contract, note=None, failure=None):
    path = entry["path"]
    current = (repo / path).read_text() if (repo / path).exists() else ""
    prompt = ("You are one developer in a team. Write the complete file %s and nothing else.\n\n"
              "Product spec:\n%s\n\nTeam contract (other files are written by other developers and follow it):\n%s\n"
              % (path, SPEC, json.dumps(contract, indent=1)))
    if note:
        prompt += "\nYour current file:\n```python\n%s```\nThe tests fail:\n%s\nReviewer note for you: %s\n" % (current, failure[-1500:], note)
    prompt += "\nReply with the full content of %s in one ```python block." % path
    text = chat("coder " + path.split("/")[-1], CODER, [{"role": "user", "content": prompt}])
    (repo / path).parent.mkdir(parents=True, exist_ok=True)
    (repo / path).write_text(code_block(text))

def test(repo, pattern):
    r = subprocess.run([sys.executable, "-m", "unittest", "discover", "-s", "tests", "-t", ".", "-p", pattern],
                       cwd=repo, capture_output=True, text=True, timeout=120)
    out = r.stdout + r.stderr
    ran = re.search(r"Ran (\d+) test", out)
    bad = re.search(r"FAILED \((.*)\)", out)
    return r.returncode == 0, "%s tests, %s" % (ran.group(1) if ran else "?", bad.group(1) if bad else "OK"), out

def main():
    global log
    ap = argparse.ArgumentParser()
    ap.add_argument("out")
    ap.add_argument("--contract", choices=["planner", "human"], default="planner")
    ap.add_argument("--rounds", type=int, default=3)
    a = ap.parse_args()
    out = Path(a.out); shutil.rmtree(out, ignore_errors=True); out.mkdir(parents=True)
    repo = out / "repo"; (repo / "shortener").mkdir(parents=True); (repo / "tests").mkdir()
    (repo / "shortener" / "__init__.py").write_text(""); (repo / "tests" / "__init__.py").write_text("")
    shutil.copy(LAB / "smoke" / "test_smoke.py", repo / "tests")
    log = open(out / "calls.jsonl", "w")
    t0 = time.time()

    print("== 1. contract (%s)" % a.contract)
    if a.contract == "human":
        contract = HUMAN_CONTRACT
    else:
        contract = json.loads(chat("planner", PLANNER, [{"role": "user", "content":
            "You are the tech lead. Split this spec into the files listed in its Structure section. For each file give the "
            "exact public interface (signatures with types and return values) and what it uses from the other files, "
            "plus shared rules every developer must follow.\n\n" + SPEC}], CONTRACT_SCHEMA, 1200))
    (out / "contract.json").write_text(json.dumps(contract, indent=1))
    for f in contract["files"]:
        print("    %s: %s" % (f["path"], " | ".join(f["interface"])[:160]))

    print("== 2. coders write their files")
    for entry in contract["files"]:
        write_file(repo, entry, contract)

    for rnd in range(1, a.rounds + 1):
        ok, summary, output = test(repo, "test_*.py")
        print("== 3.%d smoke tests: %s" % (rnd, summary))
        if ok:
            break
        print("    " + "\n    ".join([l for l in output.splitlines() if "Error" in l or "error" in l][:6]))
        review = json.loads(chat("reviewer", REVIEWER, [{"role": "user", "content":
            "You review a team's work. The smoke tests fail. Decide which files must change and write one short, concrete "
            "note for the owner of each such file.\n\nContract:\n%s\n\nTest output:\n%s\n\nFiles:\n%s" % (
                json.dumps(contract, indent=1), output[-2500:],
                "\n".join("--- %s\n%s" % (e["path"], (repo / e["path"]).read_text() if (repo / e["path"]).exists() else "(missing)")
                          for e in contract["files"]))}], REVIEW_SCHEMA, 500))
        owners = {e["path"]: e for e in contract["files"]}
        for fix in review["fixes"]:
            print("    note for %s: %s" % (fix["path"], fix["note"][:200]))
            if fix["path"] in owners:
                write_file(repo, owners[fix["path"]], contract, fix["note"], output)

    smoke_ok, smoke, _ = test(repo, "test_*.py")
    for f in (LAB / "hidden").glob("*.py"):
        shutil.copy(f, repo / "tests")
    hid_ok, hidden, hid_out = test(repo, "hidden_*.py")
    (out / "hidden-output.txt").write_text(hid_out)
    calls = [json.loads(l) for l in open(out / "calls.jsonl")]
    by_role = {}
    for c in calls:
        r = by_role.setdefault(c["role"].split()[0], [0, 0, 0, 0.0])
        r[0] += 1; r[1] += c["in"]; r[2] += c["out"]; r[3] += c["secs"]
    print("== result: smoke %s | hidden acceptance %s | %d calls, %d tokens in, %d out, %.0f s wall" % (
        smoke, hidden, len(calls), sum(c["in"] for c in calls), sum(c["out"] for c in calls), time.time() - t0))
    for role, (n, i, o, s) in by_role.items():
        print("    %-9s %2d calls %6d in %5d out %6.0f s" % (role, n, i, o, s))

if __name__ == "__main__":
    main()
```

في الكود أعلاه لاحظ التالي:

- العقد يكتب بمخطط JSON في الحقل `format`، فلا يستطيع المخطط أن يرجع نصاً حراً، وكل ملف فيه حقول `path` و`purpose` و`interface` و`uses`.
- الثابت `HUMAN_CONTRACT` هو العقد الذي يكتبه إنسان من قسم Structure في المواصفة، ويستعمل في التشغيل الثاني فقط بالخيار `--contract human`، ولاحظ أنه يحدد تفاصيل لا تذكرها المواصفة صراحة، مثل أن `encode(62)` يرجع `'10'`، وطريقة قراءة جسم الطلب في WSGI.
- المبرمج لا يملك أدوات، وإنما يكتب الملف كاملاً في كتلة كود، والسكربت يأخذ أطول كتلة. وهذا أبسط من وكيل كامل، وهو ما تفعله أغلب أطر الفرق في دور المبرمج.
- الاختبارات المخفية لا تنسخ إلى المستودع إلا بعد انتهاء الجولات كلها.

والسكربت هنا لا يستعمل أي إطار تنسيق Orchestration Framework، وإنما Python عادي يرسل الطلبات إلى Ollama ويشغل الاختبارات، والسبب أننا نريد أن نرى كل رسالة تمر بين الأدوار دون طبقة تخفي شيئاً. أما الأطر المعروفة مثل LangGraph وCrewAI وAG2 فتقدم الأدوار نفسها جاهزة، أي المخطط والمنفذين والمراجع والحلقة بينهم، وقد قارنا بينها بالأرقام في [مقال أطر تنسيق الوكلاء](https://arabroot.io/articles/%D8%A7%D8%B7%D8%B1-%D8%AA%D9%86%D8%B3%D9%8A%D9%82-%D8%A7%D9%84%D9%88%D9%83%D9%84%D8%A7%D8%A1-agent-frameworks-langgraph-%D9%88crewai-%D9%88ag2/). والذي يهمنا هنا ليس الإطار، وإنما ما يحدث بين الأدوار عندما تكون المهمة منصة لا دالة، وهو لا يتغير كثيراً بتغير الإطار، لأن الإطار ينقل الرسائل ولا يقرر ما فيها.

وكل دور في السكربت يعادل شيئاً في أي فريق برمجة تعرفه: المخطط هو المهندس الذي يكتب وثيقة التصميم Design Document، والعقد هو قسم الواجهات فيها، والمبرمجون هم من يأخذون التذاكر Tickets، والمختبر هو خط CI، والمراجع هو من يقرأ طلبات الدمج. والفرق الوحيد أن كل هؤلاء هنا نماذج لا تستطيع أن تسأل بعضها، ولا أن تفتح ملف زميل إلا عندما يعطيها السكربت إياه.

## كيف جعلنا التجربة عادلة؟

تجربة واحدة على مهمة واحدة لا تثبت قاعدة عامة، ولكنها تستطيع أن تكون أمينة فيما تقيسه، وهذه القرارات التي أخذناها قبل التشغيل حتى لا نغير شيئاً بعد أن نرى النتيجة:

- **لا تدخل بشري أثناء التشغيل:** لا نصحح ملفاً، ولا نعيد جولة، ولا نعدل تعليمات المراجع بعد أن نرى ملاحظاته. والتغيير الوحيد بين التشغيلين هو العقد.
- **حرارة صفر وبذرة ثابتة:** كل استدعاء بحرارة Temperature صفر وبذرة Seed واحدة، حتى يكون الفرق بين التشغيلين من العقد وليس من الصدفة قدر الإمكان، مع العلم أن النموذج نفسه قد يعطي رداً مختلفاً عندما يتغير أي حرف في الطلب.
- **حد ثابت للجولات:** ثلاث جولات مراجعة في كل تشغيل، وهو رقم قريب مما تستعمله الأطر في أمثلتها، لأن جولات أكثر تعني توكنات أكثر دون ضمان.
- **حكم كتبه إنسان قبل التجربة:** اختبارات القبول الأحد عشر كتبت من المواصفة، وتأكدنا أن الحل المرجعي ينجح فيها، قبل أن يكتب أي وكيل سطراً.
- **كل شيء مسجل:** العقد، وكل استدعاء، وكل ملف نهائي، ومخرج الاختبارات، محفوظة في مجلد المختبر، فتستطيع أن تقرأ ما قرأناه وتحكم بنفسك.

وما لا تقوله هذه التجربة: لا تقول إن فرق الوكلاء لا تنجح أبداً، ولا إن هذين النموذجين سيئان في كل شيء، فقد رأينا qwen3 يحل مهام في مقال بناء الوكيل. وإنما تقول إن فريقاً بهذا التنظيم، بنماذج بهذا الحجم، على منصة فيها طبقات تعتمد على بعضها، لم يصل إلى منصة تعمل في ثلاث جولات، وتقول أين بالضبط تعطل.

## ماذا كتب المخطط في العقد؟

قبل أن ننظر إلى ما كتبه المبرمجون، هذا العقد الذي كتبه المخطط في التشغيل الأول كما حفظه السكربت في `contract.json`، وهو كل ما يعرفه كل مبرمج عن زملائه:

```json
{
 "files": [
  {
   "interface": [
    "def encode(n: int) -> str: ...",
    "Raises: ValueError if n < 1"
   ],
   "path": "shortener/codes.py",
   "purpose": "Provides base62 encoding of integers (row IDs) to generate short codes.",
   "uses": [
    "None"
   ]
  },
  {
   "interface": [
    "class LinkStore(path: str):",
    "    def add(self, url: str) -> str: ...",
    "    def get(self, code: str) -> str | None: ...",
    "    def hit(self, code: str) -> None: ...",
    "    def stats(self, code: str) -> dict[str, str | int] | None: ...",
    "    Raises: ValueError if path is invalid or database cannot be opened"
   ],
   "path": "shortener/store.py",
   "purpose": "Manages the persistent storage of links in SQLite, with methods to add, retrieve, hit, and get stats for a link.",
   "uses": [
    "shortener.codes.encode"
   ]
  },
  {
   "interface": [
    "def make_app(store: LinkStore) -> WSGI application: ...",
    "Returns: A WSGI application (callable) that handles HTTP requests for /links, /<code>, and /links/<code>/stats."
   ],
   "path": "shortener/app.py",
   "purpose": "Implements the HTTP routing and response logic for the link shortener service.",
   "uses": [
    "shortener.store.LinkStore",
    "shortener.codes.encode"
   ]
  }
 ],
 "shared_rules": [
  "All files must use only the Python standard library (no third-party packages).",
  "All JSON responses must have the header `Content-Type: application/json`.",
  "All error responses must be JSON objects with a key `error` and a string value.",
  "All HTTP responses must be properly encoded and sent with correct status codes (e.g., 400, 404, 201, 302).",
  "All code paths must validate inputs strictly: URLs must start with `http://` or `https://` and be at most 2000 characters long.",
  "No duplicate entries: if a URL is already stored, the same code must be returned (no new codes for duplicates).",
  "The `encode` function must produce a base62 string (digits 0\u20139, letters a\u2013z, A\u2013Z) of the row ID, with the first link having code '1'.",
  "The `hit` method must increment the hit counter for a given code; if the code is not found, it must return 404.",
  "The `stats` method must return a dictionary with keys 'code', 'url', and 'hits' if the code exists; otherwise, return 404.",
  "All file paths must be relative and under the `shortener/` directory.",
  "All functions and methods must be pure or side-effect free unless explicitly stated (e.g., database writes).",
  "All error handling must be explicit and not silently fail; errors must be returned as JSON with a clear error message.",
  "The WSGI application must accept a `store` instance and not create or modify it.",
  "All code must be unit-testable and follow PEP 8 style guidelines."
 ]
}
```

في العقد أعلاه لاحظ التالي:

- التواقيع صحيحة وتطابق المواصفة، والقسم `uses` يقول صراحة إن ملف التخزين يستعمل `shortener.codes.encode`، فالمخطط فهم أن الرمز يولد في ملف واحد.
- القواعد المشتركة الأربع عشرة طويلة، وأغلبها يكرر المواصفة بكلمات أخرى، وبعضها عام لا يفحص، مثل «كل الدوال يجب أن تكون نقية» و«اتبع PEP 8». والقاعدة المهمة «المكتبة القياسية فقط» في أولها، ولكنها ضاعت بين ثلاث عشرة قاعدة أخرى.
- القاعدة السابعة تذكر الترتيب الصحيح، أي الأرقام ثم الحروف الصغيرة ثم الكبيرة، ولكن المبرمج كتب `ascii_letters + digits` رغم ذلك، أي أن القاعدة كانت موجودة بصيغة يسهل أن تقرأ بسرعة. أما المثال `encode(62) == '10'` فلم يكتبه المخطط، وهو الذي جعل الملف صحيحاً في التشغيل الثاني.
- القاعدتان عن `hit` و`stats` تقولان «ترجع 404» لدالتين في طبقة التخزين، وهذا خلط بين طبقة التخزين وطبقة HTTP، فطبقة التخزين ترجع `None` والتطبيق هو الذي يرد بالرمز 404\. أي أن العقد نفسه أدخل لبساً لم يكن في المواصفة.

## التشغيل الأول: المخطط يكتب العقد

شغلنا الفريق بالأمر الأول في السكربت `run.sh`، أي بعقد يكتبه المخطط، والمخرج كاملاً كما يلي:

```text
== 1. contract (planner)
    planner                  559 in   755 out    272 s
    shortener/codes.py: def encode(n: int) -> str: ... | Raises: ValueError if n < 1
    shortener/store.py: class LinkStore(path: str): |     def add(self, url: str) -> str: ... |     def get(self, code: str) -> str | None: ... |     def hit(self, code: str) -> None: 
    shortener/app.py: def make_app(store: LinkStore) -> WSGI application: ... | Returns: A WSGI application (callable) that handles HTTP requests for /links, /<code>, and /links/<cod
== 2. coders write their files
    coder codes.py          1341 in    99 out     77 s
    coder store.py          1339 in   582 out    239 s
    coder app.py            1339 in   357 out    126 s
== 3.1 smoke tests: 1 tests, errors=1
    ImportError: Failed to import test module: tests.test_smoke
    ModuleNotFoundError: No module named 'flask'
    FAILED (errors=1)
    reviewer                2072 in   109 out    150 s
    note for shortener/app.py: You must remove the import of `flask` from `shortener/app.py` because the project requires only the Python standard library. Replace the Flask-based WSGI app with a standard Python implementation that
    coder app.py            2008 in  1133 out    344 s
== 3.2 smoke tests: 1 tests, errors=1
    ImportError: Failed to import test module: tests.test_smoke
    ModuleNotFoundError: No module named 'base62'
    FAILED (errors=1)
    reviewer                2841 in   241 out    261 s
    note for shortener/app.py: You must remove the import of `base62` from `shortener/app.py` because `base62` is not a standard library module. The `encode` and `decode` functionality must be implemented in `shortener/codes.py` an
    coder app.py            2809 in  1118 out    425 s
    note for shortener/store.py: You are using `self.decode` in `store.py` without defining it. The `decode` method must be implemented in `shortener/codes.py` and must be called from `store.py`. Remove the `decode` method from `stor
    coder store.py          2233 in   436 out    116 s
== 3.3 smoke tests: 2 tests, failures=1, errors=1
    TypeError: BaseRequestHandler.__init__() missing 2 required positional arguments: 'client_address' and 'server'
    AssertionError: 'b' != '1'
    FAILED (failures=1, errors=1)
    reviewer                2791 in   359 out    484 s
    note for shortener/app.py: shortener/app.py: The `__init__` method of `ShortenerHandler` calls `super().__init__(*args, **kwargs)` but passes no arguments. The `BaseHTTPRequestHandler` constructor requires `client_address` and 
    coder app.py            2956 in  1117 out    466 s
    note for shortener/store.py: shortener/store.py: The `encode` method in `LinkStore` is incorrectly implemented. It returns a string, but the test expects `encode(1)` to return `'1'`. However, your current implementation uses a cu
    coder store.py          2265 in   482 out    154 s
== result: smoke 2 tests, failures=1, errors=1 | hidden acceptance 11 tests, failures=3, errors=6 | 12 calls, 24553 tokens in, 6788 out, 3119 s wall
    planner    1 calls    559 in   755 out    272 s
    coder      8 calls  16290 in  5324 out   1946 s
    reviewer   3 calls   7704 in   709 out    896 s
```

والقصة كاملة تظهر إذا قرأنا المخرج من البداية:

- **العقد:** كتب المخطط في 272 ثانية عقداً يبدو جيداً من بعيد: التواقيع صحيحة، و14 قاعدة مشتركة، منها «استعمل مكتبة Python القياسية فقط»، و«الرمز الأول هو '1'». ولكنه لم يكتب ترتيب الحروف في base62، ولا ما ترجعه `get` بالضبط، ولا كيف تقرأ طبقة WSGI جسم الطلب، أي القرارات الثلاثة التي سقطت فيها المنصة بعد ذلك.
- **الجولة الأولى:** مبرمج `app.py` كتب الخدمة بـ Flask، رغم أن المواصفة تقول مكتبة قياسية فقط، والعقد يكرر ذلك في أول قاعدة. فلم تبدأ الاختبارات أصلاً، وكتب المراجع ملاحظة صحيحة: احذف Flask واكتب WSGI بالمكتبة القياسية.
- **الجولة الثانية:** حذف المبرمج Flask، وكتب مكانها `import base62`، وهي مكتبة غير موجودة في المكتبة القياسية ولم تثبت. وهذا بالضبط ما شرحناه في [مقال الحزم الوهمية](https://arabroot.io/articles/%D8%A7%D9%84%D8%AD%D8%B2%D9%85-%D8%A7%D9%84%D9%88%D9%87%D9%85%D9%8A%D8%A9-slopsquatting-%D9%85%D9%83%D8%AA%D8%A8%D8%A9-%D9%8A%D8%AE%D8%AA%D8%B1%D8%B9%D9%87%D8%A7-%D8%A7%D9%84%D9%88%D9%83%D9%8A%D9%84/): النموذج يستورد اسماً يبدو منطقياً، ولو كان الخط يثبت الاعتماديات تلقائياً لثبت ما يجده على PyPI بهذا الاسم. ثم كتب المراجع ملاحظة ثانية لصاحب `store.py`، لأن ملفه يستدعي `self.decode` دون أن يعرفه.
- **الجولة الثالثة:** بدأت الاختبارات أخيراً، وفشلت لسببين: طبقة HTTP مكتوبة كـ `BaseHTTPRequestHandler` من `http.server` وليست تطبيق WSGI كما تطلب المواصفة، و`encode(1)` يرجع `'b'` بدل `'1'`. ووجه المراجع ملاحظة `encode` إلى صاحب `store.py` وليس إلى صاحب `codes.py`، لأن ملف التخزين كان قد كتب دالة `encode` خاصة به داخل الكلاس، فبقي الخطأ الحقيقي في `codes.py` دون أن يلمسه أحد.

والشكل التالي يلخص الجولات الثلاث:

![خمسة صفوف: العقد من المخطط بلا ترتيب حروف base62، ثم الجولة الأولى وفيها خطأ No module named flask، ثم الجولة الثانية وفيها No module named base62، ثم الجولة الثالثة وفيها خطأ BaseRequestHandler وencode(1) يرجع b، ثم القبول المخفي 2 من 11 مع استعمال eval](https://arabroot.io/content/images/2026/11/agent-team-builds-platform-02-run1.webp)

كل جولة أصلحت الخطأ الذي ظهر، وفتحت خطأً آخر لم يكن في العقد.

وبعد الجولات الثلاث، هذه نتيجة اختبارات القبول المخفية:

```text
ERROR: test_bad_json (tests.hidden_acceptance.Api.test_bad_json)
ERROR: test_create (tests.hidden_acceptance.Api.test_create)
ERROR: test_duplicate_post (tests.hidden_acceptance.Api.test_duplicate_post)
ERROR: test_invalid_urls (tests.hidden_acceptance.Api.test_invalid_urls)
ERROR: test_not_found (tests.hidden_acceptance.Api.test_not_found)
ERROR: test_redirect_counts_hits (tests.hidden_acceptance.Api.test_redirect_counts_hits)
FAIL: test_base62 (tests.hidden_acceptance.Codes.test_base62)
FAIL: test_add_get_hit_stats (tests.hidden_acceptance.Store.test_add_get_hit_stats)
FAIL: test_unknown (tests.hidden_acceptance.Store.test_unknown)
Ran 11 tests in 0.078s
FAILED (failures=3, errors=6)
```

نجح اختباران من 11 فقط، وفشلت كل اختبارات طبقة HTTP الستة بالخطأ نفسه، لأن `make_app` ترجع كلاساً وليس تطبيق WSGI يقبل `(environ, start_response)`. والأسباب الحقيقية تظهر في الملفات الثلاثة النهائية التي حفظناها في `out/planner-final`، وهذا ملف الرموز:

```python
import string
import random

def encode(n: int) -> str:
    if n < 1:
        raise ValueError("n must be greater than or equal to 1")
    
    base62_chars = string.ascii_letters + string.digits
    code = ""
    
    while n > 0:
        n, remainder = divmod(n, 62)
        code = base62_chars[remainder] + code
    
    return code
```

الخوارزمية صحيحة، ولكن الحروف بترتيب `string.ascii_letters + string.digits`، أي الحروف قبل الأرقام، فالرمز 1 هو `b` والرمز 62 هو `ba`، بينما المواصفة تقول بوضوح `0-9a-zA-Z`. وهذا الخطأ لم يكتشفه المراجع لأنه لم يذكر في العقد، ولأن الملاحظة الوحيدة عن `encode` ذهبت إلى الملف الخطأ. أما ملف التخزين فهذا جزء منه:

```python
    def get(self, code: str) -> Optional[str]:
        try:
            return self.decode(code)
        except ValueError:
            return None

    def hit(self, code: str) -> None:
        try:
            self.decode(code)
            self.cursor.execute('UPDATE links SET hits = hits + 1 WHERE id = ?', (code,))
            self.conn.commit()
        except ValueError:
            pass

    def stats(self, code: str) -> Optional[dict]:
        try:
            return self.decode(code)
        except ValueError:
            return None
```

العقد يقول إن `store.py` يستعمل `shortener.codes.encode`، والمبرمج كتب `encode` و`decode` خاصتين به داخل الكلاس، ثم جعل `get` و`stats` ترجعان رقم الصف بدل الرابط والإحصاء، وجعل `hit` يبحث برقم صف يساوي نص الرمز. فالملف يتجاهل نصف العقد. أما ملف `app.py` فهو أسوأ الثلاثة: ينسخ الكلاس `LinkStore` كاملاً بداخله، ويستعمل `json` و`codes` دون أن يستوردهما، ويقرأ جسم الطلب بالدالة `eval`:

```python
class ShortenerHandler(BaseHTTPRequestHandler):
    def do_POST(self):
        content_length = int(self.headers['Content-Length'])
        post_data = self.rfile.read(content_length)
        try:
            data = post_data.decode('utf-8')
            json_data = eval(data)
```

🛑

السطر `json_data = eval(data)` ينفذ أي كود Python يرسله أي شخص في جسم الطلب، أي ثغرة تنفيذ كود عن بعد Remote Code Execution كاملة في خدمة يصل إليها الإنترنت. والاختبارات لم تكشفه لأنها لم تصل إلى هذا السطر أصلاً، والمراجع لم يذكره في أي من ملاحظاته الثلاث. لا تقم بدمج كود كتبه فريق وكلاء دون أن يمر بفحص أمني ثابت مثل Bandit أو Semgrep، كما في [مقال المراجعة](https://arabroot.io/articles/%D9%85%D8%B1%D8%A7%D8%AC%D8%B9%D8%A9-%D9%83%D9%88%D8%AF-%D8%A7%D9%84%D8%B0%D9%83%D8%A7%D8%A1-%D8%A7%D9%84%D8%A7%D8%B5%D8%B7%D9%86%D8%A7%D8%B9%D9%8A-%D8%AF%D9%88%D9%86-%D8%A7%D9%86-%D8%AA%D8%B5%D8%A8%D8%AD-%D8%B4%D9%83%D9%84%D9%8A%D8%A9/)، والسبب أن نجاح الاختبارات لا يقول شيئاً عن السطر الذي لم تختبره.

## سجل الاستدعاءات: من عمل، ومتى؟

كل استدعاء للنموذج في الفريق يسجل في `calls.jsonl` بدوره والنموذج والتوكنات والثواني، وهذا سجل التشغيل الأول كاملاً:

```json
{"role": "planner", "model": "qwen3:4b-instruct", "in": 559, "out": 755, "secs": 272.2}
{"role": "coder codes.py", "model": "qwen2.5-coder:3b", "in": 1341, "out": 99, "secs": 77.0}
{"role": "coder store.py", "model": "qwen2.5-coder:3b", "in": 1339, "out": 582, "secs": 239.4}
{"role": "coder app.py", "model": "qwen2.5-coder:3b", "in": 1339, "out": 357, "secs": 125.5}
{"role": "reviewer", "model": "qwen3:4b-instruct", "in": 2072, "out": 109, "secs": 150.4}
{"role": "coder app.py", "model": "qwen2.5-coder:3b", "in": 2008, "out": 1133, "secs": 343.7}
{"role": "reviewer", "model": "qwen3:4b-instruct", "in": 2841, "out": 241, "secs": 261.2}
{"role": "coder app.py", "model": "qwen2.5-coder:3b", "in": 2809, "out": 1118, "secs": 424.6}
{"role": "coder store.py", "model": "qwen2.5-coder:3b", "in": 2233, "out": 436, "secs": 116.0}
{"role": "reviewer", "model": "qwen3:4b-instruct", "in": 2791, "out": 359, "secs": 484.1}
{"role": "coder app.py", "model": "qwen2.5-coder:3b", "in": 2956, "out": 1117, "secs": 465.9}
{"role": "coder store.py", "model": "qwen2.5-coder:3b", "in": 2265, "out": 482, "secs": 154.3}
```

وقراءة السجل بالترتيب تقول ثلاثة أشياء لا تظهر في النتيجة النهائية. الأول أن مبرمج `codes.py` عمل مرة واحدة فقط في 77 ثانية ولم يلمسه أحد بعد ذلك، رغم أن ملفه هو الذي فشل في الجولة الثالثة، لأن الملاحظة ذهبت إلى غيره. والثاني أن مبرمج `app.py` عمل أربع مرات، وكتب في كل مرة أكثر من ألف توكن بعد الأولى، أي أنه أعاد كتابة الخدمة كاملة ثلاث مرات: بدأ بـ Flask، ثم كتب نسخة تستورد مكتبة وهمية، وانتهى بـ `http.server` مع كلاس منسوخ. والثالث أن مدخل المراجع ثابت تقريباً بين ألفين وثلاثة آلاف توكن، لأنه يقرأ الملفات كلها في كل جولة، بينما الذي تغير بين الجولات ملف أو اثنان فقط. وهذا مكان واضح لتوفير التوكنات: أن يرى المراجع الفرق بين الجولتين ومخرج الاختبارات، لا المستودع كله.

## التشغيل الثاني: إنسان يكتب العقد

والسؤال الطبيعي بعد التشغيل الأول: هل المشكلة في العقد؟ فالعقد لم يذكر ترتيب الحروف، ولم يقل ما ترجعه `get`. ولذلك أعدنا التجربة بتغيير واحد فقط، وهو أن العقد هو `HUMAN_CONTRACT` الذي كتبناه نحن من المواصفة، وفيه الحروف بترتيبها، و`encode(62) == '10'`، وأن `make_app` ترجع `app(environ, start_response)`، وكيف يقرأ التطبيق جسم الطلب. والمخرج كاملاً كما يلي:

```text
== 1. contract (human)
    shortener/codes.py: ALPHABET = '0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ' | def encode(n: int) -> str  # n >= 1, else ValueError; encode(1) == '1', encode(62)
    shortener/store.py: class LinkStore: | def __init__(self, path: str)  # sqlite3.connect(path), creates the table | def add(self, url: str) -> str  # insert, code = encode(row id); 
    shortener/app.py: def make_app(store) -> callable  # returns app(environ, start_response) | POST /links -> 201 {code, short_url} | 400 {error: 'invalid url'} | GET /<code> -> 302
== 2. coders write their files
    coder codes.py          1047 in   114 out     50 s
    coder store.py          1045 in   532 out    173 s
    coder app.py            1045 in   711 out    283 s
== 3.1 smoke tests: 1 tests, errors=1
    ImportError: Failed to import test module: tests.test_smoke
    ModuleNotFoundError: No module named 'flask'
    FAILED (errors=1)
    reviewer                2097 in   227 out    212 s
    note for shortener/store.py: You must remove the import of 'base62' from app.py. It is unused and causes a conflict with the existing codes.encode function. Also, the store.py file incorrectly redefines encode — it should not dup
    coder store.py          1909 in   532 out    155 s
    note for shortener/app.py: You must remove the import of 'flask' from app.py. The test fails because flask is not installed. This violates the shared rule of using only standard library modules. Replace the Flask-based app with
    coder app.py            2073 in  1186 out    640 s
== 3.2 smoke tests: 1 tests, errors=1
    ImportError: Failed to import test module: tests.test_smoke
    ModuleNotFoundError: No module named 'base62'
    FAILED (errors=1)
    reviewer                2565 in   390 out    520 s
    note for shortener/codes.py: shortener/codes.py: Remove the duplicate `encode` function. The base62 encoding logic is already defined in shortener/app.py and should not be duplicated. This file only needs to define the ALPHABET a
    coder codes.py          1478 in    30 out     45 s
    note for shortener/store.py: shortener/store.py: Fix the `add`, `get`, `hit`, and `stats` methods to use the correct column name (`id` instead of `code`) in SQL queries. The database schema defines `id` as the primary key, so all
    coder store.py          1909 in   532 out    319 s
    note for shortener/app.py: shortener/app.py: Remove the import of `base62` and replace the `encode` function with a direct implementation using the ALPHABET defined at the top. The `encode` function must be implemented here to 
    coder app.py            2590 in  1188 out    334 s
== 3.3 smoke tests: 1 tests, errors=1
    ImportError: Failed to import test module: tests.test_smoke
    ImportError: cannot import name 'encode' from 'shortener.codes' (/lab/data/human/repo/shortener/codes.py)
    FAILED (errors=1)
    reviewer                2471 in   478 out    242 s
    note for shortener/codes.py: shortener/codes.py: The `encode` function is defined here, but it's not imported in tests. Ensure the function is properly defined and accessible. Add a proper import in tests/test_smoke.py to import 
    coder codes.py          1386 in   117 out     25 s
    note for shortener/store.py: shortener/store.py: The `encode` function is defined here, but it's used in `add` and `stats` methods. However, the method `get` incorrectly attempts to convert `code` to an integer and uses it as a t
    coder store.py          1955 in   485 out    138 s
    note for shortener/app.py: shortener/app.py: The `encode` function is defined here, but it's not used in the correct context. The `get` method uses `code` as a string in the query but expects an integer — this is a bug. Also, t
    coder app.py            2608 in  1198 out    286 s
== result: smoke 1 tests, errors=1 | hidden acceptance 1 tests, errors=1 | 14 calls, 26178 tokens in, 7720 out, 3427 s wall
    coder     11 calls  19045 in  6625 out   2450 s
    reviewer   3 calls   7133 in  1095 out    974 s
```

في المخرج أعلاه لاحظ التالي:

- مبرمج `app.py` كتب Flask مرة أخرى في الجولة الأولى، ثم `base62` في الثانية، تماماً كما في التشغيل الأول، رغم أن العقد الجديد يقول صراحة إن `make_app` ترجع دالة WSGI، وإن المكتبة القياسية وحدها مسموحة. أي أن العقد الأدق لم يغير شيئاً في هذا الملف.
- المراجع في الجولة الثانية أرسل إلى صاحب `codes.py` ملاحظة خاطئة تماماً: «احذف الدالة `encode` المكررة، فهي موجودة في `app.py`». والمبرمج نفذ، فكتب ملفاً من 30 توكناً فقط، ففشلت الجولة الثالثة بالخطأ `cannot import name 'encode'`. أي أن المراجع، وهو أكبر النماذج في الفريق، أفسد ملفاً كان صحيحاً، لأن ملفاً آخر نسخ منه دالته.
- في الجولة الثالثة أعاد المراجع الدالة إلى مكانها، ولكن مبرمج `app.py` كتب الخدمة هذه المرة بـ `http.server` مع دالة `run`، دون `make_app` أصلاً، فلم تستطع اختبارات القبول حتى أن تستورد الملف، ونتيجتها خطأ واحد.

والنتيجة الإجمالية تقول إن التشغيل الثاني أسوأ من الأول، ولكن هذا الرقم يخفي ما حدث فعلاً، لأن ملفاً لا يستورد يوقف كل الاختبارات. ولذلك كتبنا سكربتاً صغيراً اسمه `per_file.py` يشغل اختبارات القبول لكل طبقة وحدها، فاختبارات `Codes` و`Store` لا تحتاج `app.py`:

```python
# Runs the hidden acceptance tests file by file: the Codes and Store tests need only codes.py and store.py,
# so a broken app.py does not hide whether the other two files are right.
#   python per_file.py data/planner/repo data/human/repo
import subprocess, sys, tempfile, shutil, re
from pathlib import Path

SRC = Path(__file__).parent / "hidden" / "hidden_acceptance.py"
text = SRC.read_text()
for repo in sys.argv[1:]:
    for cls in ("Codes", "Store", "Api"):
        with tempfile.TemporaryDirectory() as tmp:
            r = Path(tmp) / "r"
            shutil.copytree(repo, r)
            body = text if cls == "Api" else text.replace("from shortener.app import make_app\n", "")
            (r / "tests" / "hidden_acceptance.py").write_text(body)
            out = subprocess.run([sys.executable, "-m", "unittest", "tests.hidden_acceptance.%s" % cls], cwd=r,
                                 capture_output=True, text=True).stderr
            ran = re.search(r"Ran (\d+)", out)
            res = re.search(r"(OK|FAILED \(.*\))", out)
            print("%-22s %-6s %s tests, %s" % (repo, cls, ran.group(1) if ran else "0", res.group(1) if res else out.strip().splitlines()[-1]))
```

والمخرج للتشغيلين كما يلي:

```text
data/planner/repo      Codes  2 tests, FAILED (failures=1)
data/planner/repo      Store  3 tests, FAILED (failures=2)
data/planner/repo      Api    6 tests, FAILED (errors=6)
data/human/repo        Codes  2 tests, OK
data/human/repo        Store  3 tests, FAILED (failures=2)
data/human/repo        Api    1 tests, FAILED (errors=1)
```

وهنا يظهر أثر العقد بوضوح: في التشغيل الثاني نجح ملف الرموز في اختباريه كاملين، لأن العقد كتب ترتيب الحروف ومثالين، أما في الأول فنجح في اختبار واحد من اثنين بترتيب الحروف الخاطئ. وملف التخزين نجح في اختبار واحد من ثلاثة في التشغيلين، لأن كل مبرمج له كرر الدالة `encode` بنفسه بطريقة خاطئة بدل أن يستوردها من `codes.py` كما يقول العقد. وملف التطبيق فشل في التشغيلين، مرة لأنه كلاس وليس دالة WSGI، ومرة لأن الدالة غير موجودة. والشكل التالي يجمع ذلك:

![جدول بصفين للتشغيلين وثلاثة أعمدة للملفات. التشغيل الأول بعقد المخطط: codes.py 1 من 2، وstore.py 1 من 3، وapp.py 0 من 6. التشغيل الثاني بعقد الإنسان: codes.py 2 من 2، وstore.py 1 من 3، وapp.py لا يستورد. وتحت الجدول ملاحظة أن العقد الأدق أصلح الملف الذي لا يعتمد على غيره فقط](https://arabroot.io/content/images/2026/11/agent-team-builds-platform-03-per-file.webp)

العقد الأدق أصلح الملف الذي لا يعتمد على غيره، أما الملفات التي تجمع الأجزاء فبقيت تتجاهل العقد.

## العقد الذي كتبه الإنسان، سطراً سطراً

في الكود أعلاه، الثابت `HUMAN_CONTRACT` هو العقد الذي استعملناه في التشغيل الثاني، ويستحق أن تقرأه بعين من يكتب عقداً لفريق، لأن كل سطر فيه جواب عن سؤال سوف يسأله مبرمج لا يستطيع أن يسأل:

- `ALPHABET = '0123456789abc...XYZ'` مكتوب كاملاً في عقد ملف الرموز، لأن المواصفة تقول `0-9a-zA-Z`، وهذا الوصف المختصر هو بالضبط ما فهمه مبرمج التشغيل الأول بشكل خاطئ. والنتيجة أن ملف الرموز في التشغيل الثاني نجح في اختباريه.
- `encode(1) == '1', encode(62) == '10'` مثالان يقطعان أي خلاف: هل نبدأ من صفر أم من واحد، وهل الرمز التالي للحرف الأخير يصبح رقمين.
- `code = encode(row id)` و«الرابط نفسه يرجع الرمز الموجود» في عقد التخزين، لأن قرار من يولد الرمز يجب أن يكون في ملف واحد. ومع ذلك كتب مبرمج التخزين في التشغيلين دالة `encode` خاصة به، أي أن السطر كان واضحاً والمبرمج لم يتبعه.
- `make_app(store) -> callable # returns app(environ, start_response)` في عقد التطبيق، أي الشكل الدقيق الذي تستدعيه الاختبارات. وهذا هو السطر الذي لم يتبعه أي مبرمج في أي جولة.
- القاعدة «اقرأ جسم الطلب بـ `int(environ['CONTENT_LENGTH'])`» تفصيل صغير في WSGI يخطئ فيه كثيرون، ولكنه لم يصل إلى الاستعمال أصلاً، لأن التطبيق لم يكتب كدالة WSGI.

والدرس من هذه القائمة أن العقد الجيد شرط لازم وليس كافياً: الملف الذي ينفذ دالة واحدة محددة تبع العقد حرفياً، والملفات التي تحتاج أن تجمع أجزاء وتتخذ قرارات أخرى رجعت إلى ما تعرفه النماذج من بيانات تدريبها، أي Flask و`http.server`، لأن هذا ما تراه في أغلب الأمثلة على الإنترنت لخدمة HTTP في Python.

## الوقت والتوكنات لكل دور

السطر الأخير في مخرج كل تشغيل يجمع الاستدعاءات بحسب الدور، والجدول التالي يضع التشغيلين جنباً إلى جنب:

| الدور     | عقد المخطط: استدعاءات | توكنات داخل / خارج | الثواني | عقد الإنسان: استدعاءات | توكنات داخل / خارج | الثواني |
| --------- | --------------------- | ------------------ | ------- | ---------------------- | ------------------ | ------- |
| المخطط    | 1                     | 559 / 755          | 272     | 0                      | 0 / 0              | 0       |
| المبرمجون | 8                     | 16,290 / 5,324     | 1,946   | 11                     | 19,045 / 6,625     | 2,450   |
| المراجع   | 3                     | 7,704 / 709        | 896     | 3                      | 7,133 / 1,095      | 974     |
| المجموع   | 12                    | 24,553 / 6,788     | 3,119   | 14                     | 26,178 / 7,720     | 3,427   |

في الجدول أعلاه لاحظ التالي:

- المبرمجون يأخذون قرابة ثلثي التوكنات والوقت، لأن كل مبرمج يرسل المواصفة والعقد كاملين في كل استدعاء، ثم يكتب الملف كاملاً من جديد في كل جولة، حتى لو كانت الملاحظة عن سطر واحد. ومبرمج `app.py` وحده كتب أكثر من ألف توكن في كل جولة.
- المراجع يقرأ الملفات الثلاثة ومخرج الاختبارات في كل جولة، فمدخله أكبر مدخل في الفريق، بين ألفين وثلاثة آلاف توكن، ولذلك أخذت استدعاءاته الثلاثة قرابة ربع الوقت رغم أنها ثلاثة فقط.
- العقد الذي كتبه الإنسان وفر استدعاء المخطط، ولكن الفريق احتاج استدعاءات أكثر في الجولات، لأن المراجع وزع الملاحظات على الملفات الثلاثة بدل ملف أو اثنين.
- التشغيل الواحد أخذ قرابة ساعة على المعالج، والنتيجة في الحالتين منصة لا تعمل. وهذا الوقت عند مزود سحابي بنموذج أكبر قد يكون دقائق، ولكن عدد الاستدعاءات والتوكنات هو نفسه تقريباً، وهو ما تدفع ثمنه، كما شرحنا في [مقال تكلفة تعدد الوكلاء](https://arabroot.io/articles/%D9%85%D8%AA%D9%89-%D9%8A%D8%B5%D8%A8%D8%AD-%D8%AA%D8%B9%D8%AF%D8%AF-%D8%A7%D9%84%D9%88%D9%83%D9%84%D8%A7%D8%A1-multi-agent-%D8%A7%D8%BA%D9%84%D9%89-%D9%88%D8%A7%D8%A8%D8%B7%D8%A7-%D9%85%D9%86-%D9%88%D9%83%D9%8A%D9%84-%D9%88%D8%A7%D8%AD%D8%AF/).

## والوكيل الواحد على المهمة نفسها؟

قبل أن نحكم على الفريق يجب أن نسأل السؤال الذي طرحناه في مقال تكلفة تعدد الوكلاء: هل كان وكيل واحد سيفعل أفضل؟ ولذلك أعطينا المواصفة نفسها للوكيل minicode من مقال بناء الوكيل، بالنموذج الذي نجح معه، أي qwen3:4b-instruct باستدعاء الأدوات الأصلي، مع حزمة فارغة واختباري الدخان، وحد 20 خطوة و40 دقيقة. والسكربت `single.sh` يشغله ثم يحكم عليه بالاختبارات المخفية نفسها:

```bash
#!/bin/bash
# The same spec for one agent instead of a team: minicode (from the article on building the agent) gets SPEC.md as the
# issue, an empty package and the two smoke tests, 20 steps; then the hidden acceptance tests grade the result.
set -o pipefail
cd "$(dirname "$0")"
w() { (cd "$1" && pwd -W); }
rm -rf data/single && mkdir -p data/single/work/shortener data/single/work/tests data/single/out
touch data/single/work/shortener/__init__.py data/single/work/tests/__init__.py
cp smoke/test_smoke.py data/single/work/tests/
cp spec/SPEC.md data/single/task.md
MSYS_NO_PATHCONV=1 docker run --rm --name adb-single --network adb-int --read-only --tmpfs /tmp --user 1000:1000 \
  --cap-drop ALL --memory 512m -e PYTHONDONTWRITEBYTECODE=1 \
  -v "$(w data/single/work):/work" -v "$(w data/single/out):/out" -v "$(w single):/agent:ro" -v "$(w data/single):/task:ro" \
  python:3.13.18-slim python -u /agent/agent.py --task /task/task.md --model qwen3:4b-instruct --mode tools --max-steps 20 --max-seconds 2400
MSYS_NO_PATHCONV=1 docker run --rm --network none -v "$(w data/single/work):/work:ro" -v "$(w hidden):/hidden:ro" \
  -v "$(w single):/agent:ro" python:3.13.18-slim python -B /agent/grade.py /work /hidden
```

والمخرج من خطوات الوكيل كما يلي:

```text
task: # Link shortener service (Python 3.13, standard library only)
model: qwen3:4b-instruct, mode: tools, budget: 20 steps, 2400 s
[1] list_files {} -> shortener/__init__.py  (1252 in / 44 out, 146 s)
[2] read_file {"path": "tests/test_smoke.py"} ->    1  # Smoke tests the team can run (the full acceptance tests are hidden).  (1327 in / 68 out, 57 s)
[3] search {"pattern": "encode\\(\\d+\\)"} -> tests/test_smoke.py:25: self.assertEqual(encode(1), "1")  (1856 in / 48 out, 84 s)
[4] read_file {"path": "shortener/codes.py"} -> ERROR: [Errno 2] No such file or directory: '/work/shortener/codes.py'  (1935 in / 139 out, 146 s)
[5] write_file {"path": "shortener/codes.py", "content": "def encode(n: int) -> str:\\n    \"\"\"En..."} -> wrote 349 chars to shortener/codes.py  (2109 in / 250 out, 341 s)
[6] run_tests {} -> FAILED (exit 1)  (2385 in / 64 out, 81 s)
[7] replace {"path": "shortener/codes.py", "old": "def encode(n: int) -> str:\\n    \"\"\"En...", "new": "def encode(n: int) -> str:\\n    \"\"\"En..."} -> replaced 349 chars with 349 chars in shortener/codes.py  (2785 in / 352 out, 351 s)
[8] write_file {"path": "shortener/codes.py", "content": "def encode(n: int) -> str:\\n    \"\"\"En..."} -> wrote 349 chars to shortener/codes.py  (3169 in / 217 out, 231 s)
[9] write_file {"path": "shortener/codes.py", "content": "def encode(n: int) -> str:\\n    \"\"\"En..."} -> wrote 349 chars to shortener/codes.py  (3429 in / 212 out, 290 s)
stop: stuck (same call, same result, 3 times) | steps 9 | 1727 s | tokens in 20247, out 1394
```

في المخرج أعلاه لاحظ التالي:

- الوكيل بدأ بداية صحيحة: عرض الملفات، ثم قرأ اختبارات الدخان، ثم بحث عن `encode(1)` ليعرف المطلوب، ثم قرر أن يبدأ بملف الرموز، وهو الترتيب من الأسفل للأعلى الذي اقترحناه قبل قليل.
- ولكن الملف الذي كتبه في الخطوة الخامسة كان سطراً واحداً، لأن النموذج أرسل محتوى الملف بأسطر مكتوبة كالرمزين `\n` بدل أسطر حقيقية، أي أنه هرب فواصل الأسطر مرتين داخل JSON. فالملف كود Python غير صالح، والاختبارات لا تستطيع حتى أن تستورده.
- ثم حاول الإصلاح ثلاث مرات بالمحتوى نفسه والطريقة نفسها، حتى أوقفه كشف التكرار في الخطوة التاسعة بعد 29 دقيقة و20 ألف توكن داخل، ولم يصل أبداً إلى ملف التخزين أو التطبيق.

فالوكيل الواحد هنا لم يكن أفضل من الفريق، بل توقف في أول ملف بسبب مشكلة في شكل المعاملات لا علاقة لها بفهم المهمة، وهي مشكلة كانت أداة الكتابة تستطيع أن تكشفها، مثل أن ترفض ملف Python لا يمر بالتحليل `ast.parse` وتقول للنموذج السبب. أما الفريق فكتب الملفات الثلاثة، ولكن كل ملف بطريقته. والدرس المشترك أن النموذج الصغير يفشل في التفاصيل الآلية قبل أن يصل إلى أي قرار تصميم، وأن بيئة التشغيل، سواء كانت وكيلاً أو فريقاً، هي المكان الذي تصلح فيه هذه التفاصيل.

والشكل التالي يضع التوكنات الداخلة في التشغيلات الثلاثة جنباً إلى جنب:

![ثلاثة أشرطة أفقية: فريق بعقد المخطط 24,553 توكن منها 16,290 للمبرمجين و7,704 للمراجع و559 للمخطط، وفريق بعقد الإنسان 26,178 منها 19,045 للمبرمجين و7,133 للمراجع، ووكيل واحد 20,247، والنتيجة في الثلاثة لا منصة تعمل](https://arabroot.io/content/images/2026/11/agent-team-builds-platform-04-roles.webp)

الفريق والوكيل الواحد استهلكا عشرين إلى ستة وعشرين ألف توكن داخل، ولم تعمل المنصة في أي منها.

## ما الذي نجح، وما الذي فشل؟

من السهل أن تقرأ النتيجة النهائية، أي منصة لا تعمل في التشغيلين، وتقول إن الفكرة كلها فاشلة. ولكن التجربة فيها أجزاء عملت كما يجب، وهي التي تستحق أن تأخذها إلى عملك:

**ما الذي نجح:**

- **العقد بصيغة منظمة:** المخطط أرجع JSON صالحاً من أول مرة بفضل المخطط في الحقل `format`، وتواقيعه كانت صحيحة.
- **المراجع كشف الأخطاء الواضحة:** لاحظ Flask وbase62 والدالة غير المعرفة، وكتب لكل منها في التشغيل الأول ملاحظة صحيحة إلى صاحب الملف الصحيح.
- **العقد الدقيق أصلح الملف المستقل:** ملف الرموز نجح في اختبارات القبول كاملة عندما كتب العقد ترتيب الحروف ومثالين.
- **اختبارات القبول المخفية والتسجيل:** كل ما في هذا المقال من أرقام جاء من سجل الاستدعاءات والاختبارات التي لم يرها الفريق، ولولاها لما عرفنا أن ملف الرموز صحيح في الثاني وخاطئ في الأول.

**ما الذي فشل:**

- **اتباع القواعد:** «المكتبة القياسية فقط» مكتوبة في المواصفة والعقد، وخالفها مبرمج `app.py` في التشغيلين بالطريقة نفسها: Flask ثم مكتبة وهمية.
- **احترام العقد بين الملفات:** العقد يقول إن ملف التخزين يستعمل `encode` من ملف الرموز، والمبرمج كتب نسخته الخاصة في التشغيلين، ومبرمج التطبيق نسخ الكلاس `LinkStore` كاملاً إلى ملفه.
- **توجيه الملاحظة إلى صاحبها:** المراجع أرسل ملاحظة `encode` إلى ملف التخزين في الأول، وأمر ملف الرموز بحذف دالته الصحيحة في الثاني.
- **الأمان:** `eval` على جسم الطلب في التشغيل الأول لم يذكره أحد.
- **التكامل:** طبقة HTTP لم تصل في أي جولة إلى تطبيق WSGI كما تطلب المواصفة، فلم ينجح أي اختبار من اختبارات الواجهة.

وهذه النتيجة تتفق مع ما قالته الأبحاث التي ذكرناها في [مقال تعدد الوكلاء](https://arabroot.io/articles/%D8%AA%D8%B9%D8%AF%D8%AF-%D8%A7%D9%84%D9%88%D9%83%D9%84%D8%A7%D8%A1-multi-agent-%D8%A7%D9%84%D9%85%D8%AE%D8%B7%D8%B7-%D9%88%D8%A7%D9%84%D9%85%D9%86%D9%81%D8%B0-%D9%88%D8%A7%D9%84%D9%85%D8%B1%D8%A7%D8%AC%D8%B9/) عن فشل الأنظمة متعددة الوكلاء: أغلب الفشل في التنسيق بين الأدوار وفي التحقق، وليس في قدرة كل وكيل على كتابة كود وحده. فكل ملف هنا كود Python صالح، وبعضه صحيح، والمنصة لا تعمل لأن الأجزاء لم تلتق.

## لماذا أخطأ المراجع في توجيه الملاحظات؟

المراجع في هذه التجربة يرى ثلاثة أشياء: العقد، ومخرج الاختبارات، والملفات الثلاثة كاملة، ويقرر أي ملف يجب أن يتغير. وفي التشغيلين أرسل ملاحظات إلى الملف الخطأ، والسبب يظهر إذا نظرت إلى ما رآه في الجولة الثالثة من التشغيل الأول: الاختبار يقول `'b' != '1'` عند استدعاء `encode(1)`، وفي المستودع دالتان باسم `encode`، واحدة في ملف الرموز وواحدة داخل الكلاس في ملف التخزين، والاختبار يستورد الأولى. فاختار المراجع الثانية، وربما لأن ملف التخزين كان أطول وفيه أخطاء أخرى ظاهرة.

وهذا ليس خطأ النموذج وحده، وإنما خطأ في المعلومات التي أعطيناها له، فمخرج الاختبار فيه اسم الاختبار ولكن ليس فيه الملف الذي استورد منه الدالة، والمراجع يخمن. وهناك ثلاثة تغييرات بسيطة كانت ستساعده:

1. **اختبار لكل ملف:** بدل اختباري دخان يلمسان الطبقات كلها، اختبار صغير لكل ملف باسمه، فيعرف المراجع من اسم الاختبار الفاشل صاحب الخطأ.
2. **سطر الاستيراد في مخرج الخطأ:** أداة صغيرة في المختبر تضيف إلى كل فشل الملف الذي جاءت منه الدالة، وهو شيء يعرفه Python بالخاصية `__module__`.
3. **منع التكرار آلياً:** فحص قبل كل جولة يرفض أي ملف يعرف دالة أو كلاساً موجوداً في العقد لملف آخر، وهذا كان سيوقف `encode` المكررة و`LinkStore` المنسوخة إلى ملف التطبيق من الجولة الأولى.

![ثلاثة صناديق للملفات: codes.py فيه encode بحروف مرتبة خطأ، وstore.py فيه encode ثانية داخل الكلاس، والاختبار test_encode يستورد الأولى ويفشل بالرسالة b لا تساوي 1، وسهم الملاحظة من المراجع يذهب إلى store.py بدل codes.py](https://arabroot.io/content/images/2026/11/agent-team-builds-platform-05-reviewer.webp)

دالتان بالاسم نفسه، والاختبار يستورد واحدة، والملاحظة ذهبت إلى الأخرى.

ولاحظ أن الأشياء الثلاثة كود عادي في بيئة التشغيل، وليست تعليمات إضافية للنموذج، وهذا تكرار للدرس نفسه في مقال بناء الوكيل: ما تستطيع أن تفحصه بالكود لا تتركه لتقدير النموذج.

## كيف تستفيد من الفكرة في عمل حقيقي؟

التجربة صغيرة ونماذجها صغيرة، ولكن ما حدث فيها يتكرر بأشكال أخرى مع النماذج الكبيرة، لأن أسبابه في طريقة تقسيم العمل وليس في حجم النموذج. وإذا أردت أن تستعمل فريق وكلاء في مشروع حقيقي، فهذه الطريقة التي نقترحها بعد التجربة:

1. **اكتب أنت العقد، أو راجعه سطراً سطراً.** العقد هو الشيء الوحيد الذي يراه كل المبرمجين، وكل خطأ فيه يتكرر في كل الملفات. وفي فريق بشري يأخذ هذا ساعة من مهندس خبير، وهي أرخص ساعة في المشروع كله.
2. **اجعل اختبارات الدخان أقرب إلى القبول.** اختباران فقط لم يكشفا ترتيب الحروف ولا قراءة جسم الطلب ولا `eval`. وكلما كانت الاختبارات التي يراها الفريق أدق، كان المراجع أدق، لأنه لا يرى إلا ما تكشفه الاختبارات.
3. **ابدأ بالطبقة التي لا تعتمد على غيرها.** في التجربة كتب المبرمجون الثلاثة ملفاتهم في الجولة نفسها، فبنى مبرمج التطبيق على ملف تخزين لم يكتمل. والترتيب الأفضل أن يكتب `codes.py` ويختبر، ثم `store.py` فوقه، ثم `app.py`، أي ما يسميه الناس التطوير من الأسفل للأعلى Bottom-up، وهو أبطأ قليلاً ولكنه يكشف الخطأ في مكانه.
4. **ضع البوابات الآلية بعد كل جولة.** أداة Ruff كانت ستكشف `json` غير المستورد، وأداة Bandit كانت ستكشف `eval`، وفحص الاعتماديات كان سيرفض `flask` و`base62` قبل أن يصلا إلى المراجع.
5. **قارن بوكيل واحد قبل أن تقرر.** فريق من ثلاثة مبرمجين ومراجع استهلك في تجربتنا 12 استدعاء و24 ألف توكن داخل، ووكيل واحد بمواصفة كاملة واختبارات قد يحتاج أقل، وقد رأينا في مقال تكلفة تعدد الوكلاء أن الفريق أغلى في أغلب الحالات.

والقاعدة العامة أن فريق الوكلاء يقسم العمل، ولكنه لا يقسم الفهم، فالفهم يأتي من العقد والمواصفة والاختبارات، وكلها عمل إنسان في هذا المستوى من النماذج.

## وهل كان نموذج أكبر سيغير النتيجة؟

غالباً نعم في النتيجة، ولا في أنواع الأخطاء. فالنماذج الأكبر تتبع قاعدة «المكتبة القياسية فقط» أكثر، وتكتب WSGI صحيحاً من أول مرة في الغالب، ولن تهرب فواصل الأسطر مرتين، فالأرجح أن تعمل المنصة بعد جولة أو جولتين. ولكن الأخطاء التي رأيناها هنا هي نفسها التي تصفها الأبحاث عن الأنظمة متعددة الوكلاء بنماذج كبيرة: ملف يتجاهل ما اتفق عليه في العقد، ومراجع يتحقق تحققاً ناقصاً، وكود يكرر ما كتبه وكيل آخر، وثغرة لا تكشفها الاختبارات. والفرق أن هذه الأخطاء تصبح أندر، فتصبح أخطر، لأن المراجع البشري يعتاد على أن الفريق ينجح فيقل انتباهه.

ولهذا فالتجربة بنموذج صغير مفيدة بالذات: هي تكبر الأخطاء حتى تراها في كل جولة، فتعرف أين تضع الفحوصات قبل أن تشغل الفريق نفسه بنموذج أكبر على مشروع حقيقي. وما يجب أن تقيسه عندها هو ما قسناه هنا: الاستدعاءات، والتوكنات، ونتيجة اختبارات القبول لكل ملف، ومقارنة بوكيل واحد على المهمة نفسها.

## لماذا يقرر العقد مصير الفريق؟

في فريق من البشر، المبرمج الذي يكتب طبقة HTTP يسأل زميله الذي يكتب التخزين: هل ترجع `get` القيمة `None` أم ترفع خطأ عندما لا تجد الرمز؟ ويحصل على الجواب في دقيقة، ويعدل كوده. أما في فريق الوكلاء فلا يوجد هذا السؤال، فكل مبرمج يكتب ملفه وحده من العقد والمواصفة، ثم يلتقي الكود لأول مرة عند تشغيل الاختبارات. ولذلك فإن كل قرار لم يكتب في العقد سوف يقرره كل مبرمج بطريقته، وكل قرارين مختلفين على طرفي سهم واحد خطأ تكامل Integration Bug لا يظهر في أي ملف وحده.

وهذه ليست مشكلة خاصة بالوكلاء، فهي المشكلة نفسها التي تحلها الفرق الكبيرة بالتصميم من العقد أولاً Contract-first Design، أي أن تتفق الفرق على الواجهة قبل أن يكتب أي فريق سطراً، ثم تفحص كل خدمة مقابل العقد آلياً، كما شرحنا في [مقال اختبار العقود](https://arabroot.io/articles/%D8%A7%D8%AE%D8%AA%D8%A8%D8%A7%D8%B1-%D8%A7%D9%84%D8%B9%D9%82%D9%88%D8%AF-contract-testing-%D9%85%D8%B9-pact/). والفرق مع الوكلاء أن المبرمج لا يستطيع أن يسأل، وأن المخطط الذي يكتب العقد نموذج يختصر كما رأينا، فالعقد الجيد هنا يجب أن يكون أدق مما يكتبه فريق بشري، لأنه البديل الوحيد عن كل الأسئلة التي لن تسأل.

والعقد الجيد للمهمة نفسها يجيب عن أربعة أنواع من الأسئلة:

- **الأسماء والتواقيع:** اسم كل دالة وكلاس، والمعاملات بأنواعها، وقيمة الرجوع بنوعها.
- **الحالات الحدية:** ماذا ترجع الدالة أو ترفع عندما لا تجد شيئاً، أو عندما يكون المدخل خاطئاً.
- **من يملك أي قرار:** هل يتحقق التطبيق من صحة الرابط أم طبقة التخزين، ومن يحول رقم الصف إلى رمز.
- **أمثلة ملموسة:** مثل `encode(62) == '10'`، لأن المثال يقطع الاختلاف في الفهم أسرع من أي وصف.

## أخطاء شائعة

- **ترك العقد للمخطط وحده:** العقد هو أهم وثيقة في الفريق، لأن كل مبرمج يبني عليه، والخطأ فيه يتكرر في كل الملفات. اكتبه أنت، أو راجعه قبل أن يبدأ أي مبرمج.
- **الحكم باختبارات الدخان:** اختبار ينجح يقول إن المنصة تعمل، ولا يقول إنها تعمل كما تريد، فاحتفظ باختبارات قبول لا يراها الفريق.
- **مراجع يقرأ كل شيء:** المراجع الذي يرى الملفات كلها ومخرج الاختبارات في نافذة واحدة يبدأ بالتخمين، فأعطه الفشل وما يتعلق به فقط.
- **التوازي الذي لا يوفر شيئاً:** على نموذج محلي واحد، تشغيل المبرمجين معاً لا يوفر وقتاً، وإنما يلغي فائدة الذاكرة المؤقتة لكل محادثة.
- **إعادة كتابة الملف كاملاً في كل جولة:** المبرمج الذي يعيد كتابة ملفه من الصفر قد يصلح الخطأ ويفسد ما كان يعمل، فاطلب تعديلاً محدداً أو قارن قبل أن تقبل.
- **الاعتقاد بأن الفريق يرى ما لا يراه وكيل واحد:** كل الأدوار هنا تستعمل النموذجين نفسيهما، فما لا يعرفه النموذج لا يعرفه الفريق.

## قائمة تحقق Checklist قبل أن تعطي فريق وكلاء مشروعاً

- مواصفة مكتوبة فيها السلوك والحالات الحدية، لا جملة واحدة.
- عقد بين الملفات: أسماء الدوال، والأنواع، وقيم الرجوع، وما يحدث عند الخطأ، يراجعه إنسان.
- اختبارات دخان يشغلها الفريق، واختبارات قبول مخفية للحكم.
- حد للجولات، وحد للتوكنات، وتسجيل كل استدعاء بدوره.
- كل ملف له صاحب واحد، والمراجع يوجه الملاحظة لصاحب الملف.
- تقارن النتيجة بوكيل واحد على المهمة نفسها قبل أن تقرر أن الفريق أفضل.

## تدريب عملي

1. غير اختبار الدخان الثاني ليفحص أيضاً سطر `Content-Type`، وأعد التشغيل الأول، ولاحظ هل يصلح المراجع شيئاً جديداً.
2. أعط المراجع مخرج الاختبارات فقط دون الملفات، وقارن ملاحظاته.
3. أضف دوراً خامساً يكتب اختبارات الوحدة Unit Tests لكل ملف من العقد قبل أن يكتب المبرمج ملفه، كما في [مقال TDD مع الوكلاء](https://arabroot.io/articles/%D8%A7%D9%84%D8%AA%D8%B7%D9%88%D9%8A%D8%B1-%D8%A8%D8%A7%D9%84%D8%A7%D8%AE%D8%AA%D8%A8%D8%A7%D8%B1-%D8%A7%D9%88%D9%84%D8%A7-tdd-%D9%85%D8%B9-%D9%88%D9%83%D9%84%D8%A7%D8%A1-%D8%A7%D9%84%D8%A8%D8%B1%D9%85%D8%AC%D8%A9/).
4. أضف إلى أداة `write_file` في minicode فحصاً يرفض ملف Python لا يمر بالتحليل `ast.parse`، ويرجع للنموذج رقم السطر الخاطئ، ثم أعد تشغيل `single.sh` وقارن.

## الخلاصة

- فريق من مخطط وثلاثة مبرمجين ومراجع بنموذجين محليين بنى خدمة اختصار الروابط من مواصفة في ثلاث جولات، والنتيجة في التشغيلين منصة لا تعمل.
- بعقد المخطط نجح اختباران من 11 في القبول المخفي، في 12 استدعاء و24,553 توكن داخل وقرابة 52 دقيقة على المعالج.
- بعقد كتبه إنسان أصبح ملف الرموز صحيحاً بالكامل، ولكن ملف التطبيق لم يصل إلى `make_app`، فتوقفت اختبارات القبول كلها عند الاستيراد.
- مبرمج التطبيق كتب Flask ثم مكتبة وهمية اسمها base62 في التشغيلين، رغم القاعدة المكتوبة، وكتب في الأول `eval` على جسم الطلب.
- المراجع كشف الأخطاء الواضحة، ولكنه وجه بعض الملاحظات إلى الملف الخطأ، وأمر مرة بحذف دالة صحيحة.
- العقد يصلح الملف المستقل، أما الملفات التي تجمع الأجزاء فتحتاج ترتيباً من الأسفل للأعلى، وبوابات آلية بعد كل جولة، واختبارات دخان أقرب إلى القبول.
- فريق الوكلاء يقسم العمل ولا يقسم الفهم: المواصفة والعقد والاختبارات عمل إنسان في هذا المستوى من النماذج.

وفي المقالات القريبة من هذه المرحلة بإذن الله نبني الوكيل الواحد بأيدينا ونقيسه على مهام مخفية، وهو المقارنة التي يجب أن تبدأ بها قبل أي فريق:

[![](https://arabroot.io/content/images/2026/11/build-coding-agent-cover-cover.webp)دليلابن وكيل برمجة Coding Agent بيدك: الحلقة والأدواتنبني وكيل برمجة كاملاً في ملف Python واحد حول نموذج محلي، ونرى كيف أفشلته طريقة الرد وأداة التعديل وتعريف الانتهاء قبل أن نصلحها ونقيسه باختبارات مخفية.](https://arabroot.io/articles/%D8%A7%D8%A8%D9%86-%D9%88%D9%83%D9%8A%D9%84-%D8%A8%D8%B1%D9%85%D8%AC%D8%A9-coding-agent-%D8%A8%D9%8A%D8%AF%D9%83-%D8%A7%D9%84%D8%AD%D9%84%D9%82%D8%A9-%D9%88%D8%A7%D9%84%D8%A7%D8%AF%D9%88%D8%A7%D8%AA/)[![](https://arabroot.io/content/images/2026/11/evaluate-coding-agents-cover-cover.webp)دليلكيف تقيس وكيل البرمجة؟ SWE-bench ومهام فريقكما الذي تقيسه أرقام SWE-bench ولماذا توقفت OpenAI عن نشرها، وكيف تبني أداة قياس صغيرة من تذاكر فريقك باختبارات مخفية، مع تجربة حقيقية لإعدادين على 12 مهمة.](https://arabroot.io/articles/%D9%83%D9%8A%D9%81-%D8%AA%D9%82%D9%8A%D8%B3-%D9%88%D9%83%D9%8A%D9%84-%D8%A7%D9%84%D8%A8%D8%B1%D9%85%D8%AC%D8%A9-swe-bench-%D9%88%D9%85%D9%87%D8%A7%D9%85-%D9%81%D8%B1%D9%8A%D9%82%D9%83/)[![](https://arabroot.io/content/images/2026/11/agent-in-ci-cover-cover.webp)دليلوكيل في خط النشر CI: مراجعة وإصلاح تلقائي مع موافقة بشريةخط نشر على Gitea Actions يراجع فيه نموذج محلي كل طلب دمج دون أي سر، ولا يصلح الكود إلا بعد وسم يضيفه إنسان، ثم يفتح طلب دمج جديداً يراجعه إنسان، مع سجلات حقيقية للتجربة.](https://arabroot.io/articles/%D9%88%D9%83%D9%8A%D9%84-%D9%81%D9%8A-%D8%AE%D8%B7-%D8%A7%D9%84%D9%86%D8%B4%D8%B1-ci-%D9%85%D8%B1%D8%A7%D8%AC%D8%B9%D8%A9-%D9%88%D8%A7%D8%B5%D9%84%D8%A7%D8%AD-%D8%AA%D9%84%D9%82%D8%A7%D8%A6%D9%8A-%D9%85%D8%B9-%D9%85%D9%88%D8%A7%D9%81%D9%82%D8%A9-%D8%A8%D8%B4%D8%B1%D9%8A%D8%A9/)

## سجل التحديثات

- 21 نوفمبر 2026: كتابة المقال، وتشغيل التجربة على Ollama 0.40.13 بالنموذجين qwen3:4b-instruct وqwen2.5-coder:3b.