seiso yordamida AI yozgan loyiha hujjatlarini tekshirish

seiso nima qiladi

seiso — AI tomonidan yozilgan va odamlar hamda kodlash agentlari o‘qiydigan loyiha hujjatlari uchun Markdown konvensiyasi va linteridir. U repozitoriylarga hujjatlarni izchil, qo‘llab-quvvatlash oson va kelajakdagi o‘zgarishlar uchun kontekst sifatida foydalanishni qulay saqlashga yordam beradi.

Ushbu vosita har bir loyihadan hujjatlar uchun o‘z qoidalarini ishlab chiqishni talab qilish o‘rniga, hujjatlarni umumiy konvensiya asosida tekshiradi. Har bir hujjat howto, reference yoki adr kabi turini e’lon qiladi va faqat shu turga mos materialni o‘z ichiga oladi.

seiso shuningdek, har bir faktning bitta asosiy manbasi bo‘lishini rag‘batlantiradi. Boshqa sahifalar bir xil ma’lumotni takrorlash o‘rniga shu manbaga havola berishi kerak. Bu, ayniqsa, AI tomonidan yaratilgan hujjatlar maydonlar ro‘yxati, versiya, holat yoki miqdorni bir nechta faylga ko‘chirganida, qarama-qarshiliklarni kamaytiradi.

Hujjatlashtirishning asosiy tamoyillari

• Har bir hujjat bitta turini e’lon qiladi va shu turning maqsadiga amal qiladi. How-to qadamlarni tushuntiradi, dizayn asoslari esa ADRda bo‘lishi kerak.
• Har bir faktning bitta manzili bo‘ladi. Boshqa hujjatlar uni qayta bayon qilish o‘rniga asosiy sahifaga havola beradi.
• Uzoq muddat saqlanadigan sahifalarda sahifaning o‘zgarish tezligidan tezroq o‘zgaradigan qiymatlar, jumladan versiyalar, joylashtirish holati va miqdorlar bo‘lmasligi kerak.
• Gap aniq implementatsiya tafsilotiga murojaat qilganda, pointer fayl yoki belgini aniqlaydi.
• Tayyor hujjatlar uni so‘ragan shaxsga murojaat qilmasligi yoki hujjat qanday yaratilganini bayon qilmasligi kerak.
• Vosita aniqlay olmaydigan mulohazali qarorlar sabab bilan qayd etilishi kerak. Sababsiz istisnoning o‘zi qoidabuzarlik hisoblanadi.

seiso ushbu hujjatlashtirish qoidalariga e’tibor qaratadi. U matn mashina tomonidan yozilgandek tuyuladimi-yo‘qmi, aniqlashga urinmaydi va formatlash hamda imloni boshqa vositalarga qoldiradi.

seiso’ni o‘rnatish

Qo‘llab-quvvatlanadigan o‘rnatish usullaridan birini tanlang. Rust, Python va npm paketlari bir xil buyruq qatori vositasini taqdim etadi.

cargo install seiso

uv tool install seiso
# Yoki pipx’dan foydalaning:
pipx install seiso

npm install -g @scarletkc/seiso

PyPI va npm paketlari Apple silicon va Intel protsessorli macOS, glibc’li Linux x64 va arm64 hamda Windows x64 uchun oldindan tuzilgan binar fayllarni o‘z ichiga oladi. Boshqa platformalarda, jumladan Alpine kabi musl asosidagi Linux distributivlarida, Cargo orqali o‘rnating. Ushbu platformalarda PyPI paketi ham Rust toolchain mavjud bo‘lsa, manba koddan tuzilishi mumkin.

Agar manba kod checkout’i bilan ishlayotgan bo‘lsangiz, buyruqlarni Cargo orqali ishga tushiring:

cargo run -- <command>

Repozitoriyni ishga tushirish

seiso’ni repozitoriy ildizidan ishga tushiring. Avval undan dastlabki konfiguratsiyani yaratishni so‘rang:

seiso init

Bu repozitoriy ildizida seiso.toml faylini yozadi. Yaratilgan konfiguratsiya tavsiya etilgan istisnolar va hujjat turlari mosliklarini o‘z ichiga oladi. Natijalarga tayanishdan oldin bu tavsiyalarni ko‘rib chiqing, chunki dastlabki moslik repozitoriyingiz uchun boshlang‘ich nuqta bo‘lib, loyiha qarorlarining o‘rnini bosa olmaydi.

Birinchi tekshiruvni ishga tushirish

Yaratilgan konfiguratsiyani ko‘rib chiqqach, repozitoriyni tekshiring:

seiso check

Odatiy holatda seiso check faqat barqaror qoidalarni ishga tushiradi. Bu qoidalar seiso’ning joriy etish mezonlariga javob bergan va loyiha uchun ishonchli asosni taqdim etishga mo‘ljallangan.

Diagnostika muammo qayerda yuz berganini ko‘rsatadi va uni qanday tuzatishni tushuntiradi. Shu sababli ko‘plab topilmalarni bevosita buyruq chiqishidan tuzatish mumkin. Topilma inson mulohazasini talab qilganda, masalan, ikki sahifadan qaysi biri faktning asosiy manbasi bo‘lishini tanlashda, diagnostika qabul qilinishi kerak bo‘lgan qarorni ko‘rsatadi.

