हार्नेस इंजीनियरिंग की संपूर्ण गाइड | Claude Code से सीखें AI एजेंट बनाना

“ChatGPT को प्रॉम्प्ट भेज दो, बस”—वह दौर अब बीत चुका है। 2025 से AI इंजीनियरिंग का केंद्र तेज़ी से हार्नेस इंजीनियरिंग (harness engineering) की ओर खिसक गया है। Anthropic के आंतरिक ब्लॉग हों या OpenAI के एजेंट शोध, हर जगह यह शब्द बार-बार सामने आता है।

फिर भी “हार्नेस क्या है?” पूछने पर बहुत कम लोग साफ़ जवाब दे पाते हैं। इस लेख में हम चलते कोड और Claude Code की अपनी डिज़ाइन के ज़रिए हार्नेस इंजीनियरिंग को विस्तार से खोलते हैं। पढ़ने के बाद आप शून्य से अपना एजेंट बनाने की स्थिति में होंगे।

हार्नेस यानी AI का “ढांचा”

मूल रूप से “harness” का अर्थ है घोड़े की साज या सुरक्षा बेल्ट। सॉफ़्टवेयर में “टेस्ट हार्नेस” की तरह यह किसी चीज़ को चलाने के लिए बाहरी ढांचे को दर्शाता है।

AI के संदर्भ में हार्नेस मतलब LLM के चारों ओर का रैपर लेयर। ठोस रूप में कहें तो इसमें वह सब जुड़ा होता है जो LLM को वास्तविक कार्य करने के लिए चाहिए:

• टूल्स: फ़ाइल पढ़ना, कमांड चलाना, API कॉल करना आदि
• कॉन्टेक्स्ट प्रबंधन: क्या याद रखें, क्या भूलें, क्या दबाएँ
• कंट्रोल लूप: कब कॉल करें, कब रुकें, कब पुनः प्रयास करें
• अनुमतियाँ और सुरक्षा: विनाशकारी ऑपरेशन चुपचाप न हों
• मेमोरी: सत्रों के पार बनी रहने वाली जानकारी

प्रॉम्प्ट इस हार्नेस में जाने वाला एक इनपुट भर है। हार्नेस कमज़ोर है तो सबसे चतुर प्रॉम्प्ट भी प्रदर्शन की सीमा से नहीं टकरा पाता। इसी वजह से कहा जाने लगा है कि “अकेली प्रॉम्प्ट इंजीनियरिंग काफ़ी नहीं।“

हार्नेस क्यों ज़रूरी है: OODA लूप के नज़रिए से

अकेला LLM केवल “अगला टोकन बनाना” जानता है। वास्तविक कार्य हल करने के लिए सैन्य रणनीति का OODA लूप (Observe → Orient → Decide → Act) घुमाना पड़ता है।

चरण	काम	ज़िम्मेदार
Observe (अवलोकन)	वातावरण पढ़ना (फ़ाइल, DB)	हार्नेस
Orient (स्थिति समझना)	जानकारी को LLM के लिए सजाना	हार्नेस
Decide (निर्णय)	अगला कदम चुनना	LLM
Act (क्रिया)	कमांड/API पर अमल	हार्नेस

जैसा आप देख रहे हैं, चार में से तीन चरण हार्नेस के हैं। LLM केवल Decide में सशक्त है। चारों ओर का ढांचा जितना ठोस, एजेंट उतना ही गुणवत्तापूर्ण।

तीन स्तरों के उदाहरण

एक ही कार्य “ब्लॉग लेख बनाओ” को तीन बढ़ते स्तरों पर हल करते हैं।

स्तर 1: नंगी API कॉल (लगभग कोई हार्नेस नहीं)

import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic();

const res = await client.messages.create({
  model: "claude-opus-4-6",
  max_tokens: 4096,
  messages: [{ role: "user", content: "एक ब्लॉग लेख लिखो" }],
});
console.log(res.content[0].text);

नतीजा: सामान्य, खोखला टेक्स्ट। विषय और संरचना हर बार अलग।

स्तर 2: टूल देना (मध्यम हार्नेस)

const tools = [
  {
    name: "read_existing_posts",
    description: "मौजूदा ब्लॉग लेखों की सूची और शीर्षक लौटाना",
    input_schema: { type: "object", properties: {} },
  },
  {
    name: "write_post",
    description: "MDX फ़ाइल लिखना",
    input_schema: {
      type: "object",
      properties: {
        slug: { type: "string" },
        frontmatter: { type: "object" },
        body: { type: "string" },
      },
      required: ["slug", "frontmatter", "body"],
    },
  },
];

async function runAgent(userGoal: string) {
  let messages = [{ role: "user", content: userGoal }];
  while (true) {
    const res = await client.messages.create({
      model: "claude-opus-4-6",
      max_tokens: 4096,
      tools,
      messages,
    });
    if (res.stop_reason === "end_turn") break;

    // हार्नेस टूल कॉल निष्पादित करता है
    const toolUse = res.content.find((c) => c.type === "tool_use");
    const result = await executeTool(toolUse.name, toolUse.input);
    messages.push({ role: "assistant", content: res.content });
    messages.push({
      role: "user",
      content: [{ type: "tool_result", tool_use_id: toolUse.id, content: result }],
    });
  }
}

