SpecGuard - AI coding से पहले spec की जांच करने वाला CLI/Codex plugin

 (github.com/KoreaNirsa)
7 पॉइंट द्वारा veltrix 6 일 전 | 1 टिप्पणियां | WhatsApp पर शेयर करें

नमस्ते। मैं SpecGuard नाम का एक open source टूल बना रहा हूँ।

Codex, Claude Code जैसे AI coding टूल इस्तेमाल करने पर implementation की speed वाकई तेज़ हो जाती है। लेकिन इसे कई बार इस्तेमाल करने के बाद मुझे जो समस्या बार-बार असल में मिली, वह “AI कोड नहीं लिख पाता” से ज़्यादा “AI को दिया गया spec ही अधूरा है” के करीब थी।

अगर spec में खामियां हों, तो AI उन खाली जगहों को अपने हिसाब से अनुमान लगाकर implement करता है। शुरुआत में यह ठीक-ठाक लगता है, लेकिन development आगे बढ़ने पर नीचे की समस्याएं बड़ी होने लगीं।

  • code की quality और structure धीरे-धीरे टूटने लगती है।
  • spec और code एक-दूसरे से मेल नहीं खाते।
  • बाद में यह अलग करना मुश्किल हो जाता है कि code गलत है, spec पुराना हो गया है, या शुरुआती requirement ही अस्पष्ट थी।

इसलिए मुझे लगा कि implementation के बाद सिर्फ code review काफ़ी नहीं है। defect वाला spec ज्यों का त्यों implementation agent तक पहुंचने से पहले, spec की कमियों को पहले उजागर करने वाला एक चरण ज़रूरी था।

SpecGuard इसी समस्या को कम करने के लिए बनाया गया एक CLI/Codex plugin है। यह code generation के बाद output की जांच करने वाला टूल नहीं है, बल्कि AI को implementation सौंपने से पहले spec की जांच करने वाला टूल है।

मैंने इसका जो basic flow सोचा है, वह इस तरह है।

  1. इंसान product spec लिखता है।
  2. SpecGuard से spec की जांच की जाती है।
  3. अगर NOT_READY हो तो spec को मज़बूत किया जाता है।
  4. READY हो जाए तो Codex/Claude Code जैसे implementation agent को सौंप दिया जाता है।

SpecGuard मुख्य रूप से इस तरह की कमियां ढूंढता है।

  • authentication/authorization boundary अस्पष्ट होना
  • tenant/user ownership scope का छूट जाना
  • idempotency, replay, race condition handling का न होना
  • expiry/revocation/state transition rules का अस्पष्ट होना
  • external side effects, webhook, background job retry policy का न होना
  • ऐसी requirements जो सिर्फ client-side validation पर भरोसा करती हों

नतीजे मुख्य रूप से तीन तरह के होते हैं।

  • READY: implementation agent को सौंपा जा सकता है
  • READY_WITH_WARNINGS: सौंपा जा सकता है, लेकिन कुछ सावधानियां हैं
  • NOT_READY: Critical/Major समस्याएं हैं, इसलिए spec को और मज़बूत करना ज़रूरी है

default path --no-llm heuristic जांच है। क्योंकि CI या PR Review में मेरे हिसाब से fast और reproducible results महत्वपूर्ण हैं। OpenAI Platform या Codex आधारित detailed review भी जोड़ा जा सकता है, लेकिन अभी इसे सिर्फ तब इस्तेमाल होने वाले auxiliary path के रूप में रखा है जब और गहराई से देखना हो।

v0.4.0 में जोड़ा गया

इस v0.4.0 में Codex app plugin MVP जोड़ा गया है।

pip install spec-guard  
specguard --help  
codex plugin marketplace add KoreaNirsa/spec-guard --ref main

Codex app में SpecGuard Plugins source चुनकर SpecGuard plugin install करने पर, आप Codex के भीतर SpecGuard चलाने का अनुरोध कर सकते हैं। उदाहरण के लिए sample spec बनाने के बाद

specguard example copy specs/your-feature-name --force

