مبتكر htmx يقترح معاملة ملفات Markdown كجزء من الكود المصدري لا كتوثيق
حين يكتب الـ agent الكود تضيع النية خلفه في جلسة انتهت، ووضع المواصفات بجانب الكود يحوّل سؤال أين المواصفات إلى سؤال في أي commit.
نشر Carson Gross، مبتكر مكتبة htmx، في 21 سبتمبر 2026 مقالًا بعنوان “Markdown in src”، وصل إلى الصفحة الأولى في lobste.rs. وفكرته الأساسية في جملة واحدة: ملفات Markdown أصبحت جزءًا من الكود المصدري، لا من التوثيق.
المشكلة التي ينطلق منها مألوفة في الفرق التي تعمل مع الـ agents. الـ agent يكتب الكود، أما النية التي تقف خلفه فتبقى في جلسة prompt انتهت ولم يُحفظ منها شيء. وبعد أشهر، يفتح أحدهم الملف ويسأل لماذا كُتب بهذه الطريقة، فلا يجد جوابًا.
والاقتراح عملي: مجلد داخل المستودع نفسه يضم المواصفات مكتوبة بصيغة Markdown. ملف README.md يعمل فهرسًا، وملف OVERVIEW.md يقدّم الصورة التقنية العامة، ومجلدات فرعية للميزات ونماذج البيانات والـ APIs والبنية التحتية.
الهدف ليس كتابة توثيق إضافي. الهدف أن تجلس هذه الملفات بجانب الكود، وأن تُراجَع معه في الـ pull request نفسه. وحين يُوجَّه agent إلى المستودع، يقرأ الملف نفسه الذي يقرؤه عضو جديد انضم إلى الفريق.
ويسمّي Gross المشكلة التي يعالجها هذا النهج “spooky specification at a distance”، أي المواصفات المتناثرة بعيدًا عن الكود: القرار في تذكرة، وشرحه في محادثة على Slack، وسببه في wiki لا يفتحها أحد. ثلاثة أماكن، لا يُراجَع أي منها مع الكود.
وتقترب الفكرة من معيار AGENTS.md، الذي باتت أدوات مثل Claude Code تقرؤه. والأثر المباشر لهذا النهج أنه يربط المواصفات بتاريخ الكود نفسه: كل تغيير في القرار يظهر في commit، ويمكن تتبعه ومراجعته كما يُراجَع أي سطر برمجي.