دقّق فتوثيق المشاريع المكتوب بالذكاء الاصطناعي مع seiso

شنو كيدير seiso

seiso هو convention وlinter ديال Markdown مخصص لوثائق المشاريع اللي كيتكتبها الذكاء الاصطناعي وكيتقراوها الناس والوكلاء ديال البرمجة. كيساعد المستودعات يحافظو على وثائق منسجمة، سهلة الصيانة، وأسهل للاستعمال كسياق فالتغييرات الجاية.

الأداة كتفحص الوثائق على حساب convention مشتركة، بلا ما تفرض على كل مشروع يخترع القواعد ديالو الخاصة بالتوثيق. كل وثيقة كتصرّح بنوع، بحال howto أو reference أو adr، وكتحتوي غير على المحتوى المناسب لذاك النوع.

seiso كيشجع حتى على أن كل معلومة يكون عندها مصدر رسمي واحد. الصفحات الأخرى خاصها تربط بهاد المصدر بلا ما تعاود نفس المعلومة. هاد الشي كينقص التناقضات، خصوصا ملي التوثيق اللي كينتجو الذكاء الاصطناعي كينسخ لائحة ديال الحقول، ولا version، ولا status، ولا count فعدة ملفات.

المبادئ الأساسية ديال التوثيق

• كل وثيقة كتصرّح بنوع واحد وكتتبع الغرض ديال داك النوع. وثيقة how-to كتشرح الخطوات، بينما التبرير ديال التصميم كينتمي لـ ADR.
• كل معلومة عندها مصدر واحد. الوثائق الأخرى كترابط بالصفحة الرسمية بلا ما تعاود صياغتها.
• الصفحات اللي خاصها تبقى مدة طويلة كتفادى القيم اللي كتبدل بسرعة أكثر من الصفحة، بحال versions وstatus ديال النشر وcounts.
• الـ pointer كيحدد ملف ولا symbol ملي كتكون الجملة كتشير لتفصيل ملموس فالتنفيذ.
• التوثيق اللي سالا ما خاصوش يخاطب الشخص اللي طلبو ولا يحكي كيفاش تصاوبت الوثيقة.
• القرارات اللي ما كتقدرش الأداة تاخذها خاصها تتسجل مع السبب ديالها. والاستثناء بلا تفسير راه بحد ذاتو مخالفة.

seiso كيركز على هاد القواعد ديال التوثيق. ما كيحاولش يحدد واش النثر باين مكتوب بالآلة، وكيخلي التنسيق والإملاء لأدوات أخرى.

تثبيت seiso

اختار طريقة من طرق التثبيت المدعومة. حزم Rust وPython وnpm كتوفر نفس أداة سطر الأوامر.

cargo install seiso

uv tool install seiso
# ولا استعمل pipx:
pipx install seiso

npm install -g @scarletkc/seiso

حزمتا PyPI وnpm فيهما ملفات تنفيذية جاهزة لـ macOS على Apple silicon وIntel، وLinux x64 وarm64 مع glibc، وWindows x64. فالمنصات الأخرى، ومن بينها توزيعات Linux المبنية على musl بحال Alpine، ثبّت الأداة بـ Cargo. وحزمة PyPI تقدر حتى تبني من المصدر فهاد المنصات، بشرط يكون Rust toolchain متوفر.

إلا كنت خدام من checkout ديال المصدر، شغّل الأوامر عبر Cargo:

cargo run -- <command>

تهيئة مستودع

شغّل seiso من جذر المستودع. بدا وطلب منو ينشئ configuration أولية:

seiso init

هاد الأمر كيكتب ملف seiso.toml فجذر المستودع. الـ configuration اللي كتتولد فيها exclusions مقترحة وmappings ديال أنواع الوثائق. راجع هاد الاقتراحات قبل ما تعتمد على النتائج، حيث إن الـ mapping الأولي غير نقطة بداية للمستودع ديالك وماشي بديل على قرارات المشروع.

