चीट शीट

AI एजेंट के हार्नेस की शॉर्टकट शीट: हिस्से, फ़ाइलें, समस्याएँ और शुरुआत की चेकलिस्ट

अपडेट किया गया: · Skillaria.Top

AI एजेंट का हार्नेस पाँच हिस्सों से बनता है: निर्देश, उपकरण, वातावरण, स्थिति और फ़ीडबैक। न्यूनतम फ़ाइलें हैं: AGENTS.md एक छोटे रूटर के रूप में, जाँच की स्क्रिप्ट (make check, verify.sh), प्रगति की फ़ाइल और स्थिति वाली फ़ीचर-सूची। तैयारी का निशान स्क्रिप्ट लगाती है, एजेंट नहीं।

AI एजेंट के हार्नेस के पाँच हिस्से

हिस्सायह क्या हैकलाकृतियाँटूटने का लक्षण
निर्देशएजेंट को प्रोजेक्ट के बारे में क्या जानना चाहिएAGENTS.md / CLAUDE.md, skills, docs/, ADRज्ञात परंपराएँ तोड़ता है
उपकरणएजेंट क्या कर सकता हैshell, टेस्ट, linter, ब्राउज़र, MCP सर्वर"करना चाहता है, कर नहीं सकता"
वातावरणएजेंट कहाँ काम करता हैlock files, Docker/devcontainer, git worktree, sandbox, init.shसत्र वातावरण ठीक करने से शुरू होता है
स्थितिक्या restart के बाद भी बचता हैPROGRESS.md, DECISIONS.md, feature_list.json, commitsनया सत्र नहीं जानता कि कहाँ रुके थे
फ़ीडबैकएजेंट को अपनी गलती कैसे पता चलती हैmake check, E2E, hooks, arch-check, मूल्यांकक"तैयार", पर काम नहीं करता

शून्य से लगाने का क्रम: फ़ीडबैक → निर्देश → स्थिति → वातावरण → उपकरण।

हार्नेस की फ़ाइलें

फ़ाइलकामनियम
AGENTS.md / CLAUDE.mdप्रवेश बिंदु: प्रोजेक्ट क्या है, कैसे चलाएँ, कैसे जाँचेंछोटा रूटर (लगभग 80 पंक्तियाँ), "कब पढ़ें" की शर्त वाले दस्तावेज़ों के लिंक
docs/*.mdविषयों के विवरणज़रूरत पर पढ़े जाते हैं, पूरे नहीं
.claude/skills/*/SKILL.mdदोहराए जाने वाले तरीक़े (deploy, review)काम का विवरण मेल खाए तो लोड होते हैं
PROGRESS.mdस्थिति, किया गया, रुकावटें, अगले कदमहर सत्र के अंत में अपडेट करें
DECISIONS.mdफ़ैसला, कारण, ख़ारिज विकल्पकेवल नतीजा नहीं, रास्ता भी लिखें
feature_list.jsonफ़ीचर: behavior, verification, stateठीक एक फ़ीचर active (WIP=1)
scripts/verify.shफ़ीचर की जाँच और passing में बदलनाअकेला जो passing लगाता है, commit SHA के साथ
scripts/arch-check.shआर्किटेक्चर की सीमाएँबाहर निकलने का कोड 1 + आउटपुट में WHY और FIX
scripts/init.shकाम से पहले वातावरण की जाँचवातावरण, साफ़ git, हरा make check, सक्रिय फ़ीचर
sprint contractकोड से पहले फ़ीचर का अनुबंधदायरे में / दायरे से बाहर / खुले सवाल
.claude/settings.jsonClaude Code की अनुमतियाँ और hooksजाँच घटनाओं पर हो, एजेंट की याददाश्त पर नहीं

AGENTS.md का ढाँचा

# प्रोजेक्ट: payment backend (FastAPI, PostgreSQL)

## चलाना
docker compose up -d && ./scripts/init.sh

## जाँच
make check   # lint, types, unit, arch-check
make e2e     # end-to-end परिदृश्य

