संदर्भ
विधि: GitHub
GitHub Actions से Holarch मॉडल जांच चलाएं और निष्कर्षों को GitHub issue के रूप में ट्रैक करें, और Claude Code को उन आवश्यकताओं के लिए टेस्ट केस प्रस्तावित करने दें जिन्हें कोई ब्रांच लागू करती है; सेटअप, वर्कफ़्लो फ़ाइल, एक पूरा उदाहरण और समस्या निवारण।
इस पृष्ठ पर
अवलोकन
यह रेसिपी एक GitHub रिपॉज़िटरी को एक Holarch प्रोजेक्ट से जोड़ती है। इसके दो हिस्से हैं:
- GitHub Actions में मॉडल जांच (REST API): एक शेड्यूल किया गया workflow प्रोजेक्ट की आवश्यकताओं पर Holarch की मॉडल जांच चलाता है। यह निष्कर्ष रन के सारांश में लिखता है और एक GitHub issue को उनके साथ अद्यतन रखता है।
- कोड समीक्षा में आवश्यकताएं (MCP, Claude Code के ज़रिए): Claude Code उस ब्रांच को पढ़ता है जिस पर आप काम कर रहे हैं, Holarch में वे आवश्यकताएं ढूंढता है जिन्हें वह लागू करती है, और उन्हें सत्यापित करने वाले टेस्ट केस प्रस्तावित करता है। कुछ भी बदलने से पहले आप Holarch में प्रस्ताव की समीक्षा करते हैं।
Holarch में कोई बिल्ट-इन GitHub ऐप नहीं है। रेसिपी REST API और MCP का उपयोग करती है, इसलिए आप हर चरण को अपने अनुसार ढाल सकते हैं।
पूर्वापेक्षाएं
- API और MCP वाला प्लान: Individual या Team, या Individual ट्रायल। Free प्लान पर सत्यापित शैक्षणिक ईमेल पते वाले या सक्रिय कक्षा संगठन के खाते के पास भी ये होते हैं (प्लान और सीमाएं)।
- एक Holarch प्रोजेक्ट। workflow इसे केवल पढ़ता है; Claude Code के प्रस्तावों के लिए संपादक या स्वामी की भूमिका चाहिए।
- एक GitHub रिपॉज़िटरी जहाँ आप Actions secrets और variables जोड़ सकते हैं, और जहाँ Actions issue बना सकते हैं।
- Claude वाले हिस्से के लिए: पढ़ें और परिवर्तन प्रस्तावित करें पहुँच के साथ Holarch से कनेक्ट किया गया Claude Code (Holarch को Claude से कनेक्ट करें)।
इसका उपयोग कैसे करें
कब और क्यों
मॉडल जांच मॉडल में कमियां ढूंढती है, जैसे बिना सत्यापन करने वाले टेस्ट केस की आवश्यकताएं। उन्हें शेड्यूल पर चलाने और निष्कर्षों को वहाँ ट्रैक करने से जहाँ टीम पहले से काम करती है, समीक्षाओं के बीच कमियां दिखती रहती हैं। Claude Code दूसरी ओर से चक्र पूरा करता है: जब कोड कोई आवश्यकता लागू करता है, तो वह उसे सत्यापित करने वाले टेस्ट केस का मसौदा बनाता है।
रिपॉज़िटरी सेट करें
- Holarch में प्रोजेक्ट तक सीमित एक केवल पढ़ें टोकन बनाएं: खाता सेटिंग्स → API टोकन → नया टोकन (टोकन बनाएं)।
- प्रोजेक्ट id ढूंढें:
GET /api/v1/projectsआपके प्रोजेक्ट को उनकेidके साथ सूचीबद्ध करता है।
curl -H "Authorization: Bearer hol_…" https://app.holarch.app/api/v1/projects
- GitHub में रिपॉज़िटरी की Settings → Secrets and variables → Actions खोलें:
- Secrets के अंतर्गत टोकन के साथ
HOLARCH_TOKENजोड़ें। - Variables के अंतर्गत प्रोजेक्ट id के साथ
HOLARCH_PROJECTजोड़ें।
- Secrets के अंतर्गत टोकन के साथ
- Issues → Labels के अंतर्गत लेबल
holarchबनाएं। workflow अपना issue ढूंढने के लिए इसका उपयोग करता है।
शेड्यूल पर मॉडल जांच चलाएं
यह फ़ाइल .github/workflows/holarch-checks.yml के रूप में सहेजें और उसे commit करें।
# Holarch Model Checks: requirement findings in the run summary and in one GitHub issue.
name: Holarch model checks
on:
schedule:
- cron: "0 6 * * 1-5" # weekdays at 06:00 UTC
workflow_dispatch:
permissions:
issues: write
jobs:
checks:
runs-on: ubuntu-latest
env:
HOLARCH_TOKEN: ${{ secrets.HOLARCH_TOKEN }}
HOLARCH_PROJECT: ${{ vars.HOLARCH_PROJECT }}
GH_TOKEN: ${{ github.token }}
GH_REPO: ${{ github.repository }}
steps:
- name: Run Model Checks
run: |
curl -sS --fail-with-body -H "Authorization: Bearer $HOLARCH_TOKEN" \
"https://app.holarch.app/api/v1/projects/$HOLARCH_PROJECT/model-checks?class=Requirement" > checks.json
jq -r '"Holarch Model Checks: \(.total) requirement findings\n",
(.issues[] | "- [ ] \(.rule) \(.entity.number) \(.entity.name): \(.heading)")' checks.json > findings.md
cat findings.md >> "$GITHUB_STEP_SUMMARY"
- name: Update the tracking issue
run: |
total=$(jq .total checks.json)
issue=$(gh issue list --label holarch --state open --json number --jq '.[0].number')
if [ "$total" -gt 0 ] && [ -z "$issue" ]; then
gh issue create --title "Holarch Model Checks findings" --label holarch --body-file findings.md
elif [ "$total" -gt 0 ]; then
gh issue edit "$issue" --body-file findings.md
elif [ -n "$issue" ]; then
gh issue close "$issue" --comment "Holarch Model Checks find no requirement issues."
fi
इसे अभी चलाने के लिए Actions → Holarch model checks → Run workflow खोलें।
आपको रन के सारांश में निष्कर्ष दिखते हैं, हर निष्कर्ष के लिए एक पंक्ति, जैसे Requirement.10 <number> <name>: Leaf requirements with no verifying test case। issue Holarch Model Checks findings में वही सूची होती है। निष्कर्ष ठीक होने पर अगला रन उसे बंद कर देता है।
यह कैसे काम करता है:
GET /api/v1/projects/<project>/model-checks?class=Requirementप्रोजेक्ट की अपनी नियम सेटिंग्स के साथ जांच चलाता है और निष्कर्ष लौटाता है:rule,heading,entity(id,number,name) और संबंधित आइटम। परिणाम लौटाए जाते हैं, संग्रहीत नहीं किए जाते।curl --fail-with-bodyत्रुटि होने पर चरण को विफल करता है और Holarch का संदेश छापता है, जैसे{"error": "…", "code": "token-invalid"}।ghऔरjqGitHub के Ubuntu runner के साथ आते हैं।
विविधताएं:
- अन्य नियम:
class=Requirementको किसी अन्य क्लास में बदलें (Test Case,Asset, अपने नियम सेट के लिएCustom), याrule=Requirement.10से एक नियम का नाम दें। - आवश्यकता की गुणवत्ता:
GET /api/v1/projects/<project>/qualityहर आवश्यकता को नौ गुणवत्ता एट्रिब्यूट पर स्कोर देता है। जिन आवश्यकताओं काscoreआपकी सीमा से नीचे है उन्हें इसी तरह सूचीबद्ध करें। - निष्कर्षों पर रन को विफल करें: अंतिम पंक्ति के रूप में
test "$total" -eq 0जोड़ें, उदाहरण के लिए किसी रिलीज़ ब्रांच की जांच में।
Claude Code से किसी ब्रांच के लिए टेस्ट केस प्रस्तावित करें
पुल रिक्वेस्ट खोलने से पहले इसका उपयोग करें, ताकि किसी परिवर्तन द्वारा लागू आवश्यकताओं को एक सत्यापन करने वाला टेस्ट केस मिले।
- Claude Code को एक बार Holarch से कनेक्ट करें:
claude mcp add --transport http holarch https://app.holarch.app/mcp
फिर /mcp टाइप करें, holarch → प्रमाणित करें चुनें, Holarch में साइन इन करें और पढ़ें और परिवर्तन प्रस्तावित करें के साथ अनुमति दें पर क्लिक करें।
- रिपॉज़िटरी में, अपनी ब्रांच पर, Claude Code से उदाहरण के लिए पूछें: "इस ब्रांच की तुलना main से करें। Holarch CubeSat प्रोजेक्ट में वे आवश्यकताएं ढूंढें जिन्हें यह परिवर्तन लागू करता है, और जिसका कोई सत्यापन करने वाला टेस्ट केस नहीं है उसके लिए एक टेस्ट केस प्रस्तावित करें। प्रस्ताव के सारांश में ब्रांच का नाम दें।"
- Claude Code git से diff पढ़ता है। Holarch में यह आवश्यकताएं ढूंढने के लिए
search_entitiesऔरget_entityका, और यह देखने के लिए कि किनका कोई सत्यापन करने वाला टेस्ट केस नहीं है, नियमRequirement.10के साथrun_model_checksका उपयोग करता है। यह हर टेस्ट केस कोcreate_entityऔर उसके verifies संबंध के साथ जोड़ता है, फिरpropose_changesसे प्रस्ताव भेजता है।Claude Code प्रस्ताव के शीर्षक और उसकी समीक्षा के लिंक के साथ उत्तर देता है।
- Holarch में ✦ AI ▾ → “<title>” की समीक्षा करें… खोलें, या घंटी के नीचे की सूचना।
- ज़रूरत हो तो नाम और विवरण संपादित करें, फिर चयनित लागू करें पर क्लिक करें।
टेस्ट केस इतिहास में आपके नाम के साथ बनते हैं, और एक ही बार पूर्ववत करने से सब वापस हो जाता है। अगला शेड्यूल किया गया workflow रन अब उन आवश्यकताओं को सूचीबद्ध नहीं करता।
आवश्यकता का लिंक पुल रिक्वेस्ट के विवरण में पेस्ट करें: get_entity और REST API इसे url के रूप में लौटाते हैं। यह प्रोजेक्ट के किसी भी सदस्य के लिए आवश्यकता खोलता है।
उदाहरण: CubeSat EO-1 डेमो
- प्रोजेक्ट प्रबंधित करें → प्रोजेक्ट फ़ाइलें ▾ → नया डेमो प्रोजेक्ट से डेमो बनाएं, और उसके id को
HOLARCH_PROJECTके रूप में उपयोग करें। - Run workflow से workflow चलाएं।
सारांश उन आवश्यकताओं को सूचीबद्ध करता है जिन्हें मॉडल जांच चिह्नित करती है, उदाहरण के लिए बिना सत्यापन करने वाले टेस्ट केस की leaf आवश्यकताएं। issue Holarch Model Checks findings वही सूचीबद्ध करता है।
- attitude control कोड बदलने वाली ब्रांच पर, Claude Code से उन आवश्यकताओं के लिए टेस्ट केस प्रस्तावित करने को कहें जिन्हें ब्रांच लागू करती है।
उस कोड की आवश्यकताएं 2.1 Pointing Accuracy और 2.2 Pointing Stability हैं। दोनों पहले से TC-04 Pointing Accuracy Test द्वारा सत्यापित हैं, इसलिए उन्हें किसी नए टेस्ट केस की ज़रूरत नहीं।
- इसके बजाय उससे issue की सूची की किसी आवश्यकता के लिए टेस्ट केस प्रस्तावित करने को कहें, फिर Holarch में प्रस्ताव की समीक्षा करके उसे लागू करें।
- workflow फिर से चलाएं।
वह आवश्यकता अब सूचीबद्ध नहीं है।
सुझाव
- workflow को उसका अपना केवल-पढ़ने वाला टोकन दें, प्रोजेक्ट तक सीमित। workflow हटाते समय उसे खाता सेटिंग्स → API टोकन के अंतर्गत रद्द करें।
- शेड्यूल किया गया workflow Holarch की नियम सेटिंग्स का उपयोग करता है: मॉडल जांच में कोई नियम बंद करें या उसका स्तर बदलें, और अगला रन उसका अनुसरण करता है।
- टोकन आपकी चुनी तिथि पर समाप्त होता है। workflow के लिए एक वर्ष या कभी नहीं चुनें, और तिथि नोट करें।
समस्या निवारण
| संदेश या लक्षण | कारण और समाधान |
|---|---|
"code": "token-required" | HOLARCH_TOKEN secret खाली है या मौजूद नहीं है। इसे Settings → Secrets and variables → Actions के अंतर्गत जोड़ें। |
"code": "token-invalid" | टोकन गलत, रद्द या समाप्त है। एक नया बनाएं और secret अपडेट करें। |
"code": "plan-api" | खाते के प्लान में API और MCP शामिल नहीं हैं। Individual ट्रायल शुरू करें या कोई प्लान चुनें; तब टोकन फिर से काम करता है। |
"code": "org-policy" | प्रोजेक्ट के संगठन ने API पहुँच बंद कर दी। किसी संगठन व्यवस्थापक से पूछें। |
"code": "not-found" | HOLARCH_PROJECT ऐसा प्रोजेक्ट नहीं है जिसका टोकन उपयोग कर सके। id, और टोकन की प्रोजेक्ट सेटिंग जांचें। |
"code": "rate-limited" | इस टोकन के साथ एक मिनट में 600 से अधिक अनुरोध। workflow कम बार चलाएं, या अन्य स्क्रिप्ट को उनके अपने टोकन दें। |
gh issue create विफल होता है: label not found | रिपॉज़िटरी में लेबल holarch बनाएं। |
gh HTTP 403 लौटाता है | workflow को permissions: issues: write चाहिए, और रिपॉज़िटरी की Actions सेटिंग्स को इसकी अनुमति देनी चाहिए। |
| Claude Code Holarch के लिखने वाले टूल नहीं देता | कनेक्शन केवल-पढ़ने वाला है। /mcp चलाएं, holarch को पढ़ें और परिवर्तन प्रस्तावित करें के साथ फिर से कनेक्ट करें, फिर नई बातचीत शुरू करें। |