شغّل أول فحص

من بعد ما تراجع الـ configuration اللي تولدات، فحص المستودع:

seiso check

بشكل افتراضي، seiso check كيشغّل غير القواعد المستقرة. هاد القواعد دازت معايير الترقية ديال seiso ومقصود بها توفر الأساس الموثوق للمشروع.

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

استكشف القواعد وبنية الوثائق

استعمل أوامر القواعد باش تفهم شنو يقدر seiso يفحص:

seiso rule --all
seiso rule <CODE>

seiso rule --all كتسرد جميع القواعد وكتبيّن الحالة ديال كل وحدة. استعمل seiso rule <CODE> باش تشوف قاعدة معينة مع الأمثلة.

باش تفحص نموذج الوثائق ديال seiso بلا ما تشغّل القواعد، استعمل:

seiso parse

هاد الشي مفيد ملي كتتعلم كيفاش الأداة كتفسر وثيقة ولا كتقلب علاش الفحص عطى نتيجة معينة.

استعمل القواعد التجريبية بحذر

القواعد اللي مازال ما حققاتش معايير الترقية متوفرة كـ previews. القواعد التجريبية مازال غير مستقرة وقد تعطي false positives، وداكشي علاش ما كتكونش مفعلة فالفحص العادي.

جرّبها محليا باستعمال الخيار --preview:

seiso check --preview

القواعد التجريبية مفيدة باش تلقى بكري المشاكل المحتملة فالتوثيق، ولكن README كيوصي تبقى خارج CI gates حتى تولي مستقرة. workflow عملي هو تستعمل القواعد المستقرة فالفحوصات الإلزامية، والقواعد التجريبية للمراجعة المحلية الاختيارية.

دخل seiso فـ workflow ديال التوثيق

1. ثبّت seiso باستعمال Cargo أو uv أو pipx أو npm.
2. شغّل seiso init من جذر المستودع.
3. راجع exclusions المقترحة وmappings ديال الأنواع فـ seiso.toml.
4. شغّل seiso check وحلّ النتائج اللي تبلّغ عليها.
5. استعمل seiso rule --all وشرح القواعد الفردية ملي تحتاج تفهم تشخيصا معينا.
6. جرّب محليا seiso check --preview، ولكن تجنب تستعمل نتائج القواعد التجريبية كـ CI gates.

بالنسبة للـ workflows الكبيرة، توثيق seiso فيه إرشادات على configuration واختيار القواعد وصيغ المخرجات، وزيد عليها hooks ديال Claude Code وpre-commit وتكاملات CI.

إرشادات متقدمة

خلي المصادر ديال المعلومات رسمية

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

طابق أنواع الوثائق مع الغرض ديالها

استعمل howto للخطوات الإجرائية، وreference للمعلومات الواقعية اللي كاتبقى صالحة، وadr للتبرير اللي ورا اختيار تصميم معيّن. الفصل بين هاد الأغراض كيمنع الصفحة تولّي خليط من التعليمات، وبيانات مرجعية، وقرارات تاريخية.

سجّل الاستثناءات المبررة

بعض القرارات ديال المستودع كتحتاج للحكم وماشي لقاعدة آلية. ملي كتخلي استثناء، وثّق السبب ديالو. كيتعامل seiso مع الاستثناء اللي ما عندوش تفسير على أنه مشكل فالتوثيق، حيث المساهمين والوكلاء فالمستقبل ما يقدروش يعرفو واش كان مقصود.

رجع للاتفاقية ملي تكون القاعدة ما واضحةش

اتفاقية seiso كتحدد العقد ديال كل نوع ديال الوثائق، وشنو هو الدليل اللي يقدر التشخيص يدّعيه. استعملها مع نتيجة seiso rule <CODE> ملي تحتاج تفهم البنية المتوقعة ولا تقرر كيفاش تصلح الملاحظة.

الخلاصة

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