नतीजा: गैर-डुप्लिकेट विषय चुना जाता है और सही प्रारूप की MDX बनती है। टूल जोड़ते ही गुणवत्ता बदल जाती है।

स्तर 3: Claude Code स्तर का पूर्ण हार्नेस

• स्वचालित लूप (उपयोगकर्ता स्वीकृति, त्रुटि पुनः प्रयास)
• कॉन्टेक्स्ट संकुचन (लंबी वार्ता को सारांशित करके टोकन बचाना)
• सब-एजेंट सौंपाव (अनुवाद अलग कॉन्टेक्स्ट में)
• प्रॉम्प्ट कैशिंग (स्थिर भाग दोबारा न भेजना)
• हुक्स (कमिट से पहले ऑटो-लिंट)

यह सब स्वयं जोड़ना बड़ा प्रोजेक्ट है। इसीलिए Claude Code को “रेफरेंस इम्प्लीमेंटेशन” की तरह पढ़ना मूल्यवान है।

Claude Code के हार्नेस की परतें

Claude Code Anthropic के भीतर सबसे परिष्कृत एजेंट हार्नेस है। इसे पाँच परतों में समझा जा सकता है।

परत 1: टूल डिज़ाइन

Read, Edit, Write, Bash, Glob, Grep, Agent आदि तैयार मिलते हैं। ध्यान देने योग्य बात है उनकी ग्रेन्युलैरिटी:

• Grep साधारण grep नहीं बल्कि ripgrep का रैपर है — सटीक और तेज़
• Edit पूरी फ़ाइल नहीं लिखता, बल्कि निश्चित स्ट्रिंग बदलता है — न्यूनतम डिफ़
• Agent सब-एजेंट उत्पन्न करता है जिसका कॉन्टेक्स्ट अलग होता है

टूल की गुणवत्ता सीधे एजेंट की गुणवत्ता बनाती है। “जैसे-तैसे चल जाए” काफ़ी नहीं। आइडेम्पोटेंसी, स्पष्ट त्रुटि संदेश और एकल ज़िम्मेदारी को ध्यान में रखकर टूल डिज़ाइन करें।

परत 2: कॉन्टेक्स्ट की श्रेणी

~/.claude/CLAUDE.md         ← वैश्विक नियम
./CLAUDE.md                 ← प्रोजेक्ट नियम (स्वतः लोड)
~/.claude/memory/           ← दीर्घकालिक स्मृति (सत्रों के पार)
  ├── user_profile.md
  ├── feedback_xxx.md
  └── project_xxx.md
संवाद इतिहास                 ← हालिया आदान-प्रदान
कार्य/योजना                  ← वर्तमान सत्र की प्रगति

हर परत की आयु और भूमिका अलग है। ग़लत जगह लिखने पर जानकारी तुरंत खो जाती है या पुरानी जानकारी टिकी रह जाती है। “सिर्फ़ इसी सत्र के लिए” = कार्य, “बार-बार चाहिए” = मेमोरी।

परत 3: सब-एजेंट सौंपाव

Agent टूल से अलग कॉन्टेक्स्ट का एजेंट स्पॉन किया जा सकता है।

# मुख्य एजेंट केवल निर्देश दे, भारी काम सब-एजेंट करे
Agent(
  subagent_type: "general-purpose",
  prompt: "blog/harness.mdx को अंग्रेज़ी + 8 भाषाओं में अनुवाद करो,
           प्रत्येक को blog-{lang}/ में सहेजो, फिर रिपोर्ट दो"
)

इससे मुख्य कॉन्टेक्स्ट विस्तृत लॉग से गंदा नहीं होता। लंबे बिल्ड लॉग, अनुवाद के बीच-बीच के नतीजे, खोज परिणाम — जहाँ सिर्फ़ अंतिम परिणाम चाहिए, वह सौंप दें।

परत 4: हुक्स (नियतात्मक प्रक्रियाएँ)

.claude/settings.json से टूल कॉल के पहले/बाद शेल कमांड डाली जा सकती है।

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "npx tsc --noEmit" }
        ]
      }
    ]
  }
}

फ़ाइल संपादन के बाद स्वचालित टाइप-चेक चलता है। “हर बार LLM से कहने के बजाय नियतात्मक ढंग से हो जाना चाहिए” वाले कार्य हुक में सौंपें।

परत 5: अनुमति मोड

{
  "permissions": {
    "allow": ["Read", "Grep", "Glob"],
    "deny": ["Bash(rm -rf*)", "Bash(git push --force*)"],
    "ask": ["Write", "Edit", "Bash"]
  }
}

विनाशकारी कमांड स्पष्ट रूप से मना करें, लेखन पर पुष्टि माँगें। हादसे तभी होते हैं जब कुछ बिना निगरानी चल जाए — इसलिए यह परत संचालन सुरक्षा तय करती है।

पाँच सामान्य जाल