## Definition of Done
- make check और make e2e — कोड 0
- फ़ीचर scripts/verify.sh से passing किया गया
- PROGRESS.md अपडेट

## MUST
- database के अनुरोध केवल repositories से
- secrets केवल environment variables से

## दस्तावेज़
- docs/payments.md — जब काम भुगतान और रिफ़ंड से जुड़ा हो
- docs/migrations.md — जब database schema बदले

फ़ीचर की स्थितियाँ

स्थितिअर्थकौन बदलता है
pendingकतार मेंयोजनाकार
activeकाम जारी (केवल एक)शुरू करते समय एजेंट
passingजाँच पास हुईकेवल verify.sh
blockedइंसान का फ़ैसला चाहिएएजेंट, कारण के साथ

सत्यापन के स्तर

स्तरक्याकब
1Lint, typesहमेशा
2Unit और integration testsहमेशा
3E2Eएक से ज़्यादा परत प्रभावित हो; "तैयार" से पहले
4arch-checkनए परतों के पार imports

"तैयार" का अधिकार केवल सबसे ऊपरी स्तर के बाद। हरे unit tests तैयारी नहीं हैं।

नियमों का तंत्र

स्तरउपकरणलागत
grep-guardpattern खोजने वाली स्क्रिप्ट, WHY/FIX संदेश के साथमिनट
Linter नियमimport-linter (Python), dependency-cruiser, eslint-plugin-boundaries (JS/TS)एक घंटा
आर्किटेक्चर टेस्टCI में टेस्ट, जो परतें टूटने पर विफल होज़्यादा, पर make check में दिखता है
 
#!/usr/bin/env bash
fail=0
if grep -rn "from app.db" app/services/; then
  echo "WHY: services database से सीधे बात नहीं करतीं"
  echo "FIX: app/repositories/ का repository उपयोग करें"
  fail=1
fi
exit $fail

आम समस्याएँ और समाधान

समस्याहिस्सासमाधान
CLAUDE.md का नियम नहीं माना जातानिर्देशफ़ाइल छोटी करें, नियम को जाँच या hook में बदलें
एजेंट टेस्ट नहीं चला सकताउपकरणकमांड की अनुमति दें, dependencies image में डालें
अलग मशीनों पर अलग व्यवहारवातावरणlock files, Docker/devcontainer, runtime के तय संस्करण
सत्रों के बीच भूलनास्थितिPROGRESS.md, session handoff, सत्र की शुरुआत में पढ़ना
तीन फ़ीचर शुरू, एक भी पूरा नहींस्थितिfeature_list.json में WIP=1
"तैयार", पर काम नहीं करताफ़ीडबैकDoD, E2E, verify.sh, स्वतंत्र मूल्यांकक
टेस्ट हरे, फ़ीचर टूटाफ़ीडबैकअसली database और configuration वाला E2E
एजेंट बुरे पैटर्न कॉपी करता हैफ़ीडबैकपहले ही दिन से arch-check
समझ नहीं आता कि एजेंट ने क्या कियास्थितिछोटे commits, PROGRESS.md और DECISIONS.md की रिपोर्ट
एजेंट ने रात में वातावरण बिगाड़ावातावरणsandbox, git worktree, checkpoints, init.sh से वापसी
रिव्यू में एक ही टिप्पणी दो बारपूरा हार्नेसmake check में जाँच बनाएँ, टेक्स्ट निर्देशों से हटाएँ

लंबे कामों की भूमिकाएँ

भूमिकाक्या करती हैक्या नहीं करती
योजनाकारस्वीकृति-मानदंड वाले फ़ीचरकोड नहीं लिखता
जनरेटरएक फ़ीचर लागू करता है, टेस्ट चलाता हैतय नहीं करता कि काम तैयार है
मूल्यांककरूब्रिक पर फ़ैसला, फ़ाइल, पंक्ति, लॉग के हवाले के साथजनरेटर का तर्क नहीं देखता
Mergereview == pass पर commitयह कोड है, एजेंट नहीं

