صفحه ۱۷ از ۴۹، پروژه‌های عملی
پروژه 01. فقط-پرامپت در برابر قانون-محور: چقدر تفاوت ایجاد می‌کند
در این صفحه
درس‌های مرتبط: درس 01. مدل‌های قوی به‌معنای اجرای قابل‌اعتماد نیستند · درس 02. هارنس در واقع چیست فایل‌های الگو: templates/
کاری که انجام می‌دهید#
یک پوسته برنامه کاربردی پایگاه دانش مینیمال با Electron بسازید — پنجره‌ای با فهرست اسناد در سمت چپ، پانل پرسش و پاسخ در سمت راست و یک دایرکتوری محلی برای داده‌ها. خود این وظیفه پیچیده نیست. آنچه پیچیده است نحوه هدایت ایجنت برای تکمیل آن است.
شما این کار را دو بار اجرا می‌کنید. بار اول: فقط یک پرامپت، بدون هیچ آماده‌سازی. بار دوم: هارنس مینیمال (مانند AGENTS.md، init.sh، feature_list.json) از قبل در مخزن قرار داده شده است. سپس مقایسه کنید.
سناریوی این دوره از یک بازه بازکشف/آماده‌سازی کوتاه به عنوان مثال استفاده می‌کند، نه یک نتیجه اندازه‌گیری‌شده ثابت.
استفاده از پروژه‌های موجود در مخزن#
مسیر مخزن: projects/project-01/
| دایرکتوری | شامل چه مواردی است | نحوه استفاده از آن |
|---|---|---|
starter/ |
اجرای هارنس ضعیف. این بخش تنها task-prompt.md را به عنوان شرح وظیفه دارد و فاقد AGENTS.md یا feature_list.json است. توجه: starter/ همچنین شامل یک پیاده‌سازی مرجع از برنامه است — سورس برنامه (src/، package.json، پیکربندی‌ها، scripts/) را قبل از اجرا حذف کنید تا ایجنت آن را از صفر بسازد. اسناد نمونه در data/ به انتخاب شماست: آن‌ها را در هر دو اجرا نگه دارید یا از هر دو حذف کنید تا تقارن دو اجرا حفظ شود. |
پرامپت را به ایجنت کدنویس خود بدهید و آنچه را که بدون ساختار اضافی تکمیل می‌کند بسنجید. |
solution/ |
همان برش محصول همراه با مصنوعات صریح هارنس: AGENTS.md، CLAUDE.md، init.sh، feature_list.json، claude-progress.md، و docs/ (ARCHITECTURE.md، PRODUCT.md). |
مقایسه کنید که چگونه یک وظیفه یکسان از طریق قوانین و شواهد راستی‌آزمایی ملموس و عینی می‌شود. پیش از اجرای قوی، شواهد ثبت‌شده را بازنشانی کنید: وضعیت هر ویژگی در feature_list.json را روی not-started قرار دهید و مقادیر evidence/testedAt آن را پاک کنید (فیلدها را نگه دارید)، و گزارش نشست در claude-progress.md را پاک کنید (عنوان را نگه دارید)، در غیر این صورت ایجنت می‌بیند هر چهار ویژگی از قبل پاس شده‌اند و چیزی برای ساختن نخواهد داشت. |
چهار ویژگی ملموس عبارتند از باز شدن پنجره، فهرست اسناد، پانل سوالات، و ایجاد دایرکتوری داده محلی. فایل solution/feature_list.json را برای شواهد مورد انتظار هر ویژگی بررسی کنید.
ابزارها#
- Claude Code یا Codex (یکی را انتخاب کنید و برای هر دو اجرا از همان استفاده نمایید)
- دو دایرکتوری کاری ایزوله (یکی برای هر اجرا؛ هرگز هر دو به طور همزمان هنگام اجرای یک تست فعال نباشند)
- Node.js + Electron (پشته پروژه)
- یک تایمر (ثبت مدت زمان هر اجرا)
سازوکار هارنس#
هارنس مینیمال: AGENTS.md + init.sh + feature_list.json + CLAUDE.md + claude-progress.md + docs/
پروتکل اجرا#
آماده‌سازی#
- دو دایرکتوری کاری ایزوله آماده کنید، به عنوان مثال
p01-baseline/وp01-improved/. هر بار یکی را اجرا کنید: فایل‌ها را تنظیم کنید، اجرا کنید، نتایج را آرشیو کنید، دایرکتوری را حذف کنید، سپس دیگری را آغاز نمایید. - از شاخه‌های گیت برای تفکیک دو اجرا استفاده نکنید. یک ایجنت کدنویس دسترسی کامل به فایل‌سیستم دارد و دایرکتوری‌های همجوار و ارجاعات شاخه‌ها را کاوش خواهد کرد؛ اگر اجرای ضعیف بتواند فایل‌های هارنس قوی (
feature_list.json،claude-progress.md،docs/) را ببیند، آزمایش آلوده می‌شود. - پرامپت وظیفه یکسانی را برای هر دو اجرا آماده کنید، متنی برگرفته از
starter/task-prompt.md: «Build an Electron app that can show documents and answer questions.»
اجرای اول (هارنس ضعیف)#
در p01-baseline/، فقط پرامپت وظیفه را قرار دهید (بدون هیچ فایل هارنس).
- ایجنت را فقط با پرامپت بالا آغاز کنید.
- هیچ
AGENTS.md، هیچ اسکریپت راه‌اندازی (init script)، و هیچ معیار پذیرشی ارائه ندهید. - وقتی ایجنت متوقف شد، دستور
npm start(یا هر دستور راه‌اندازی که تولید کرده است) را اجرا کنید تا بررسی نمایید آیا برنامه اجرا می‌شود یا خیر. - ثبت کنید: خروجی ترمینال، تفاوت (diff) کلیدی کد، خلاصه نهایی ایجنت.
- کد را به صورت دستی دستکاری نکنید. اگر برنامه اجرا نشد، همان وضعیت را ثبت نمایید.
- نتایج را آرشیو کنید،
p01-baseline/را حذف کنید، سپس آزمون دوم را اجرا نمایید.
اجرای دوم (هارنس قوی)#
در p01-improved/، پیش از آغاز به کار ایجنت، موارد زیر را آماده کنید:
AGENTS.md: ساختار پروژه، دستورات راه‌اندازی، قوانین مرز لایه‌های ElectronCLAUDE.md: مرجع سریع برای ایجنت (دستورات بیلد/اجرا، فایل‌های کلیدی)init.sh: بررسی بیلد تمیز پروژه (npm install && npm run check && npm run build)feature_list.json: چهار ویژگی و وضعیت تکمیل آن‌هاclaude-progress.md: گزارش پیشرفت و شواهدdocs/: مشخصات معماری و محصول کهAGENTS.mdبه ایجنت می‌گوید ابتدا آن‌ها را بخواند (ARCHITECTURE.md،PRODUCT.md)
سپس شواهد ثبت‌شده را بازنشانی کنید: وضعیت هر ویژگی در feature_list.json را روی not-started قرار دهید و مقادیر evidence/testedAt آن را پاک کنید (فیلدها را نگه دارید)، و گزارش نشست در claude-progress.md را پاک کنید (عنوان را نگه دارید). ایجنت را با همان پرامپت اجرای اول آغاز کنید. وقتی متوقف شد، ./init.sh را اجرا کنید و نتیجه را ثبت نمایید.
نحوه اندازه‌گیری نتایج#
| سنجه | شرح |
|---|---|
| تکمیل | کامل / جزئی / ناموفق |
| اولین راه‌اندازی موفق | زمان از شروع تا اولین npm start موفق (یا دستور راه‌اندازی تولیدشده) |
| تلاش‌های مجدد | تعداد مداخله‌های انسانی لازم برای راه‌اندازی موفق |
| موارد جاافتاده | کدام ویژگی‌ها هنگام اعلام اتمام توسط ایجنت هنوز پیاده‌سازی نشده بودند |
| توقف زودهنگام | آیا ایجنت در حالی که برنامه هنوز اجرا نمی‌شد اعلام پایان کرد |
آنچه باید تحویل دهید#
- گزارش اجرای هارنس ضعیف: پرامپت، لاگ‌ها/رونوشت، diff نهایی، شواهد راه‌اندازی
- گزارش اجرای هارنس قوی: همان موارد، به همراه فایل‌های هارنسی که آماده کرده‌اید
- یک یادداشت مقایسه‌ای (1 تا 2 صفحه): تفاوت‌ها، داده‌ها، نتیجه‌گیری شما
چارچوب تجربی#
این یک آزمایش مقایسه‌ای است، نه الزامی برای اینکه هر دو اجرای ایجنت یک برنامه Electron آماده محیط عملیاتی تولید کنند. وظیفه یکسان را در برابر starter/ ضعیف و solution/ با هارنس صریح اجرا کنید، سپس ثبت کنید که هر اجرا کدام ویژگی‌ها را تکمیل می‌کند و چه شواهدی از نتیجه پشتیبانی می‌کند. خروجی جزئی یا ناقص شواهد تجربی معتبر است؛ فهرست ویژگی‌ها آنچه را که باید سنجیده شود تعریف می‌کند، نه الزامی مبنی بر اینکه اجرای فقط-پرامپت باید تمام موارد را پاس کند.