17. פרויקט גמר: סוכן סקירת קוד

הבעיה

במשך 16 שיעורים למדת רכיבים בודדים: לולאות, כלים, תכנון, תת-סוכנים, מיומנויות, דחיסה, משימות, עבודה ברקע, צוותים, פרוטוקולים, אוטונומיה, worktrees, הערכות, מגבלות בטיחות, ניטור ופריסה לייצור. כל אחד עובד בנפרד. אבל מערכות אמיתיות משלבות את כולם.

פרויקט הגמר הזה קושר כל מושג יחד למערכת אחת ברמת ייצור: בוט סקירת קוד מרובה-סוכנים.

הארכיטקטורה

                         PR Diff
                            │
                     ┌──────▼──────┐
                     │  Lead Agent  │─────── Task Board
                     │   (s01)      │         (s07)
                     └──────┬──────┘
                            │ plan + delegate
              ┌─────────────┼─────────────┐
              ▼             ▼             ▼
     ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
     │   Security   │ │ Performance  │ │    Style     │
     │  Reviewer    │ │  Reviewer    │ │  Reviewer    │
     │   (s09)      │ │   (s09)      │ │   (s09)      │
     └──────┬───────┘ └──────┬───────┘ └──────┬───────┘
            │                │                │
     ┌──────▼───────┐ ┌──────▼───────┐ ┌──────▼───────┐
     │  worktree/   │ │  worktree/   │ │  worktree/   │
     │  security    │ │  performance │ │  style       │
     │   (s12)      │ │   (s12)      │ │   (s12)      │
     └──────┬───────┘ └──────┬───────┘ └──────┬───────┘
            │                │                │
            └────────────────┼────────────────┘
                             │ findings via mailbox (s10)
                     ┌───────▼───────┐
                     │  Synthesize   │
                     │   (s04)       │
                     └───────┬───────┘
                             │
                     ┌───────▼───────┐
                     │ Review Summary│
                     └───────────────┘

כל תיבה ממופה לשיעור שהשלמת. זה לא מושג חדש — זו ההרכבה של כל מה שלמדת.

שלב 1: תכנון הסקירה

הסוכן הראשי מקבל diff ומפרק אותו לחלקים הניתנים לסקירה:

def plan_review(diff: str) -> list[dict]:
    """Use the LLM to analyze a diff and create review tasks."""
    prompt = f"""Analyze this diff and create review tasks.
For each concern, create a task with:
- title: what to check
- category: security | performance | style
- files: which files are relevant

Diff:
{diff}"""

    messages = [{"role": "user", "content": prompt}]
    response = agent_loop(messages)
    tasks = parse_tasks(response)

    # Create tasks in the task system (s07)
    for task in tasks:
        task_manager.create(
            title=task["title"],
            category=task["category"],
            files=task["files"],
            status="pending",
        )
    return tasks

זה משתמש בגישת TodoWrite לתכנון ובמערכת המשימות לאחסון מתמיד. משימות שורדות קריסות כי הן קובצי JSON על הדיסק.

שלב 2: הרכבת הצוות

def setup_review_team():
    """Initialize specialist agents with domain-specific prompts."""
    teammates = [
        {
            "name": "security",
            "role": "security reviewer",
            "system": (
                "You are a security reviewer. Look for: "
                "SQL injection, XSS, path traversal, auth bypass, "
                "hardcoded secrets, insecure deserialization. "
                "Rate each finding: critical / high / medium / low."
            ),
        },
        {
            "name": "performance",
            "role": "performance reviewer",
            "system": (
                "You are a performance reviewer. Look for: "
                "N+1 queries, unnecessary allocations, missing indexes, "
                "O(n^2) algorithms, synchronous I/O in hot paths. "
                "Estimate impact: high / medium / low."
            ),
        },
        {
            "name": "style",
            "role": "style reviewer",
            "system": (
                "You are a style reviewer. Look for: "
                "inconsistent naming, missing type hints, dead code, "
                "overly complex functions, missing docstrings on public APIs. "
                "Suggest concrete fixes."
            ),
        },
    ]
    init_team(teammates)
    return teammates

