در یک مخزن، فایلی با 3000 خط دستورالعمل برای ایجنت کدنویسی وجود دارد. ایجنت تقریباً فقط به نیمی از آن عمل میکند. یکی از مهندسان میخواهد حجم آن را به یک صفحه کاهش دهد. مهندس دیگری میگوید تکتک خطوط این فایل حاصل یک حادثه (Incident) بودهاند و هیچچیز نباید حذف شود. این اختلاف را چطور حل میکنید؟
اول خودتان جواب بدهید، بعد پاسخ را باز کنید.
پاسخ کوتاه
هر دو تا حدی حق دارند؛ اما چارهی کار نه کوتاهتر کردن فایل، بلکه ایجاد مجموعهای از فایلهای لایهبندیشده است. یک مسیریاب ریشه (Root Router) با حجمی کمتر از حدود 50 خط نگه دارید که فقط شامل اشارهگرها و چند قانون سفتوسخت باشد. قوانین را به یک فایل قوانین با حجم یک صفحه نمایش بهازای هر دستهبندی منتقل کنید و جزئیات عمیقتر را هم به اسناد موضوعی ببرید تا ایجنت فقط زمانی که وظیفهای به آن موضوع مربوط شد، آنها را بارگذاری کند. با این کار همهی قوانین حفظ میشوند و ایجنت حداکثر با دو گام پرش به هر قانونی میرسد.
پاسخ کامل
چرا فایل طولانی شکست میخورد
مدل فایل را بارگذاری میکند، صفحهی اول را میخواند، بودجهی اتنشن (Attention) آن تمام میشود و در نهایت تنها به بخش کوچکی از آنچه گفته شده عمل میکند. شکست یک کتابچهی راهنمای طولانی دقیقاً به همان دلیلی رخ میدهد که یک سند آشناسازی سازمانی (Onboarding) 40 صفحهای شکست میخورد: خواننده یک بار نگاهی گذرا به آن میاندازد و دیگر هرگز به بخشی که واقعاً اهمیت داشت برنمیگردد. راهنماهای طولانی نادیده گرفته میشوند، اما مسیریابهای کوتاه دنبال میشوند.
سه لایه
| لایه | محل قرارگیری | زمان خواندهشدن | اندازه |
|---|---|---|---|
| مسیریاب | فایل دستورالعملهای ریشه | در هر نشست | کمتر از حدود 50 خط |
| قوانین | docs/agent-rules.md |
در هر نشست، هنگام راهاندازی | یک صفحه نمایش بهازای هر دستهبندی |
| اسناد موضوعی | docs/<topic>.md |
فقط زمانی که وظیفه با آن موضوع در ارتباط است | به هر میزان عمق که لازم باشد |
مسیریاب به فایل وضعیت (State File)، تابلوی تسکها (Task Board)، قوانین و دستور اعتبارسنجی اشاره میکند. همچنین به تمام اسناد موضوعی بر اساس مسیر فایل ارجاع میدهد، نه با توصیف متنی.
دو آزمون برای حفظ انضباط
- دسترسپذیری (Reachability): ایجنت حداکثر با دو گام پرش از مسیریاب به هر قانونی میرسد. اشارهگری که دیگر مقصد معتبری ندارد بدتر از قانونی است که اصلاً وجود ندارد؛ بنابراین وجود یک پیوند خراب در مسیریاب، بهخودیخود یک نقض قانون در زمان راهاندازی به شمار میآید.
- تازگی (Freshness): مسیریاب باید آنقدر کوتاه باشد که بازبین در هر Pull Request بتواند دوباره آن را بخواند. این تنها مانعی است که جلوی رشد دوبارهی آن و تبدیل شدنش به یک کتابچهی راهنما را میگیرد.
مواردی که هنگام پیراستن متن باید رد کنید
این درس به پادالگوهایی (Anti-patterns) اشاره میکند که ظاهری شبیه به پوشش کامل قوانین دارند. دستورالعملهای متناقض بدون هیچ هشداری ایجنت را از حالت سؤالپرسیدن به حدسزدن سوق میدهند؛ نتایج یک اندازهگیری نشان داد که نرخ حل مسئله با دستورالعملهای شفاف 48.8 درصد و با دستورالعملهای متناقض 28 درصد بوده است. یک قانون سبک کدنویسی بدون دستور بررسی ساختار (Lint)، به ایجنت اجازه میدهد انطباق را از خودش سرهم کند؛ بنابراین در کنار هر قانون سبک، دستور اجرایی آن را هم بیاورید. کار را با دستورها شروع کنید و با سبک کدنویسی پایان دهید. متن را برای ایجنت بنویسید نه برای خوانندهی انسانی؛ چرا که ایجاز و فشردگی، بافت (Context) را نجات میدهد.
فایلهای تودرتو
مخازن بزرگ برای هر زیربخش یک مسیریاب مجزا نگه میدارند. ابزارها از فایل در حال کار تا ریشه به عقب حرکت میکنند و هر مسیریابی را که بیابند به هم پیوند میزنند؛ بنابراین یک فایل در زیرپوشه، فایل ریشه را گسترش میدهد. یکی از مخازن بزرگ در این درس، 88 مورد از این فایلها دارد. اندازهگیریهای موجود در درس نشان میدهد که بهترین فایلها جهشی کیفی معادل ارتقای مدل ایجاد میکنند، و بدترین فایلها نتیجهای ضعیفتر از نداشتن هیچ فایلی به همراه دارند.
سؤالهای تکمیلی مصاحبهگر
- سطح 2: تیم میخواهد قانونی را به دلیل اهمیت بالایش در مسیریاب نگه دارد. آزمونِ سنجش تعلق آن به مسیریاب چیست؟ پاسخ مورد انتظار: مسیریاب فقط جای اشارهگرها و معدود قوانین سفتوسختی است که برای همهی نشستها صدق میکنند؛ هر قانونی که مربوط به نوع خاصی از وظیفه باشد باید به یک سند موضوعی برود.
- سطح 2: وقتی تیم از چند ایجنت کدنویسی مختلف استفاده میکند، چگونه یک منبع حقیقت واحد (Source of Truth) نگه میدارید؟ پاسخ مورد انتظار: یک فایل ریشه و ساخت پیوندهای نمادین (Symlink) با نامهایی که هر ابزار انتظار دارد؛ به این ترتیب همهی ابزارها همان متن یکسان را میخوانند.
- سطح 3: یک ابزار لینت برای میز کار (Workbench) چه مواردی را بررسی میکند؟ پاسخ مورد انتظار: اینکه حجم مسیریاب در محدودهی خطوط مجاز باشد، تمام مسیرهای مورد ارجاع واقعاً وجود داشته باشند، و هیچ دو قانونی با هم تداخل نداشته باشند.
- سطح 3: چرا در این درس، رتبهی یک پیوند خراب پایینتر از قانونی قرار گرفته که اصلاً نوشته نشده است؟ پاسخ مورد انتظار: ایجنت به مسیریاب اعتماد میکند، اشارهگر را دنبال میکند، چیزی نمییابد و طوری ادامه میدهد که انگار قانون وجود نداشته است؛ در حالی که نبودِ یک قانون دستکم وعدهی دروغین ایجاد نمیکند.
جوابهای اشتباهی که مصاحبهگرها زیاد میشنوند
- «فایل را به یک صفحه کاهش دهید و بقیه را پاک کنید.» این قوانین حاصل حوادث واقعی بودهاند و حذف آنها حوادث را تکرار میکند؛ پس بهجای حذف، آنها را لایهبندی کنید.
- «فایل طولانی را نگه دارید و به ایجنت بگویید همهی آن را بخواند.» مدل بودجهی اتنشن محدودی دارد و دستور خواندن همه چیز، تغییری در میزان عمل به آن ایجاد نمیکند.
- «فایل را در پرامپت سیستم قرار دهید تا همیشه در بافت حضور داشته باشد.» مشکل، حضور در بافت نیست؛ مشکل، عمل کردن به آن است. یک مسیریاب کوتاه همراه با اشارهگرها دنبال میشود، اما یک بلوک متنی بلند نادیده میماند.
کجای دوره آموزش داده میشود
درس میز کار حداقلی مسیریاب را به یکی از سه فایل اصلی تبدیل میکند، و درس محدودیتهای اجرایی لایهها و دو آزمون ارزیابی را ارائه میدهد.