1. बहुत ज़्यादा टूल 30 टूल देने पर मॉडल चुनाव में उलझ जाता है, सटीकता गिरती है। नियम: 5–15। बाकी क्षमताएँ सब-एजेंट को दें।

2. प्रॉम्प्ट कैश का उपयोग न करना Claude API के cache_control के बिना, लंबा system prompt हर बार पूरा भेजा जाता है और खर्च बढ़ता है। 5 मिनट की TTL ध्यान में रखें और स्थिर भाग को कैश करें।

messages: [{
  role: "system",
  content: [
    { type: "text", text: longStaticInstructions,
      cache_control: { type: "ephemeral" } },   // ← यही
    { type: "text", text: dynamicContext },
  ],
}]

3. त्रुटि संदेश जो LLM नहीं पढ़ सकता टूल केवल Error: undefined लौटाए, तो मॉडल खुद को सुधार नहीं पाता। लिखें कि क्या ग़लत है और कैसे ठीक करें।

throw new Error(
  `फ़ाइल '${path}' मौजूद नहीं है। ` +
  `scripts/ में मौजूद फ़ाइलें: ${list.join(", ")}`
);

4. मानवीय अनुमोदन छोड़ना विनाशकारी क्रियाएँ (डिलीट, force push, DB अपडेट) स्वतः अनुमोदित करने पर किसी दिन हादसा होगा ही। डिफ़ॉल्ट: लेखन पर पूछें, डिलीट पर मना।

5. मेमोरी की सफ़ाई न करना पुरानी जानकारी बनी रहने पर एजेंट ग़लत मान्यताओं पर चलता है। मेमोरी को भी नियमित रूप से साफ़ करना ज़रूरी है (Claude Code में /compact या हाथ से संपादन)।

अपना मिनी-हार्नेस चलाएँ

अंत में, Node.js + TypeScript में एक न्यूनतम हार्नेस।

// mini-harness.ts
import Anthropic from "@anthropic-ai/sdk";
import { readFileSync, writeFileSync } from "fs";

const client = new Anthropic();

const tools = [
  { name: "read_file",
    description: "टेक्स्ट फ़ाइल पढ़ें",
    input_schema: { type: "object", properties: { path: { type: "string" } }, required: ["path"] } },
  { name: "write_file",
    description: "टेक्स्ट फ़ाइल लिखें",
    input_schema: { type: "object", properties: { path: { type: "string" }, content: { type: "string" } }, required: ["path", "content"] } },
];

const executors = {
  read_file: ({ path }) => readFileSync(path, "utf-8"),
  write_file: ({ path, content }) => { writeFileSync(path, content); return `written ${path}`; },
};

async function loop(goal: string, maxSteps = 10) {
  const messages: any[] = [{ role: "user", content: goal }];
  for (let i = 0; i < maxSteps; i++) {
    const res = await client.messages.create({
      model: "claude-opus-4-6", max_tokens: 4096, tools, messages,
    });
    messages.push({ role: "assistant", content: res.content });
    if (res.stop_reason === "end_turn") return res.content;

    const toolUse = res.content.find((c: any) => c.type === "tool_use") as any;
    if (!toolUse) return res.content;
    const result = executors[toolUse.name](toolUse.input);
    messages.push({
      role: "user",
      content: [{ type: "tool_result", tool_use_id: toolUse.id, content: String(result) }],
    });
  }
}

await loop("README.md पढ़ो और 3 पंक्तियों का सारांश TL;DR.md में सहेजो");

इतने भर से आपका मिनी-एजेंट मौजूदा फ़ाइल पढ़ सकता है और नई फ़ाइल लिख सकता है। इसमें Grep, Bash, Agent टूल जोड़ते जाइए और एक लघु Claude Code तैयार है।

निष्कर्ष: प्रॉम्प्ट लेखक से हार्नेस डिज़ाइनर तक

पुराना नज़रिया	नया नज़रिया
अच्छा प्रॉम्प्ट = अच्छा आउटपुट	अच्छा हार्नेस = अच्छा आउटपुट
मॉडल चुनना	मॉडल + टूल + कॉन्टेक्स्ट + अनुमति डिज़ाइन
एकल प्रश्न	सतत लूप संचालन

यह बदलाव महसूस करने के लिए Claude Code सर्वोत्तम पाठ है। केवल उपयोग न करें — उसकी रचना खोलकर अपने एजेंट में उतारें। 2026 और आगे के AI इंजीनियरों के लिए यही अपेक्षित मनोवृत्ति है।

पहले ऊपर का मिनी-हार्नेस कॉपी-पेस्ट करके चलाइए। दस मिनट बाद आपने अपने निजी एजेंट की पहली सीढ़ी चढ़ ली होगी।

संबंधित लेख

• Claude Code के सब-एजेंट के 10 पैटर्न
• CLAUDE.md सर्वोत्तम अभ्यास
• Claude Code टोकन अनुकूलन तकनीकें
• Claude Code अनुमति सेटिंग गाइड

संदर्भ सामग्री

• Anthropic Agent SDK आधिकारिक दस्तावेज़
• Claude Code आधिकारिक गाइड
• Prompt Caching गाइड