Qoidalar va hujjat tuzilmasini o‘rganish

seiso nimalarni tekshira olishini tushunish uchun qoidalar buyruqlaridan foydalaning:

seiso rule --all
seiso rule <CODE>

seiso rule --all barcha qoidalarni ro‘yxatlaydi va ularning holatini ko‘rsatadi. Alohida qoidani misollar bilan ko‘rish uchun seiso rule <CODE> buyrug‘idan foydalaning.

Qoidalarni ishga tushirmasdan seiso’ning hujjat modelini tekshirish uchun quyidagidan foydalaning:

seiso parse

Bu vosita hujjatni qanday talqin qilishini o‘rganayotganingizda yoki tekshiruv nima sababdan muayyan natija berganini aniqlayotganingizda foydalidir.

Ko‘rib chiqish qoidalaridan ehtiyotkorlik bilan foydalaning

Joriy etish mezonlariga hali javob bermagan qoidalar ko‘rib chiqish sifatida mavjud. Ko‘rib chiqish qoidalari tajribaviy bo‘lib, noto‘g‘ri ijobiy natijalar berishi mumkin, shuning uchun ular standart tekshiruvda yoqilmagan.

Ularni --preview opsiyasi bilan mahalliy tarzda sinab ko‘ring:

seiso check --preview

Ko‘rib chiqish qoidalari mumkin bo‘lgan hujjatlashtirish muammolarini erta aniqlash uchun foydali, biroq README ularni barqaror bo‘lmaguncha CI nazoratlaridan tashqarida saqlashni tavsiya qiladi. Amaliy ish jarayoni majburiy tekshiruvlar uchun barqaror qoidalardan, ixtiyoriy mahalliy ko‘rib chiqish uchun esa ko‘rib chiqish qoidalaridan foydalanishdan iborat.

seiso’ni hujjatlashtirish ish jarayoniga joriy etish

1. seiso’ni Cargo, uv, pipx yoki npm orqali o‘rnating.
2. Repozitoriy ildizidan seiso init buyrug‘ini ishga tushiring.
3. seiso.toml faylidagi tavsiya etilgan istisnolar va tur mosliklarini ko‘rib chiqing.
4. seiso check buyrug‘ini ishga tushiring va bildirilgan topilmalarni bartaraf eting.
5. Diagnostikani tushunish kerak bo‘lganda seiso rule --all va alohida qoidalar izohlaridan foydalaning.
6. seiso check --preview buyrug‘i bilan mahalliy tarzda tajriba qiling, ammo ko‘rib chiqish topilmalaridan CI nazorati sifatida foydalanmang.

Kengroq ish jarayonlari uchun seiso hujjatlarida konfiguratsiya, qoidalarni tanlash va chiqish formatlari, shuningdek Claude Code hook’lari, pre-commit va CI integratsiyalari bo‘yicha yo‘riqnoma mavjud.

Ilg‘or yo‘riqnoma

Faktlarni asosiy manbada saqlang

seiso takrorlangan yoki noto‘g‘ri joylashtirilgan ma’lumotlar haqida xabar berganda, fakt qaysi hujjatga tegishli bo‘lishi kerakligini aniqlang. Asosiy tushuntirishni shu hujjatga ko‘chiring va unga bog‘liq sahifalardan havola bering. Bu yangilanishlarni xavfsizroq qiladi hamda o‘quvchilar va agentlarga yagona ishonchli manbani aniq ko‘rsatadi.

Hujjat turlarini maqsadga moslang

Jarayon bosqichlari uchun howto, barqaror faktik ma’lumotlar uchun reference, dizayn tanlovi ortidagi mulohazalar uchun esa adr dan foydalaning. Bu maqsadlarni alohida saqlash sahifaning yo‘riqnomalar, ma’lumotnoma va tarixiy qarorlar aralashmasiga aylanishining oldini oladi.

Asoslangan istisnolarni qayd eting

Ayrim repository qarorlari mexanik qoida emas, mulohazani talab qiladi. Istisnoni saqlab qolsangiz, sababini hujjatlashtiring. seiso izohsiz istisnoni hujjatlashtirish muammosi deb hisoblaydi, chunki kelajakdagi hissa qo‘shuvchilar va agentlar bu ataylab qilingan-qilinmaganini aniqlay olmaydi.

Qoida noaniq bo‘lsa, konvensiyaga murojaat qiling

seiso konvensiyasi har bir hujjat turining shartlarini va diagnostika da’vo qilishi mumkin bo‘lgan dalillarni belgilaydi. Kutilayotgan tuzilmani tushunish yoki topilmani qanday tuzatishni hal qilish kerak bo‘lganda, undan seiso rule <CODE> chiqishi bilan birga foydalaning.

Xulosa

seiso loyiha hujjatlariga umumiy tuzilma va yo‘naltirilgan tekshiruv vositasini beradi. Uni o‘rnating, seiso.toml faylini yarating va ko‘rib chiqing, barqaror tekshiruvlarni ishga tushiring hamda hujjatlarni insonlar va kodlash agentlari uchun ishonchliroq qilish maqsadida qoidalar izohlaridan foydalaning. Preview qoidalari targ‘ib qilinmaguncha ularni tajribaviy deb hisoblang va egalik hamda istisnolar haqidagi qarorlarni repositoryda aniq qayd eting.