स्वायत्त काम का बजट

  • लक्ष्य एक वाक्य में (जैसे सभी फ़ीचर passing करना)।
  • WIP=1, प्रति फ़ीचर समय और प्रयासों की सीमा।
  • मेट्रिक केवल बढ़े, गिरावट पर तुरंत rollback।
  • Migrations, infrastructure, पैसा: इंसान को एस्केलेशन।
  • कई असफल रिव्यू के बाद फ़ीचर साफ़ context से दोबारा शुरू।

एजेंट शुरू करने की चेकलिस्ट

  1. AGENTS.md है: स्टैक, चलाने का तरीक़ा, जाँच की कमांड, DoD।
  2. make check साफ़ clone पर पास होता है।
  3. वातावरण दोहराने योग्य है: lock files, Docker या devcontainer।
  4. एजेंट को ज़रूरी कमांड उपलब्ध हैं, ख़तरनाक कमांड बंद या sandbox में।
  5. कम से कम मुख्य परिदृश्य के लिए E2E है।
  6. PROGRESS.md है और सत्र की शुरुआत में उसे पढ़ने का नियम है।
  7. फ़ीचर सूची में स्थितियाँ हैं, सक्रिय केवल एक।
  8. passing का निशान स्क्रिप्ट लगाती है।
  9. जाँच के संदेशों में WHY और FIX हैं।
  10. काम स्वीकृति-मानदंड और दायरे की सीमाओं के साथ लिखा है।
  11. तय है कि क्या इंसान के फ़ैसले पर छोड़ना है।
  12. बदलावों से पहले verification gap गिना गया है, ताकि तुलना हो सके।

हार्नेस की मेट्रिक्स

मेट्रिककैसे गिनें
Verification gap10 कामों पर, "तैयार" कहे गए पर जाँच से अपुष्ट कामों का अनुपात
MTTRटूटने से कार्यशील स्थिति वापस आने तक का समय
कोल्ड स्टार्टक्या नया सत्र "हम कहाँ हैं, आगे क्या" बिना अंदाज़े के बता सकता है
Ablationएक हिस्सा बंद करने पर स्थिर कामों के सेट पर गिरावट

सार

हार्नेस एक फ़ाइल नहीं, एक चक्र है: निर्देश, उपकरण, वातावरण, स्थिति और फ़ीडबैक। जाँच से शुरू करें, AGENTS.md को छोटा रखें, तैयारी का निशान स्क्रिप्ट को दें और हार्नेस की नियमित समीक्षा करें। यह सब एक असली परियोजना पर, एक ही हार्नेस में जोड़कर, व्यावहारिक पाठ्यक्रम में सिखाया जाता है।

अक्सर पूछे जाने वाले प्रश्न

AGENTS.md और CLAUDE.md में क्या फ़र्क है?

उद्देश्य एक ही है: एजेंट के लिए निर्देश की फ़ाइल। CLAUDE.md Claude Code पढ़ता है, AGENTS.md कई एजेंटों का साझा फ़ॉर्मेट है। CLAUDE.md में केवल <code>@AGENTS.md</code> लिखकर उसे जोड़ा जा सकता है।

AGENTS.md में कितनी पंक्तियाँ होनी चाहिए?

कोई कठोर सीमा नहीं, पर प्रवेश फ़ाइल छोटी रखें, लगभग सौ पंक्तियों की, विषय-सूची की तरह। विवरण अलग दस्तावेज़ों में।

क्या छोटे प्रोजेक्ट में feature_list.json चाहिए?

एक बार के छोटे बदलावों के लिए नहीं। यह तब फ़ायदेमंद है जब एजेंट एक के बाद एक कई फ़ीचर पर या कई सत्रों में काम करे।

एजेंट को चाहिए गोपनीय जानकारी कहाँ रखें?

environment variables में या secrets manager में, निर्देश फ़ाइलों और कोड में नहीं। एजेंट को वातावरण तक पहुँच दें, मान टेक्स्ट में न दें।

इस विषय को वीडियो में सीखें

यह विषय “Harness Engineering: инженерия надёжности AI-агентов” कोर्स में अभ्यास के साथ विस्तार से समझाया गया है।

कोर्स पर जाएँ