Codex में उस folder को खोलकर आप इस तरह अनुरोध कर सकते हैं।

1. @SpecGuard specs/your-feature-name पर SpecGuard चलाओ।  
2. @SpecGuard specs/your-feature-name spec package पर SpecGuard चलाओ, और READY/NOT_READY status तथा मुख्य findings का सार बताओ।  
3. @SpecGuard specs/your-feature-name पर SpecGuard चलाओ। default heuristic जांच से आगे बढ़ो, और result status तथा आगे क्या करना है उसका सार बताओ।

plugin SpecGuard engine को दोबारा implement नहीं करता। यह मौजूदा specguard CLI को call करता है, और generated results पढ़कर current status और next action का सार बताता है।

SpecGuard जब READY status बनाता है, तो implementation agent को सौंपे जा सकने वाला handoff document बनाया जा सकता है, और उसके बाद Codex implementation शुरू करे — यही flow मेरा इरादा है।

PR Review भी supported है

GitHub Actions आधारित SpecGuard PR Review workflow भी उपलब्ध है।

PR में जब spec package बदलता है, तब SpecGuard Review चलाकर उसका result PR में छोड़ने वाला flow है। यह feature OpenAI को call करके चलता है।

लक्ष्य “AI द्वारा बनाया गया code review” नहीं, बल्कि “AI को सौंपने से पहले spec input की review” है।

टीम में अगर आप इस तरह के नियम रखना चाहते हैं, तो इसका इस्तेमाल किया जा सकता है।

  • NOT_READY spec को implementation के लिए आगे न भेजना
  • Critical/Major findings को PR में पहले ही उजागर करना
  • implementation output नहीं, बल्कि requirement input quality को पहले manage करना

installation के लिए CLI में specguard actions install-pr-review इस्तेमाल किया जा सकता है, या Codex से @specguard SpecGuard PR Review workflow सेट कर दो. कहकर setup किया जा सकता है।

हालांकि, यह अभी experimental feature है, इसलिए automated setup supported नहीं है और GitHub Secret में नीचे की तरह setting करनी होगी।

SPECGUARD_OPENAI_API_KEY=sk-proj-xxxxxxxxxxxxxxxx  
SPECGUARD_PR_REVIEW_MODEL=gpt-5.4-nano  
SPECGUARD_REVIEW_SPEC_PATHS=specs/your-feature-name

वर्तमान स्थिति और सीमाएं

अभी यह शुरुआती version है, इसलिए हर spec का पूरी तरह सटीक आकलन करने वाला टूल नहीं है।

लेकिन अगर आप AI coding इस्तेमाल करते हुए “कमज़ोर spec की वजह से implementation बिगड़ने” जैसी समस्या झेल रहे हैं, तो implementation से पहले एक बार filter करने वाले safety check की तरह इसे आज़मा सकते हैं।

मैं feedback पाना चाहता हूँ। खासकर नीचे की बातें जानना चाहता हूँ।

  • किस तरह के spec पर यह अच्छा बैठता है
  • कौन-सी findings ज़्यादा हैं या कम हैं
  • Codex plugin flow वास्तव में उपयोगी है या नहीं
  • PR Review के ज़रिए enforce करना टीम workflow के अनुकूल है या नहीं

अभी यह beta version से भी पहले का, यानी development की शुरुआती अवस्था में है, लेकिन आगे इसे ऐसा project बनाना चाहता हूँ जो वास्तविक कामकाजी माहौल में पर्याप्त रूप से इस्तेमाल किया जा सके।

जिन लोगों की रुचि हो, उनके issues/PR भी स्वागतयोग्य हैं। फिलहाल repository के issues और PR मुख्य रूप से अंग्रेज़ी में manage होते हैं, लेकिन आप चाहें तो कोरियाई में भी लिख सकते हैं।

GitHub : https://github.com/KoreaNirsa/spec-guard

संबंधित पढ़ाई

1 टिप्पणियां

 
veltrix 6 일 전

इस प्रोजेक्ट के बारे में अधिक विस्तृत जानकारी आप https://nirsa.tistory.com/487 पर देख सकते हैं।