לכל מומחה יש prompt מערכת ממוקד שקובע מה הוא מחפש. זו תבנית צוותי סוכנים עם זהות ומחזור חיים.

שלב 3: ביצוע מקבילי

def execute_review(tasks: list, team: list):
    """Assign worktrees and let agents work in parallel."""
    for task in task_manager.get_ready():
        # Each task gets its own git worktree (s12)
        wt = create_worktree(task["id"])
        task["worktree"] = wt
        task_manager.update(task)

    # Start teammate loops in threads (s09 + s11)
    threads = []
    for mate in team:
        t = threading.Thread(
            target=teammate_loop,
            args=(mate["name"], mate["role"]),
            daemon=True,
        )
        t.start()
        threads.append(t)

    # Autonomous agents claim ready tasks (s11)
    # Each runs in its assigned worktree
    wait_for_completion(task_manager, timeout=300)

    # Cleanup worktrees after completion
    for task in task_manager.get_all():
        if task.get("worktree"):
            cleanup_worktree(task["id"])

תבנית הסוכנים האוטונומיים מאפשרת למומחים לתבוע משימות באופן עצמאי. בידוד worktree מבטיח שהם לא יכולים להפריע אחד לשני.

שלב 4: איסוף ממצאים

def collect_findings(team: list) -> dict:
    """Drain all specialist mailboxes and aggregate findings."""
    findings = {"security": [], "performance": [], "style": []}

    for mate in team:
        messages = drain_inbox("lead")
        for msg in messages:
            if msg["from"] == mate["name"]:
                parsed = json.loads(msg["content"])
                findings[mate["name"]].extend(parsed["findings"])

    return findings

תבנית בקשה-תגובה של פרוטוקולי צוות מבטיחה שנוכל להתאים ממצאים למומחה הנכון.

שלב 5: סינתוז הסקירה

def synthesize_review(findings: dict) -> str:
    """Use a subagent to produce a coherent review summary."""
    all_findings = json.dumps(findings, indent=2)

    summary = run_subagent(f"""Synthesize these code review findings into a
structured review. Prioritize by severity. Group by category.

Findings:
{all_findings}

Output format:
## Critical Issues
## Recommendations
## Style Suggestions
""")
    return summary

תת-סוכן מסנתז את כל הממצאים לסיכום קוהרנטי. דחיסת הקשר מבטיחה שהסינתזה נשארת בגבולות ה-token גם בסקירות גדולות.

עטיפת ייצור

פרויקט הגמר משלב את כל דרישות הייצור:

def run_code_review(diff: str) -> str:
    """Full production code review pipeline."""
    tracer = AgentTracer("code-review")    # s15: observability
    guardrail = GuardRail(PERMISSIONS)      # s14: safety

    tracer.record("review_start", {"diff_size": len(diff)})

    tasks = plan_review(diff)               # s03 + s07: planning
    team = setup_review_team()              # s09: team setup
    execute_review(tasks, team)             # s11 + s12: parallel work
    findings = collect_findings(team)       # s10: coordination
    summary = synthesize_review(findings)   # s04 + s06: synthesis

    tracer.record("review_complete", {
        "findings": sum(len(v) for v in findings.values()),
        "total_tokens": tracer.total_tokens(),
    })

    return summary

מפת מושגי השיעורים

המסקנה המרכזית

הרתמה שלמה. מלולאת while True בודדת בשיעור 1, בנית מערכת שבה מספר סוכנים מתואמים באופן אוטונומי לביצוע עבודה מורכבת במקביל — עם בטיחות, ניטור ומוכנות לייצור מובנים. המודל הוא האינטליגנציה. הקוד הוא הרתמה. למדת לבנות את הרתמה.